pthread_join (original) (raw)
The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.
A newer edition of this document exists here
NAME
pthread_join - wait for thread termination
SYNOPSIS
int pthread_join(pthread_t
thread, void **valueptr);
`
![[Option Start]](http://www.opengroup.org/onlinepubs/009695399/images/opt-start.gif)
#include <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:
[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.
[EINVAL]
The value specified by thread does not refer to a joinable 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(), wait(), the Base Definitions volume of IEEE Std 1003.1-2001, <pthread.h>
CHANGE HISTORY
First released in Issue 5. Included for alignment with the POSIX Threads Extension.
Issue 6
The pthread_join() function is marked as part of the Threads option.
IEEE Std 1003.1-2001/Cor 2-2004, XSH/TC2/D6/97 is applied, updating the ERRORS section so that the [EINVAL] error is made optional and the words ``the implementation has detected'' are removed from it.
End of informative text.
UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT]