pthread_cleanup_push()--Push Cleanup Handler onto Cancellation Cleanup Stack

 #include <pthread.h>
 void pthread_cleanup_push(void (*routine)(void *), void *arg);  

The pthread_cleanup_push() function pushes a cancellation cleanup routine onto the calling threads cancellation cleanup stack. When the thread calls pthread_exit() or is cancelled by pthread_cancel(), the cancellation cleanup handlers are called with the argument arg.

The cancellation cleanup handlers are also called when they are removed from the cancellation cleanup stack by a call to pthread_cleanup_pop() and a non-zero execute argument is specified.

The pthread_cleanup_push() and the matching pthread_cleanup_pop() call should be in the same lexical scope (that is, same level of brackets {}).

When the thread calls pthread_exit() or is cancelled by pthread_cancel(), the cancellation cleanup handlers are called with the argument specified by the pthread_cleanup_push() call that the handler was registered with.

During this thread cancellation cleanup processing, the thread calls cancellation cleanup handlers with cancellation disabled until the last cancellation cleanup handler returns. The handlers are called in Last In, First Out (LIFO) order. Automatic storage for the invocation stack frame of the function that registered the handler are still present when the cancellation cleanup handler is executed.

When a cancellation cleanup handler is called because of a call to pthread_cleanup_pop(1), the cancellation cleanup handler does not necessarily run with cancellation disabled. The cancellation state and cancellation type are not changed by a call to pthread_cleanup_pop(1).

A cancellation cleanup handler should not exit using longjmp() or siglongjmp(). If a cleanup handler takes an exception, the exception condition is handled and ignored and processing continues. You can look in the job log of the job to see exception messages generated by cancellation cleanup handlers.

Authorities and Locks

None.

Parameters

routine

(Input) The cancellation cleanup routine

arg

(Input) Argument that is passed to the start routine if it is called

Return Value

None.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cancel()--Cancel Thread
  
  
• pthread_cleanup_pop()--Pop Cleanup Handler off of Cancellation Cleanup Stack
  
  
• pthread_exit()--Terminate Calling Thread

Example

See Code disclaimer information for information pertaining to code examples.

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

void cleanupHandler(void *arg)
{
  printf("In the cleanup handler\n");
}

void *threadfunc(void *parm)
{
  printf("Entered secondary thread\n");
  pthread_cleanup_push(cleanupHandler, NULL);
  while (1) {
    pthread_testcancel();
    sleep(1);
  }
  pthread_cleanup_pop(0);
  return NULL;
}

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

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

  /* Create a thread using default attributes */
  printf("Create thread using the NULL attributes\n");
  rc = pthread_create(&thread, NULL, threadfunc, NULL);
  checkResults("pthread_create(NULL)\n", rc);

  /* sleep() is not a very robust way to wait for the thread */
  sleep(2);

  printf("Cancel the thread\n");
  rc = pthread_cancel(thread);
  checkResults("pthread_cancel()\n", rc);

  /* sleep() is not a very robust way to wait for the thread */
  sleep(3);
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPCLPU0
Create thread using the NULL attributes
Entered secondary thread
Cancel the thread
In the cleanup handler
Main completed