pthread_join.3p (6635B)
- '\" et
- .TH PTHREAD_JOIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- pthread_join
- \(em wait for thread termination
- .SH SYNOPSIS
- .LP
- .nf
- #include <pthread.h>
- .P
- int pthread_join(pthread_t \fIthread\fP, void **\fIvalue_ptr\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIpthread_join\fR()
- function shall suspend execution of the calling thread until the target
- .IR thread
- terminates, unless the target
- .IR thread
- has already terminated. On return from a successful
- \fIpthread_join\fR()
- call with a non-NULL
- .IR value_ptr
- argument, the value passed to
- \fIpthread_exit\fR()
- by the terminating thread shall be made available in the location
- referenced by
- .IR value_ptr .
- When a
- \fIpthread_join\fR()
- returns successfully, the target thread has been terminated. The
- results of multiple simultaneous calls to
- \fIpthread_join\fR()
- specifying the same target thread are undefined. If the thread calling
- \fIpthread_join\fR()
- is canceled, then the target thread shall not be detached.
- .P
- It is unspecified whether a thread that has exited but remains unjoined
- counts against
- {PTHREAD_THREADS_MAX}.
- .P
- The behavior is undefined if the value specified by the
- .IR thread
- argument to
- \fIpthread_join\fR()
- does not refer to a joinable thread.
- .P
- The behavior is undefined if the value specified by the
- .IR thread
- argument to
- \fIpthread_join\fR()
- refers to the calling thread.
- .SH "RETURN VALUE"
- If successful, the
- \fIpthread_join\fR()
- function shall return zero; otherwise, an error number shall be
- returned to indicate the error.
- .SH ERRORS
- The
- \fIpthread_join\fR()
- function may fail if:
- .TP
- .BR EDEADLK
- A deadlock was detected.
- .P
- The
- \fIpthread_join\fR()
- function shall not return an error code of
- .BR [EINTR] .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- An example of thread creation and deletion follows:
- .sp
- .RS 4
- .nf
- typedef struct {
- int *ar;
- long n;
- } subarray;
- .P
- void *
- incer(void *arg)
- {
- long i;
- .P
- for (i = 0; i < ((subarray *)arg)->n; i++)
- ((subarray *)arg)->ar[i]++;
- }
- .P
- int main(void)
- {
- int ar[1000000];
- pthread_t th1, th2;
- subarray sb1, sb2;
- .P
- sb1.ar = &ar[0];
- sb1.n = 500000;
- (void) pthread_create(&th1, NULL, incer, &sb1);
- .P
- sb2.ar = &ar[500000];
- sb2.n = 500000;
- (void) pthread_create(&th2, NULL, incer, &sb2);
- .P
- (void) pthread_join(th1, NULL);
- (void) pthread_join(th2, NULL);
- return 0;
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- The
- \fIpthread_join\fR()
- 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\fR().
- 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\fR()
- function in no way precludes a programmer from coding such complex
- waits. Thus, while not a primitive, including
- \fIpthread_join\fR()
- in this volume of POSIX.1\(hy2017 was considered valuable.
- .P
- The
- \fIpthread_join\fR()
- 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\fR()
- returns, any application-provided stack storage could be reclaimed.
- .P
- The
- \fIpthread_join\fR()
- or
- \fIpthread_detach\fR()
- function should eventually be called for every thread that is created
- with the
- .IR detachstate
- attribute set to PTHREAD_CREATE_JOINABLE
- so that storage associated with the thread may be reclaimed.
- .P
- The interaction between
- \fIpthread_join\fR()
- and cancellation is well-defined for the following reasons:
- .IP " *" 4
- The
- \fIpthread_join\fR()
- function, like all other non-async-cancel-safe functions, can only be
- called with
- deferred cancelability type.
- .IP " *" 4
- Cancellation cannot occur in the disabled cancelability state.
- .P
- Thus, only the default cancelability state need be considered. As
- specified, either the
- \fIpthread_join\fR()
- 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\fR()
- returns. There are no race conditions since
- \fIpthread_join\fR()
- was called in the deferred cancelability state.
- .P
- If an implementation detects that the value specified by the
- .IR thread
- argument to
- \fIpthread_join\fR()
- does not refer to a joinable thread, it is recommended that the
- function should fail and report an
- .BR [EINVAL]
- error.
- .P
- If an implementation detects that the value specified by the
- .IR thread
- argument to
- \fIpthread_join\fR()
- refers to the calling thread, it is recommended that the function
- should fail and report an
- .BR [EDEADLK]
- error.
- .P
- If an implementation detects use of a thread ID after the end of its
- lifetime, it is recommended that the function should fail and report an
- .BR [ESRCH]
- error.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIpthread_create\fR\^(\|)",
- .IR "\fIwait\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 4.12" ", " "Memory Synchronization",
- .IR "\fB<pthread.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .