1PTHREAD_JOIN(P) POSIX Programmer's Manual PTHREAD_JOIN(P)
2
6 pthread_join - wait for thread termination
7
9 #include <pthread.h>
10 int pthread_join(pthread_t thread, void **value_ptr);
12
15 The pthread_join() function shall suspend execution of the calling
16 thread until the target thread terminates, unless the target thread has
17 already terminated. On return from a successful pthread_join() call
18 with a non-NULL value_ptr argument, the value passed to pthread_exit()
19 by the terminating thread shall be made available in the location ref‐
20 erenced by value_ptr. When a pthread_join() returns successfully, the
21 target thread has been terminated. The results of multiple simultaneous
22 calls to pthread_join() specifying the same target thread are unde‐
23 fined. If the thread calling pthread_join() is canceled, then the tar‐
24 get thread shall not be detached.
25 It is unspecified whether a thread that has exited but remains unjoined
27 counts against {PTHREAD_THREADS_MAX}.
28
30 If successful, the pthread_join() function shall return zero; other‐
31 wise, an error number shall be returned to indicate the error.
32
34 The pthread_join() function shall fail if:
35 EINVAL The implementation has detected that the value specified by
37 thread does not refer to a joinable thread.
38 ESRCH No thread could be found corresponding to that specified by the
40 given thread ID.
41 The pthread_join() function may fail if:
44 EDEADLK
46 A deadlock was detected or the value of thread specifies the
47 calling thread.
48 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 *
65 incer(void *arg)
66 {
67 long i;
68 for (i = 0; i < ((subarray *)arg)->n; i++)
71 ((subarray *)arg)->ar[i]++;
72 }
73 int main(void)
76 {
77 int ar[1000000];
78 pthread_t th1, th2;
79 subarray sb1, sb2;
80 sb1.ar = &ar[0];
83 sb1.n = 500000;
84 (void) pthread_create(&th1, NULL, incer, &sb1);
85 sb2.ar = &ar[500000];
88 sb2.n = 500000;
89 (void) pthread_create(&th2, NULL, incer, &sb2);
90 (void) pthread_join(th1, NULL);
93 (void) pthread_join(th2, NULL);
94 return 0;
95 }
96
98 None.
99
101 The pthread_join() function is a convenience that has proven useful in
102 multi-threaded applications. It is true that a programmer could simu‐
103 late this function if it were not provided by passing extra state as
104 part of the argument to the start_routine(). The terminating thread
105 would set a flag to indicate termination and broadcast a condition that
106 is part of that state; a joining thread would wait on that condition
107 variable. While such a technique would allow a thread to wait on more
108 complex conditions (for example, waiting for multiple threads to termi‐
109 nate), waiting on individual thread termination is considered widely
110 useful. Also, including the pthread_join() function in no way precludes
111 a programmer from coding such complex waits. Thus, while not a primi‐
112 tive, including pthread_join() in this volume of IEEE Std 1003.1-2001
113 was considered valuable.
114 The pthread_join() function provides a simple mechanism allowing an
116 application to wait for a thread to terminate. After the thread termi‐
117 nates, the application may then choose to clean up resources that were
118 used by the thread. For instance, after pthread_join() returns, any
119 application-provided stack storage could be reclaimed.
120 The pthread_join() or pthread_detach() function should eventually be
122 called for every thread that is created with the detachstate attribute
123 set to PTHREAD_CREATE_JOINABLE so that storage associated with the
124 thread may be reclaimed.
125 The interaction between pthread_join() and cancellation is well-defined
127 for the following reasons:
128 * The pthread_join() function, like all other non-async-cancel-safe
130 functions, can only be called with deferred cancelability type.
131 * Cancellation cannot occur in the disabled cancelability state.
133 Thus, only the default cancelability state need be considered. As spec‐
135 ified, either the pthread_join() call is canceled, or it succeeds, but
136 not both. The difference is obvious to the application, since either a
137 cancellation handler is run or pthread_join() returns. There are no
138 race conditions since pthread_join() was called in the deferred cance‐
139 lability state.
140
142 None.
143
145 pthread_create() , wait() , the Base Definitions volume of
146 IEEE Std 1003.1-2001, <pthread.h>
147
149 Portions of this text are reprinted and reproduced in electronic form
150 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
151 -- Portable Operating System Interface (POSIX), The Open Group Base
152 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
153 Electrical and Electronics Engineers, Inc and The Open Group. In the
154 event of any discrepancy between this version and the original IEEE and
155 The Open Group Standard, the original IEEE and The Open Group Standard
156 is the referee document. The original Standard can be obtained online
157 at http://www.opengroup.org/unix/online.html .
158IEEE/The Open Group 2003 PTHREAD_JOIN(P)