Man Linux: Main Page and Category List

NAME

       pthread_join - wait for thread termination

SYNOPSIS

       #include <pthread.h>

       int pthread_join(pthread_t thread, void **value_ptr);

DESCRIPTION

       The  pthread_join()  function  shall  suspend  execution of the calling
       thread until the target thread terminates, unless the target thread has
       already  terminated.  On  return  from a successful pthread_join() call
       with a non-NULL value_ptr argument, the value passed to  pthread_exit()
       by  the  terminating  thread  shall  be  made available in the location
       referenced by value_ptr. When a  pthread_join()  returns  successfully,
       the  target  thread  has  been  terminated.  The  results  of  multiple
       simultaneous calls to pthread_join() specifying the same target  thread
       are  undefined.  If the thread calling pthread_join() is canceled, then
       the target thread shall not be detached.

       It is unspecified whether a thread that has exited but remains unjoined
       counts against {PTHREAD_THREADS_MAX}.

RETURN VALUE

       If   successful,   the   pthread_join()  function  shall  return  zero;
       otherwise, an error number shall be returned to indicate the error.

ERRORS

       The pthread_join() function shall fail if:

       EINVAL The implementation has detected  that  the  value  specified  by
              thread does not refer to a joinable thread.

       ESRCH  No  thread could be found corresponding to that specified by the
              given thread ID.

       The pthread_join() function may fail if:

       EDEADLK
              A deadlock was detected or the value  of  thread  specifies  the
              calling thread.

       The  pthread_join() function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES

       An example of thread creation and deletion follows:

              typedef struct {
                  int *ar;
                  long n;
              } subarray;

              void *
              incer(void *arg)
              {
                  long i;

                  for (i = 0; i < ((subarray *)arg)->n; i++)
                      ((subarray *)arg)->ar[i]++;
              }

              int main(void)
              {
                  int        ar[1000000];
                  pthread_t  th1, th2;
                  subarray   sb1, sb2;

                  sb1.ar = &ar[0];
                  sb1.n  = 500000;
                  (void) pthread_create(&th1, NULL, incer, &sb1);

                  sb2.ar = &ar[500000];
                  sb2.n  = 500000;
                  (void) pthread_create(&th2, NULL, incer, &sb2);

                  (void) pthread_join(th1, NULL);
                  (void) pthread_join(th2, NULL);
                  return 0;
              }

APPLICATION USAGE

       None.

RATIONALE

       The pthread_join() function is a convenience that has proven useful  in
       multi-threaded  applications.  It  is  true  that  a  programmer  could
       simulate this function if it were not provided by passing  extra  state
       as  part of the argument to the start_routine(). The terminating thread
       would set a flag to indicate termination and broadcast a condition that
       is  part  of  that state; a joining thread would wait on that condition
       variable.  While such a technique would allow a thread to wait on  more
       complex  conditions  (for  example,  waiting  for  multiple  threads to
       terminate), waiting on  individual  thread  termination  is  considered
       widely  useful.  Also,  including the pthread_join() function in no way
       precludes a programmer from coding such complex waits.  Thus, while not
       a    primitive,    including   pthread_join()   in   this   volume   of
       IEEE Std 1003.1-2001 was considered valuable.

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

       The pthread_join() or pthread_detach() function  should  eventually  be
       called  for every thread that is created with the detachstate attribute
       set to PTHREAD_CREATE_JOINABLE so  that  storage  associated  with  the
       thread may be reclaimed.

       The interaction between pthread_join() and cancellation is well-defined
       for the following reasons:

        * The pthread_join() function, like  all  other  non-async-cancel-safe
          functions, can only be called with deferred cancelability type.

        * Cancellation cannot occur in the disabled cancelability state.

       Thus,  only  the  default  cancelability  state  need be considered. As
       specified, either the pthread_join() call is canceled, or it  succeeds,
       but  not  both.  The  difference  is  obvious to the application, since
       either a cancellation handler is run or pthread_join()  returns.  There
       are  no race conditions since pthread_join() was called in the deferred
       cancelability state.

FUTURE DIRECTIONS

       None.

SEE ALSO

       pthread_create()  ,  wait()  ,   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <pthread.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .