logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

pthread_join.3p (6635B)


  1. '\" et
  2. .TH PTHREAD_JOIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pthread_join
  12. \(em wait for thread termination
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <pthread.h>
  17. .P
  18. int pthread_join(pthread_t \fIthread\fP, void **\fIvalue_ptr\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpthread_join\fR()
  23. function shall suspend execution of the calling thread until the target
  24. .IR thread
  25. terminates, unless the target
  26. .IR thread
  27. has already terminated. On return from a successful
  28. \fIpthread_join\fR()
  29. call with a non-NULL
  30. .IR value_ptr
  31. argument, the value passed to
  32. \fIpthread_exit\fR()
  33. by the terminating thread shall be made available in the location
  34. referenced by
  35. .IR value_ptr .
  36. When a
  37. \fIpthread_join\fR()
  38. returns successfully, the target thread has been terminated. The
  39. results of multiple simultaneous calls to
  40. \fIpthread_join\fR()
  41. specifying the same target thread are undefined. If the thread calling
  42. \fIpthread_join\fR()
  43. is canceled, then the target thread shall not be detached.
  44. .P
  45. It is unspecified whether a thread that has exited but remains unjoined
  46. counts against
  47. {PTHREAD_THREADS_MAX}.
  48. .P
  49. The behavior is undefined if the value specified by the
  50. .IR thread
  51. argument to
  52. \fIpthread_join\fR()
  53. does not refer to a joinable thread.
  54. .P
  55. The behavior is undefined if the value specified by the
  56. .IR thread
  57. argument to
  58. \fIpthread_join\fR()
  59. refers to the calling thread.
  60. .SH "RETURN VALUE"
  61. If successful, the
  62. \fIpthread_join\fR()
  63. function shall return zero; otherwise, an error number shall be
  64. returned to indicate the error.
  65. .SH ERRORS
  66. The
  67. \fIpthread_join\fR()
  68. function may fail if:
  69. .TP
  70. .BR EDEADLK
  71. A deadlock was detected.
  72. .P
  73. The
  74. \fIpthread_join\fR()
  75. function shall not return an error code of
  76. .BR [EINTR] .
  77. .LP
  78. .IR "The following sections are informative."
  79. .SH EXAMPLES
  80. An example of thread creation and deletion follows:
  81. .sp
  82. .RS 4
  83. .nf
  84. typedef struct {
  85. int *ar;
  86. long n;
  87. } subarray;
  88. .P
  89. void *
  90. incer(void *arg)
  91. {
  92. long i;
  93. .P
  94. for (i = 0; i < ((subarray *)arg)->n; i++)
  95. ((subarray *)arg)->ar[i]++;
  96. }
  97. .P
  98. int main(void)
  99. {
  100. int ar[1000000];
  101. pthread_t th1, th2;
  102. subarray sb1, sb2;
  103. .P
  104. sb1.ar = &ar[0];
  105. sb1.n = 500000;
  106. (void) pthread_create(&th1, NULL, incer, &sb1);
  107. .P
  108. sb2.ar = &ar[500000];
  109. sb2.n = 500000;
  110. (void) pthread_create(&th2, NULL, incer, &sb2);
  111. .P
  112. (void) pthread_join(th1, NULL);
  113. (void) pthread_join(th2, NULL);
  114. return 0;
  115. }
  116. .fi
  117. .P
  118. .RE
  119. .SH "APPLICATION USAGE"
  120. None.
  121. .SH RATIONALE
  122. The
  123. \fIpthread_join\fR()
  124. function is a convenience that has proven useful in multi-threaded
  125. applications. It is true that a programmer could simulate this
  126. function if it were not provided by passing extra state as part of the
  127. argument to the
  128. \fIstart_routine\fR().
  129. The terminating thread would set a flag to indicate termination and
  130. broadcast a condition that is part of that state; a joining thread
  131. would wait on that condition variable. While such a technique would
  132. allow a thread to wait on more complex conditions (for example, waiting
  133. for multiple threads to terminate), waiting on individual thread
  134. termination is considered widely useful. Also, including the
  135. \fIpthread_join\fR()
  136. function in no way precludes a programmer from coding such complex
  137. waits. Thus, while not a primitive, including
  138. \fIpthread_join\fR()
  139. in this volume of POSIX.1\(hy2017 was considered valuable.
  140. .P
  141. The
  142. \fIpthread_join\fR()
  143. function provides a simple mechanism allowing an application to wait
  144. for a thread to terminate. After the thread terminates, the
  145. application may then choose to clean up resources that were used by the
  146. thread. For instance, after
  147. \fIpthread_join\fR()
  148. returns, any application-provided stack storage could be reclaimed.
  149. .P
  150. The
  151. \fIpthread_join\fR()
  152. or
  153. \fIpthread_detach\fR()
  154. function should eventually be called for every thread that is created
  155. with the
  156. .IR detachstate
  157. attribute set to PTHREAD_CREATE_JOINABLE
  158. so that storage associated with the thread may be reclaimed.
  159. .P
  160. The interaction between
  161. \fIpthread_join\fR()
  162. and cancellation is well-defined for the following reasons:
  163. .IP " *" 4
  164. The
  165. \fIpthread_join\fR()
  166. function, like all other non-async-cancel-safe functions, can only be
  167. called with
  168. deferred cancelability type.
  169. .IP " *" 4
  170. Cancellation cannot occur in the disabled cancelability state.
  171. .P
  172. Thus, only the default cancelability state need be considered. As
  173. specified, either the
  174. \fIpthread_join\fR()
  175. call is canceled, or it succeeds, but not both. The difference is
  176. obvious to the application, since either a cancellation handler is run
  177. or
  178. \fIpthread_join\fR()
  179. returns. There are no race conditions since
  180. \fIpthread_join\fR()
  181. was called in the deferred cancelability state.
  182. .P
  183. If an implementation detects that the value specified by the
  184. .IR thread
  185. argument to
  186. \fIpthread_join\fR()
  187. does not refer to a joinable thread, it is recommended that the
  188. function should fail and report an
  189. .BR [EINVAL]
  190. error.
  191. .P
  192. If an implementation detects that the value specified by the
  193. .IR thread
  194. argument to
  195. \fIpthread_join\fR()
  196. refers to the calling thread, it is recommended that the function
  197. should fail and report an
  198. .BR [EDEADLK]
  199. error.
  200. .P
  201. If an implementation detects use of a thread ID after the end of its
  202. lifetime, it is recommended that the function should fail and report an
  203. .BR [ESRCH]
  204. error.
  205. .SH "FUTURE DIRECTIONS"
  206. None.
  207. .SH "SEE ALSO"
  208. .IR "\fIpthread_create\fR\^(\|)",
  209. .IR "\fIwait\fR\^(\|)"
  210. .P
  211. The Base Definitions volume of POSIX.1\(hy2017,
  212. .IR "Section 4.12" ", " "Memory Synchronization",
  213. .IR "\fB<pthread.h>\fP"
  214. .\"
  215. .SH COPYRIGHT
  216. Portions of this text are reprinted and reproduced in electronic form
  217. from IEEE Std 1003.1-2017, Standard for Information Technology
  218. -- Portable Operating System Interface (POSIX), The Open Group Base
  219. Specifications Issue 7, 2018 Edition,
  220. Copyright (C) 2018 by the Institute of
  221. Electrical and Electronics Engineers, Inc and The Open Group.
  222. In the event of any discrepancy between this version and the original IEEE and
  223. The Open Group Standard, the original IEEE and The Open Group Standard
  224. is the referee document. The original Standard can be obtained online at
  225. http://www.opengroup.org/unix/online.html .
  226. .PP
  227. Any typographical or formatting errors that appear
  228. in this page are most likely
  229. to have been introduced during the conversion of the source files to
  230. man page format. To report such errors, see
  231. https://www.kernel.org/doc/man-pages/reporting_bugs.html .