Waiting for a Thread's Completion

Syntax

In many cases, a thread has to wait until some other threads terminate. This is the job of function thr_join(). The syntax of thr_join() is:

int thr_join(
       thread_t wait_for,  /* thread we are waiting  */
       0,                  /* 0 is fine with use     */
       void **status);     /* status in thr_create() */

• wait_for, whose type is thread_t, is the sixth parameter in a thr_create() call. This parameter stores the ID of a thread. Thus, this call means the caller wants to wait the thread whose ID is wait_for until its completion. Now, we have two cases:
  • If thr_join() is reached before the completion of the indicated thread, the caller waits until the completion of the indicated thread. After this, the caller executes its next statement.
  • If thr_join() is reached after the completion of the indicated thread, nothing will happen to the caller and the caller executes its next statement.
• Consider the example below:

  #include  <thread.h>
  
  void  Task(void *Junk)
  {
       .......
       thr_exit(NULL);
  }
  
  void  main(void)
  {
       thread_t   TaskID;
       size_t     TaskStatus;
  
       thr_create(NULL,0,Task,(void *) NULL,0,&TaskID);
       ......
       thr_join(TaskID, 0, (void *) &TaskStatus);
  }
  

  If thr_join() in the main program is reached before Task() terminates, the main program waits there until Task() completes. Then, the execution of main resumes. This is illustrated by the following diagram:
  

  On the other hand, if Task() has already terminated when the main program reaches thr_join(), there is nothing to ``join'' and the main program proceeds:

  
• status is a variable of type size_t. status is used to save the status of the terminated thread. For most cases, a zero for status works fine. Or, if you like, you can declare a variable of type size_t and cast the pointer to it to void *.
• If the execution of thr_join() is successful, the returned value is 0.
• Multiple threads should not wait for the same thread. If this does happen, one of these threads returns successfully, while the others will fail because the waited thread is not a valid one after it exits.

Example

#include  
#include  

#define   MAX_ITERATION  200

void  *ThreadA(void *DontNeedIt)
{
     int  i;

     for (i = 1; i <= MAX_ITERATION; i++)
          printf("Thread A speaking: iteration %d\n", i);
     thr_exit(NULL);
}

void  *ThreadB(void *DontNeedIt)
{
     int  i;

     for (i = 1; i <= MAX_ITERATION; i++)
          printf("     Thread B speaking: iteration %d\n", i);
     thr_exit(NULL);
}

void  main(void)
{
     thread_t  FirstThread, SecondThread;
     size_t    StatusFromA, StatusFromB;

     thr_create(NULL, 0, ThreadA, (void *) NULL, 0, &FirstThread);
     thr_create(NULL, 0, ThreadB, (void *) NULL, 0, &SecondThread);

     thr_join(FirstThread, 0, (void *) &StatusFromA);
     thr_join(SecondThread, 0, (void *) &StatusFromB);
}

• This program creates two threads, each of which iterates MAX_ITERATION times. A message is displayed in each iteration.
• The main creates the first thread by running function ThreadA(); however, the main program sends nothing into this thread. Please note the sixth argument FirstThread. It will stored the thread ID of the created thread and is used in the corresponding thr_join() call.
• The third argument of the first call to thr_join() is a pointer to StatusFromA of type size_t. This pointer is cast to void *.
• After creating both threads, the main program waits for the completion of both threads and then exits. Note that both threads exit using thr_exit() rather than exit().