Unix/Linux Go Back    


Linux 2.6 - man page for pthread_join (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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  suc-
       cessful	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  refer-
       enced 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 termi-
       nating 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  program-
       mer 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				  PTHREAD_JOIN(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:52 AM.