thr_join(THREAD)

thr_join -- join control paths with another thread

Synopsis

   cc [options] -Kthread file
   
   #include <thread.h>
   

   int thr_join(thread_t wait_for, thread_t *departed_thread, void **status);

Description

thr_join waits for termination of the undetached sibling thread designated by wait_for and retrieves the exit status of the terminated thread (see thr_exit(THREAD)).

When the thread being waited for (wait_for) terminates, and thr_join returns, it can be viewed that the terminated thread has ``joined control paths'' with the thread that called thr_join.

Parameters

wait_for: the ID of the thread to wait for or 0
departed_thread: pointer to the ID of the thread joined, set by thr_join
status: pointer to the joined thread's exit status

wait_for parameter

If wait_for is set to the thread ID of an undetached sibling thread, thr_join waits for that thread to terminate. If wait_for is equal to (thread_t)0, thr_join waits for termination of any undetached sibling thread, and returns when the first one completes thr_exit.

Threads created with the THR_DETACHED flag cannot be joined.

departed_thread parameter

If the value of the pointer departed_thread is not NULL, thr_join sets the location pointed to by departed_thread to the identifier of the terminated sibling thread. This tells the calling thread which thread it joined.

status parameter

If status is not NULL, the location pointed to by status is set to the exit status from the terminated sibling thread.

Only one thread can successfully return from a thr_join for a given departed_thread. If more than one thread is waiting for a specific thread to terminate, one is successful and the others fail with error indication ESRCH. This allows exactly one thread to join with and obtain status from a given thread.

If wait_for has already been thr_joined, or otherwise is not known by the implementation, ESRCH is returned.

The wait in thr_join is not broken by a signal. If a thread waiting in thr_join receives a signal that is not masked, if will execute the signal handler, and then return to waiting in thr_join. Note that this behavior differs from that of cond_wait (see condition(SYNCH)).

Return values

thr_join returns zero for success and an error number on failure.

Errors

If any of the following conditions occurs, thr_join returns the corresponding value:

ESRCH: there is no joinable (undetached) thread in the current process with thread ID wait_for.
EDEADLK: wait_for is the calling thread's thread ID.
EINVAL: wait_for is (thread_t) 0, and there are no undetached sibling threads to wait for.

References

Intro(THREAD), condition(SYNCH), _lwp_wait(S), thr_create(THREAD), thr_exit(THREAD), wait(S)