pthread_extendedjoin_np()--Wait for Thread with Extended Options

 #include <pthread.h>
 int pthread_extendedjoin_np(pthread_t thread, void **status,
 			     pthread_joinoption_np_t *options);  

The pthread_extendedjoin_np() function waits for a thread to terminate, optionally detaches the thread, then returns the threads exit status.

If the options parameter is specified as NULL or the contents of the pthread_joinoption_np_t structure represented by options parameter is binary 0, then the behavior of pthread_extendedjoin_np() is equivalent to pthread_join().

The deltatime field of the options parameter can be used to specify the amount of elapsed time to wait before the wait times out. If the wait times out, the ETIMEDOUT error is returned and the thread is not detached. For an infinite wait, specify a seconds value of 0, and a nanoseconds value of 0.

The leaveThreadAllocated field of the options parameter can be used to specify that the pthread_extendedjoin_np() function should NOT implicitly detach the thread when the join completes successfully. If the leaveThreadAllocated option is used, the thread should later be detached using pthread_join(), pthread_detach(), or pthread_extendedjoin_np() without specifying the leaveThreadAllocated option.

The reserved fields of the options parameter are for use by possible future extensions to pthread_extendedjoin_np(). If any reserved fields of the options parameter are not zero, the EINVAL error is returned.

If the status parameter is NULL, the threads exit status is not returned.

The meaning of the threads exit status (value returned to the status memory location) is determined by the application except for the following conditions:

1. When the thread has been canceled using pthread_cancel(), the exit status of PTHREAD_CANCELED is made available.
2. When the thread has been terminated as a result of an unhandled IBM^® i exception, operator intervention, or other proprietary IBM i mechanism, the exit status of PTHREAD_EXCEPTION_NP is made available.

Eventually, you should call pthread_join(), pthread_detach() or pthread_extendedjoin_np() without specifying the leaveThreadAllocated option for every thread that is created joinable (with a detach state of PTHREAD_CREATE_JOINABLE) so that the system can reclaim all resources associated with the thread. Failure to join to or detach joinable threads causes memory and other resource leaks until the process ends.

Authorities and Locks

None.

Parameters

thread

(Input) Pthread handle to the target thread

status

(Input/Output) Address of the variable to receive the thread's exit status

options

(Input) Address of the join options structure specifying optional behavior of this API.

Return Value

0

pthread_extendedjoin_np() was successful.

value

pthread_extendedjoin_np() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_extendedjoin_np() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[ESRCH]

The thread specified could not be found.

[ETIMEDOUT]

The time specified in the deltatime field of the options parameter elapsed without the target thread terminating.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_detach()--Detach Thread
  
  
• pthread_exit()--Terminate Calling Thread
  
  
• pthread_join()--Wait for and Detach Thread
  
  
• pthread_join_np()--Wait for Thread to End

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define _MULTI_THREADED
#include <pthread.h>
#include <unistd.h>
#include <string.h>
#include <errno.h>
#include <stdio.h>
#include "check.h"

static void *thread(void *parm)
{
   printf("Entered thread\n");
   sleep(10);
   printf("Ending thread\n");
   return __VOID(42);
}


int main (int argc, char *argv[])
{
   pthread_joinoption_np_t    joinoption;
   void                      *status;
   int                        rc;
   pthread_t                  t;

   printf("Entering testcase %s\n", argv[0]);

   printf("Create thread using attributes that allow join\n");
   rc = pthread_create(&t, NULL, thread, NULL);
   checkResults("pthread_create()\n", rc);

   memset(&joinoption, 0, sizeof(pthread_joinoption_np_t));
   joinoption.deltatime.tv_sec = 3;
   joinoption.leaveThreadAllocated = 1;

   printf("Join to the thread, timeout in 3 seconds, no implicit detach\n");
   rc = pthread_extendedjoin_np(t, &status, &joinoption);
   if (rc != ETIMEDOUT) {
      printf("Join did not timeout as expected! rc=%d\n", rc);
      exit(1);
   }

   /* Call pthread_extendedjoin_np the same as a normal             */
   /* pthread_join() call.                                          */
   /* i.e.     Implicit Detach is done, and Infinite wait           */
   printf("Normal join to the thread\n");
   rc = pthread_extendedjoin_np(t, &status, NULL);
   checkResults("pthread_extendedjoin_np(no-options)\n", rc);

   if (__INT(status) != 42) {
      printf("Got the incorrect thread status!\n");
      exit(1);
   }
   printf("Main completed\n");
   return(0);

}

Output

Entering testcase QP0WTEST/TPJOINE0
Create thread using attributes that allow join
Join to the thread, timeout in 3 seconds, no implicit detach
Entered thread
Normal join to the thread
Ending thread
Main completed

[ Back to top | Pthread APIs | APIs by category ]