NAME
pthread_join - wait for thread termination
SYNOPSIS
#include <pthread.h>
int pthread_join(pthread_t thread, void **value_ptr);
DESCRIPTION
The pthread_join() function shall suspend execution of the calling
thread until the target thread terminates, unless the target thread has
already terminated. On return from a successful pthread_join() call
with a non-NULL value_ptr argument, the value passed to pthread_exit()
by the terminating thread shall be made available in the location
referenced by value_ptr. When a pthread_join() returns successfully,
the target thread has been terminated. The results of multiple
simultaneous calls to pthread_join() specifying the same target thread
are undefined. If the thread calling pthread_join() is canceled, then
the target thread shall not be detached.
It is unspecified whether a thread that has exited but remains unjoined
counts against {PTHREAD_THREADS_MAX}.
RETURN VALUE
If successful, the pthread_join() function shall return zero;
otherwise, an error number shall be returned to indicate the error.
ERRORS
The pthread_join() function shall fail if:
EINVAL The implementation has detected that the value specified by
thread does not refer to a joinable thread.
ESRCH No thread could be found corresponding to that specified by the
given thread ID.
The pthread_join() function may fail if:
EDEADLK
A deadlock was detected or the value of thread specifies the
calling thread.
The pthread_join() function shall not return an error code of [EINTR].
The following sections are informative.
EXAMPLES
An example of thread creation and deletion follows:
typedef struct {
int *ar;
long n;
} subarray;
void *
incer(void *arg)
{
long i;
for (i = 0; i < ((subarray *)arg)->n; i++)
((subarray *)arg)->ar[i]++;
}
int main(void)
{
int ar[1000000];
pthread_t th1, th2;
subarray sb1, sb2;
sb1.ar = &ar[0];
sb1.n = 500000;
(void) pthread_create(&th1, NULL, incer, &sb1);
sb2.ar = &ar[500000];
sb2.n = 500000;
(void) pthread_create(&th2, NULL, incer, &sb2);
(void) pthread_join(th1, NULL);
(void) pthread_join(th2, NULL);
return 0;
}
APPLICATION USAGE
None.
RATIONALE
The pthread_join() function is a convenience that has proven useful in
multi-threaded applications. It is true that a programmer could
simulate this function if it were not provided by passing extra state
as part of the argument to the start_routine(). The terminating thread
would set a flag to indicate termination and broadcast a condition that
is part of that state; a joining thread would wait on that condition
variable. While such a technique would allow a thread to wait on more
complex conditions (for example, waiting for multiple threads to
terminate), waiting on individual thread termination is considered
widely useful. Also, including the pthread_join() function in no way
precludes a programmer from coding such complex waits. Thus, while not
a primitive, including pthread_join() in this volume of
IEEE Std 1003.1-2001 was considered valuable.
The pthread_join() function provides a simple mechanism allowing an
application to wait for a thread to terminate. After the thread
terminates, the application may then choose to clean up resources that
were used by the thread. For instance, after pthread_join() returns,
any application-provided stack storage could be reclaimed.
The pthread_join() or pthread_detach() function should eventually be
called for every thread that is created with the detachstate attribute
set to PTHREAD_CREATE_JOINABLE so that storage associated with the
thread may be reclaimed.
The interaction between pthread_join() and cancellation is well-defined
for the following reasons:
* The pthread_join() function, like all other non-async-cancel-safe
functions, can only be called with deferred cancelability type.
* Cancellation cannot occur in the disabled cancelability state.
Thus, only the default cancelability state need be considered. As
specified, either the pthread_join() call is canceled, or it succeeds,
but not both. The difference is obvious to the application, since
either a cancellation handler is run or pthread_join() returns. There
are no race conditions since pthread_join() was called in the deferred
cancelability state.
FUTURE DIRECTIONS
None.
SEE ALSO
pthread_create(3), wait(2), the Base Definitions volume of IEEE
Std 1003.1-2001, <pthread.h>
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .