NAME

thrd_join — wait for thread termination

SYNOPSIS

#include <threads.h>

int thrd_join(thrd_t thr, int *res);


DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1-2024 defers to the ISO C standard.

The thrd_join() function shall join the thread identified by thr with the current thread by blocking until the other thread has terminated. If the parameter res is not a null pointer, thrd_join() shall store the thread's exit status in the integer pointed to by res. The termination of the other thread shall synchronize with the completion of the thrd_join() function. The application shall ensure that the thread identified by thr has not been previously detached or joined with another thread.

The results of multiple simultaneous calls to thrd_join() specifying the same target thread are undefined.

The behavior is undefined if the value specified by the thr argument to thrd_join() refers to the calling thread.

^[CX] It is unspecified whether a zombie thread counts against {PTHREAD_THREADS_MAX}.

If thr refers to a thread that was created using pthread_create() or via a SIGEV_THREAD notification and the thread terminates, or has already terminated, by returning from its start routine, the behavior of thrd_join() is undefined. If thr refers to a thread that terminates, or has already terminated, by calling pthread_exit() or by being cancelled, the behavior of thrd_join() is undefined.

The thrd_join() function shall not be affected if the calling thread executes a signal handler during the call.

RETURN VALUE

The thrd_join() function shall return thrd_success on success or thrd_error if the request could not be honored.

^[CX] It is implementation-defined whether thrd_join() detects deadlock situations; if it does detect them, it shall return thrd_error when one is detected.

ERRORS

See RETURN VALUE.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

The thrd_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 thrd_join() returns, any application-provided stack storage could be reclaimed.

The thrd_join() or thrd_detach() function should eventually be called for every thread that is created using thrd_create() so that storage associated with the thread may be reclaimed.

The thrd_join() function cannot be used to obtain the exit status of a thread that was created using pthread_create() or via a SIGEV_THREAD notification and which terminates by returning from its start routine, or of a thread that terminates by calling pthread_exit(), because such threads have a void * exit status, instead of the int that thrd_join() returns via its res argument.

The thrd_join() function cannot be used to obtain the exit status of a thread that terminates by being cancelled because it has no way to indicate that a thread was cancelled. (The pthread_join() function does this by returning a reserved void * exit status; it is not possible to reserve an int value for this purpose without introducing a conflict with the ISO C standard.) The standard developers considered adding a thrd_canceled enumeration constant that thrd_join() would return in this case. However, this return would be unexpected in code that is written to conform to the ISO C standard, and it would also not solve the problem that threads which use only ISO C <threads.h> interfaces (such as ones created by third party libraries written to conform to the ISO C standard) have no way to handle being cancelled, as the ISO C standard does not provide cancellation cleanup handlers.

The thrd_join() function is not affected by signal handlers for the reasons stated in XRAT B.2.3 Error Numbers.

FUTURE DIRECTIONS

None.

SEE ALSO

pthread_create, pthread_exit, pthread_join, thrd_create, thrd_exit

XBD 4.15.2 Memory Synchronization, <threads.h>

CHANGE HISTORY

First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.