diff options
Diffstat (limited to 'man3p/pthread_join.3p')
| -rw-r--r-- | man3p/pthread_join.3p | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/man3p/pthread_join.3p b/man3p/pthread_join.3p new file mode 100644 index 000000000..a34e46147 --- /dev/null +++ b/man3p/pthread_join.3p @@ -0,0 +1,179 @@ +.\" 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 . |