mirror of https://github.com/mkerrisk/man-pages
180 lines
5.5 KiB
Plaintext
180 lines
5.5 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "PTHREAD_JOIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" pthread_join
|
|
.SH NAME
|
|
pthread_join \- wait for thread termination
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <pthread.h>
|
|
.br
|
|
.sp
|
|
int pthread_join(pthread_t\fP \fIthread\fP\fB, void **\fP\fIvalue_ptr\fP\fB);
|
|
\fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIpthread_join\fP() function shall suspend execution of the calling
|
|
thread until the target \fIthread\fP terminates,
|
|
unless the target \fIthread\fP has already terminated. On return from
|
|
a successful \fIpthread_join\fP() call with a non-NULL
|
|
\fIvalue_ptr\fP argument, the value passed to \fIpthread_exit\fP()
|
|
by the
|
|
terminating thread shall be made available in the location referenced
|
|
by \fIvalue_ptr\fP. When a \fIpthread_join\fP() returns
|
|
successfully, the target thread has been terminated. The results of
|
|
multiple simultaneous calls to \fIpthread_join\fP() specifying
|
|
the same target thread are undefined. If the thread calling \fIpthread_join\fP()
|
|
is canceled, then the target thread shall not be
|
|
detached.
|
|
.LP
|
|
It is unspecified whether a thread that has exited but remains unjoined
|
|
counts against {PTHREAD_THREADS_MAX}.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If successful, the \fIpthread_join\fP() function shall return zero;
|
|
otherwise, an error number shall be returned to indicate
|
|
the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIpthread_join\fP() function shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The implementation has detected that the value specified by \fIthread\fP
|
|
does not refer to a joinable thread.
|
|
.TP 7
|
|
.B ESRCH
|
|
No thread could be found corresponding to that specified by the given
|
|
thread ID.
|
|
.sp
|
|
.LP
|
|
The \fIpthread_join\fP() function may fail if:
|
|
.TP 7
|
|
.B EDEADLK
|
|
A deadlock was detected or the value of \fIthread\fP specifies the
|
|
calling thread.
|
|
.sp
|
|
.LP
|
|
The \fIpthread_join\fP() function shall not return an error code of
|
|
[EINTR].
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
An example of thread creation and deletion follows:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBtypedef struct {
|
|
int *ar;
|
|
long n;
|
|
} subarray;
|
|
.sp
|
|
|
|
void *
|
|
incer(void *arg)
|
|
{
|
|
long i;
|
|
.sp
|
|
|
|
for (i = 0; i < ((subarray *)arg)->n; i++)
|
|
((subarray *)arg)->ar[i]++;
|
|
}
|
|
.sp
|
|
|
|
int main(void)
|
|
{
|
|
int ar[1000000];
|
|
pthread_t th1, th2;
|
|
subarray sb1, sb2;
|
|
.sp
|
|
|
|
sb1.ar = &ar[0];
|
|
sb1.n = 500000;
|
|
(void) pthread_create(&th1, NULL, incer, &sb1);
|
|
.sp
|
|
|
|
sb2.ar = &ar[500000];
|
|
sb2.n = 500000;
|
|
(void) pthread_create(&th2, NULL, incer, &sb2);
|
|
.sp
|
|
|
|
(void) pthread_join(th1, NULL);
|
|
(void) pthread_join(th2, NULL);
|
|
return 0;
|
|
}
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
The \fIpthread_join\fP() 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
|
|
\fIstart_routine\fP(). 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 \fIpthread_join\fP() function in
|
|
no way precludes a programmer from coding such complex waits.
|
|
Thus, while not a primitive, including \fIpthread_join\fP() in this
|
|
volume of IEEE\ Std\ 1003.1-2001 was considered
|
|
valuable.
|
|
.LP
|
|
The \fIpthread_join\fP() 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
|
|
\fIpthread_join\fP() returns, any application-provided stack storage
|
|
could be reclaimed.
|
|
.LP
|
|
The \fIpthread_join\fP() or \fIpthread_detach\fP() function should
|
|
eventually
|
|
be called for every thread that is created with the \fIdetachstate\fP
|
|
attribute set to PTHREAD_CREATE_JOINABLE so that storage
|
|
associated with the thread may be reclaimed.
|
|
.LP
|
|
The interaction between \fIpthread_join\fP() and cancellation is well-defined
|
|
for the following reasons:
|
|
.IP " *" 3
|
|
The \fIpthread_join\fP() function, like all other non-async-cancel-safe
|
|
functions, can only be called with deferred
|
|
cancelability type.
|
|
.LP
|
|
.IP " *" 3
|
|
Cancellation cannot occur in the disabled cancelability state.
|
|
.LP
|
|
.LP
|
|
Thus, only the default cancelability state need be considered. As
|
|
specified, either the \fIpthread_join\fP() call is canceled,
|
|
or it succeeds, but not both. The difference is obvious to the application,
|
|
since either a cancellation handler is run or
|
|
\fIpthread_join\fP() returns. There are no race conditions since \fIpthread_join\fP()
|
|
was called in the deferred cancelability
|
|
state.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIpthread_create\fP() , \fIwait\fP() , the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, \fI<pthread.h>\fP
|
|
.SH 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 .
|