ThreadJoin(), ThreadJoin_r()

Updated: April 19, 2023

Block until a thread terminates

Synopsis:

#include <sys/neutrino.h>

int ThreadJoin( int tid,
                void** status );


int ThreadJoin_r( int tid,
                  void** status );

Arguments:

tid
The ID of the thread that you want to join, as returned by ThreadCreate().
status
The address of a pointer to a location where the function can store the thread's exit status.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The ThreadJoin() and ThreadJoin_r() kernel calls block until the thread specified by tid terminates. If status isn't NULL, the functions save the thread's exit status in the area pointed to by status. If the thread tid has already terminated, the functions immediately return with success and the status, if requested.

These functions are identical except in the way they indicate errors. See the Returns section for details.

Note: Instead of using these kernel calls directly, consider calling pthread_join() or pthread_timedjoin().

When ThreadJoin() returns successfully, the target thread has been successfully terminated. Until this occurs, the thread ID tid isn't reused and a small kernel resource (a thread object) is retained.

You can't join a thread that's detached (see ThreadCreate() and ThreadDetach()).

The target thread must be joinable. Multiple pthread_join(), pthread_timedjoin(), ThreadJoin(), and ThreadJoin_r() calls on the same target thread aren't allowed.

Blocking states

STATE_JOIN
The calling thread blocks waiting for the indicated thread to exit.

Returns:

The only difference between these functions is the way they indicate errors:

ThreadJoin()
If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
ThreadJoin_r()
Returns EOK on success. This function does NOT set errno. If an error occurs, the function may return any value listed in the Errors section.

Errors:

EBUSY
The specified thread is already being joined by another thread.
EDEADLK
The calling thread is attempting to join itself.
EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EINTR
The call was interrupted by a signal.
EINVAL
The specified thread isn't joinable because it's detached (see ThreadDetach()).
ESRCH
The specified thread doesn't exist.
ETIMEDOUT
A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX Neutrino

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes