TutThreadWait

Name

TutThreadWait — wait for another thread to exit

Synopsis

T_BOOL TutThreadWait(thread, exit_return) 
T_THREAD thread; 
T_PTR *exit_return; 

Arguments

thread — thread to join with

exit_return — location of a T_PTR into which that thread’s exit value is stored

Return Values

TRUE if the attempt to wait was successful, FALSE otherwise.

Diagnostics

If TutThreadWait fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TutThreadWait attempts to suspend the calling thread until the (other) thread designated by thread has exited. It then retrieves thread’s exit value and stores it in the location designated by exit_return. Finally, all resources associated with (the now defunct) thread are released. This implies that only one calling thread can successfully do a TutThreadWait on a given (other) thread. The normal practice is to make any thread that creates child threads responsible for waiting for each of its children to exit.

If the thread designated by thread has already exited before TutThreadWait is first called, the function succeeds immediately, without suspending the calling thread, and stores the saved exit value in the location designated by exit_return.

Caution

A thread created by TutThreadCreate or TutThreadCreateVa that is not joined with TutThreadWait leaks a small amount of system resources. If this is done systematically by a long-lived process, eventually that process may exhaust an operating-system-dependent limit and no may longer be able to create new threads.

To create detached threads (for example, threads that free all of their associated resources immediately upon completion), call either TutThreadWait or TutThreadDetach.

See Also

TutThreadCreate, TutThreadCreateVa, TutThreadExit, TutThreadDetach

Examples

This example expects a pointer to a heap-allocated two-element integer array as the calling thread’s exit status:

T_THREAD thread; 
T_INT4 *result_array; 
. 
. 
. 
if (!TutThreadWait(thread, &result_array)) { 
  /* error */ 
} 
TutOut("Result array => [ %d, %d ]\n", 
       result_array[0], result_array[1]); 
TutFree(result_array);