pthread_exit()--Terminate Calling Thread

 #include <pthread.h>
 void pthread_exit(void *status);

The pthread_exit() function terminates the calling thread, making its exit status available to any waiting threads. Normally, a thread terminates by returning from the start routine that was specified in the pthread_create() call which started it. An implicit call to pthread_exit() occurs when any thread returns from its start routine. (With the exception of the initial thread, at which time an implicit call to exit() occurs). The pthread_exit() function provides an interface similar to exit() but on a per-thread basis.

Note that in the IBM^® i implementation of threads, the initial thread is special. Termination of the initial thread by pthread_exit() or any thread termination mechanism terminates the entire process.

The following activities occur in this order when a thread terminates by a return from its start routine or pthread_exit() or thread cancellation:

1. Any cancellation cleanup handlers that have been pushed and not popped will be executed in reverse order with cancellation disabled.
2. Data destructors are called for any thread specific data entries that have a non NULL value for both the value and the destructor.
3. The thread terminates.
4. Thread termination may possibly cause the system to run IBM i cancel handlers (registered with the #pragma cancel_handler directive), or C++ destructors for automatic objects.
5. If thread termination is occurring in the initial thread, it will cause the system to terminate all other threads, then run C++ static object destructors, activation group cleanup routines and atexit() functions.
6. Any mutexes that are held by a thread that terminates, become `abandoned' and are no longer valid. Subsequent calls by other threads that attempt to acquire the abandoned mutex though pthread_mutex_lock() will deadlock. Subsequent calls by other threads that attempt to acquire the abandoned mutex through pthread_mutex_trylock() will return EBUSY.
7. No release of any application visible process resources occur. This includes but is not limited to mutexes, file descriptors, or any process level cleanup actions.

Do not call pthread_exit() from a cancellation cleanup handler or destructor function that was called as a result of either an implicit or explicit call to pthread_exit(). If pthread_exit() is called from a cancellation cleanup handler, the new invocation of pthread_exit() will continue cancellation cleanup processing using the next cancellation cleanup handler that was pushed. If pthread_exit() is called from a data destructor, the new invocation of pthread_exit() will skip all subsequent calls to any data destructors (regardless of the number of destructor iterations that have completed), and terminate the thread.

Cleanup handlers and data destructors are not called when the application calls exit() or abort() or otherwise terminates the process. Cleanup handlers and data destructors are not called when a thread terminates by any proprietary IBM i mechanism other than the Pthread interfaces.

The meaning of the status parameter 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 will be 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 will be made available.

No address error checking is done on the status parameter. Do not call pthread_exit() with, or return the address of, a variable in a threads automatic storage. This storage will be unavailable after the thread terminates.

Note: If pthread_exit() is called by application code after step 3 in the above list, pthread_exit() will fail with the CPF1F81 exception. This indicates that the thread is already considered terminated by the system, and pthread_exit() cannot continue. If your code does not handle this exception, it will appear as if the call to pthread_exit() was successful.

Authorities and Locks

None.

Parameters

status

(Input) exit status of the thread

Return Value

pthread_exit() does not return.

Error Conditions

None.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cancel()--Cancel Thread
  
  
• pthread_create()--Create Thread
  
  
• pthread_join()--Wait for and Detach Thread

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 <stdio.h>
#include "check.h"

int  theStatus=5;

void *threadfunc(void *parm)
{
  printf("Inside secondary thread\n");
  pthread_exit(__VOID(theStatus));
  return __VOID(theStatus); /* Not needed, but this makes the compiler smile */
}

int main(int argc, char **argv)
{
  pthread_t             thread;
  int                   rc=0;
  void                 *status;

  printf("Enter Testcase - %s\n", argv[0]);

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

  printf("Wait for the thread to exit\n");
  rc = pthread_join(thread, &status);
  checkResults("pthread_join()\n", rc);
  if (__INT(status) != theStatus) {
    printf("Secondary thread failed\n");
    exit(1);
  }

  printf("Got secondary thread status as expected\n");
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPEXIT0
Create thread using attributes that allow join
Wait for the thread to exit
Inside secondary thread
Got secondary thread status as expected
Main completed

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