1PTHREAD_JOIN(3P) POSIX Programmer's Manual PTHREAD_JOIN(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 pthread_join — wait for thread termination
13
15 #include <pthread.h>
16 int pthread_join(pthread_t thread, void **value_ptr);
18
20 The pthread_join() function shall suspend execution of the calling
21 thread until the target thread terminates, unless the target thread has
22 already terminated. On return from a successful pthread_join() call
23 with a non-NULL value_ptr argument, the value passed to pthread_exit()
24 by the terminating thread shall be made available in the location ref‐
25 erenced by value_ptr. When a pthread_join() returns successfully, the
26 target thread has been terminated. The results of multiple simultaneous
27 calls to pthread_join() specifying the same target thread are unde‐
28 fined. If the thread calling pthread_join() is canceled, then the tar‐
29 get thread shall not be detached.
30 It is unspecified whether a thread that has exited but remains unjoined
32 counts against {PTHREAD_THREADS_MAX}.
33 The behavior is undefined if the value specified by the thread argument
35 to pthread_join() does not refer to a joinable thread.
36 The behavior is undefined if the value specified by the thread argument
38 to pthread_join() refers to the calling thread.
39
41 If successful, the pthread_join() function shall return zero; other‐
42 wise, an error number shall be returned to indicate the error.
43
45 The pthread_join() function may fail if:
46 EDEADLK
48 A deadlock was detected.
49 The pthread_join() function shall not return an error code of [EINTR].
51 The following sections are informative.
53
55 An example of thread creation and deletion follows:
56 typedef struct {
59 int *ar;
60 long n;
61 } subarray;
62 void *
64 incer(void *arg)
65 {
66 long i;
67 for (i = 0; i < ((subarray *)arg)->n; i++)
69 ((subarray *)arg)->ar[i]++;
70 }
71 int main(void)
73 {
74 int ar[1000000];
75 pthread_t th1, th2;
76 subarray sb1, sb2;
77 sb1.ar = &ar[0];
79 sb1.n = 500000;
80 (void) pthread_create(&th1, NULL, incer, &sb1);
81 sb2.ar = &ar[500000];
83 sb2.n = 500000;
84 (void) pthread_create(&th2, NULL, incer, &sb2);
85 (void) pthread_join(th1, NULL);
87 (void) pthread_join(th2, NULL);
88 return 0;
89 }
90
92 None.
93
95 The pthread_join() function is a convenience that has proven useful in
96 multi-threaded applications. It is true that a programmer could simu‐
97 late this function if it were not provided by passing extra state as
98 part of the argument to the start_routine(). The terminating thread
99 would set a flag to indicate termination and broadcast a condition that
100 is part of that state; a joining thread would wait on that condition
101 variable. While such a technique would allow a thread to wait on more
102 complex conditions (for example, waiting for multiple threads to termi‐
103 nate), waiting on individual thread termination is considered widely
104 useful. Also, including the pthread_join() function in no way precludes
105 a programmer from coding such complex waits. Thus, while not a primi‐
106 tive, including pthread_join() in this volume of POSIX.1‐2017 was con‐
107 sidered valuable.
108 The pthread_join() function provides a simple mechanism allowing an
110 application to wait for a thread to terminate. After the thread termi‐
111 nates, the application may then choose to clean up resources that were
112 used by the thread. For instance, after pthread_join() returns, any
113 application-provided stack storage could be reclaimed.
114 The pthread_join() or pthread_detach() function should eventually be
116 called for every thread that is created with the detachstate attribute
117 set to PTHREAD_CREATE_JOINABLE so that storage associated with the
118 thread may be reclaimed.
119 The interaction between pthread_join() and cancellation is well-defined
121 for the following reasons:
122 * The pthread_join() function, like all other non-async-cancel-safe
124 functions, can only be called with deferred cancelability type.
125 * Cancellation cannot occur in the disabled cancelability state.
127 Thus, only the default cancelability state need be considered. As spec‐
129 ified, either the pthread_join() call is canceled, or it succeeds, but
130 not both. The difference is obvious to the application, since either a
131 cancellation handler is run or pthread_join() returns. There are no
132 race conditions since pthread_join() was called in the deferred cance‐
133 lability state.
134 If an implementation detects that the value specified by the thread
136 argument to pthread_join() does not refer to a joinable thread, it is
137 recommended that the function should fail and report an [EINVAL] error.
138 If an implementation detects that the value specified by the thread
140 argument to pthread_join() refers to the calling thread, it is recom‐
141 mended that the function should fail and report an [EDEADLK] error.
142 If an implementation detects use of a thread ID after the end of its
144 lifetime, it is recommended that the function should fail and report an
145 [ESRCH] error.
146
148 None.
149
151 pthread_create(), wait()
152 The Base Definitions volume of POSIX.1‐2017, Section 4.12, Memory Syn‐
154 chronization, <pthread.h>
155
157 Portions of this text are reprinted and reproduced in electronic form
158 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
159 table Operating System Interface (POSIX), The Open Group Base Specifi‐
160 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
161 Electrical and Electronics Engineers, Inc and The Open Group. In the
162 event of any discrepancy between this version and the original IEEE and
163 The Open Group Standard, the original IEEE and The Open Group Standard
164 is the referee document. The original Standard can be obtained online
165 at http://www.opengroup.org/unix/online.html .
166 Any typographical or formatting errors that appear in this page are
168 most likely to have been introduced during the conversion of the source
169 files to man page format. To report such errors, see https://www.ker‐
170 nel.org/doc/man-pages/reporting_bugs.html .
171IEEE/The Open Group 2017 PTHREAD_JOIN(3P)