thr_join(3scl)thr_join(3scl)NAMEthr_join - Causes the calling thread to wait for the termination of a
thread, and to return that thread's return-status.
LIBRARY
SCL Threads Library (libthread.so)
SYNOPSIS
#include <thread.h>
int thr_join(
thread_t wait_for,
thread_t *departed,
void **thr_status );
PARAMETERS
Identifier of the thread to be waited for. Returns the identifier of
the thread that was joined. Returns the exit-status from the termi‐
nated, joined thread.
DESCRIPTION
This routine suspends execution of the calling thread until the speci‐
fied target thread wait_for terminates.
If wait_for is 0, then this routine will try to join with an already-
terminated, undetached thread, and if there are not any threads in that
state, then this routine waits for an undetached thread to terminate,
and joins with it. The identifier of the joined thread is returned in
the departed argument.
Solaris documents that a thread can wait for all other [un-detached,
non-daemon] threads to terminate by executing the following piece of
code: while (thr_join(0,0,0) == 0)
;
SCL IMPLEMENTATION NOTES
POSIX threads provides pthread_join( pthread_t thread, void **value_ptr
). Thus if the wait_for parameter to thr_join(3scl) is not 0, then
thr_join(3scl) essentially just calls pthread_join(3).
If the wait_for parameter to thr_join(3scl) is 0, then thr_join(3scl)
can join with any joinable, terminated thread. We refer to this as
join-any-thread. POSIX threads does not support join-any-thread: it
only supports joining with a specified thread. Thus to implement join-
any-thread functionality, internal state information about all threads
of the current process is maintained by the SCL thread library. This
state information is updated when a new thread is created, or a thread
terminates, or a thread is joined.
When thr_join(3scl) is called with wait_for set to 0 to join-any-
thread, the SCL implementation will obtain a suitable thread ID to join
with. It does this by looking at the internal state information for a
thread that has already terminated and is undetached, or by waiting for
the first suitable thread to terminate.
In all cases, thr_join(3scl) ultimately calls pthread_join(3) with a
specific thread ID, to obtain the return-status of the thread, and to
properly detach the thread in the underlying POSIX thread library.
Daemon threads
Solaris documents that daemon threads cannot be joined. Calling
thr_join(0,..) to join-any-thread when the only other thread is an
active daemon thread results in thr_join() on Solaris returning
EDEADLK.
However, tests on Solaris showed that calling thr_join() with a spe‐
cific daemon thread ID blocks, and if the daemon thread subsequently
exits, the calling thread successfully joins with the daemon thread.
This behaviour seems inconsistent with the documented behaviour.
It is envisaged that typical use of daemon threads probably assumes
that a daemon thread will never terminate, and hence never need join‐
ing. Thus in the SCL threads implementation, daemon threads are made
detached by default, meaning that they are not joinable. If joinable
daemon threads are required, the SCL environment variable
STL_DETACH_DAEMONS can be set to 0, which causes daemon threads to be
created as non-detached.
Solaris thr_join() behaviour and SCL thr_join() behaviour
A test program was created which creates a new thread with particular
attributes, i.e. detached or non-detached, and daemon or non-daemon.
The main thread immediately tries to join with the new thread, either
by specifying the specific thread ID to join with, or by specifying
thr_join(0,...) to join-any-thread. The new thread executes for 10 sec‐
onds then terminates.
The table below shows the observed behaviour of thr_join() on Solaris
5.7 for this scenario: join-specific-thread join-any-
thread thread attributes thr_join( tid ) thr_join( 0 )
--------------------------------------------- <default>
0 0 detached ESRCH
<hangs> daemon 0 EDEADLK detached
daemon ESRCH EDEADLK
A status of 0 means that the thread was successfully joined. Any other
status means that the thread was not joined.
The table below shows the implemented behaviour for SCL thr_join() on
Tru64 UNIX for this scenario: thread attributes thr_join( tid )
thr_join( 0 ) --------------------------------
------------- <default> 0 0 detached
ESRCH EDEADLK daemon [1] ESRCH
EDEADLK daemon [2] 0 0 detached daemon
ESRCH EDEADLK
This is the default behaviour for daemon threads, which are implicitly
created detached by the SCL implementation. This is the behaviour for
daemon threads when the SCL environment variable STL_DETACH_DAEMONS is
set to 0.
RETURN VALUES
If an error condition occurs, this routine returns an integer value
indicating the type of error.
Additional error return information may be written to the SCL error
log. Refer to scl_error_log(4scl) for details.
Possible return values are as follows: Successful completion. The
specified thread ID does not refer to an existing thread. Or:
Error EINVAL from pthread_join(3), indicating that the specified thread
ID does not refer to a joinable (non-detached) thread. Or:
An internal implementation error occurred. Refer to the SCL errorlog
for additional information. A potential deadlock was detected: the
only joinable thread is the calling thread. Or:
An internal implementation error occurred. Refer to the SCL errorlog
for additional information.
ERRORS
None.
RELATED INFORMATION
Functions: pthread_create(3), pthread_join(3), scl_intro(3scl),
scl_thread_intro(3scl), thr_create(3scl)
Files: scl_error_log(4scl)
Manuals: Solaris Compatibility Libraries User's Guide
thr_join(3scl)
