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