trusty (3) pthread_join.3posix.gz

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 .