PTHREAD_JOIN(3P) - phpMan

PTHREAD_JOIN(3P)           POSIX Programmer's Manual          PTHREAD_JOIN(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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  ref-
       erenced  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 unde-
       fined. If the thread calling pthread_join() is canceled, then the  tar-
       get 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;  other-
       wise, 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 simu-
       late 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 termi-
       nate), 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  primi-
       tive,  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 termi-
       nates, 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 spec-
       ified, 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 cance-
       lability 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 .

IEEE/The Open Group                  2003                     PTHREAD_JOIN(3P)