ThreadJoin(), ThreadJoin_r()
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.
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:
| Safety: | |
|---|---|
| Cancellation point | Yes |
| Signal handler | Yes |
| Thread | Yes |