pthread_cleanup_pop()--Pop Cleanup Handler off of Cancellation Cleanup Stack

 #include <pthread.h>
 void pthread_cleanup_pop(int execute);  

The pthread_cleanup_pop() function pops the last cleanup handler from the cancellation cleanup stack. If the execute parameter is nonzero, the handler is called with the argument specified by the pthread_cleanup_push() call with which the handler was registered.

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, 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 is 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

execute

(Input) Boolean value indicating whether the cancellation cleanup handler should be executed

Return Value

None.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_cancel()--Cancel Thread
  
  
• pthread_cleanup_push()--Push Cleanup Handler onto 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, you should see the cleanup handler\n");
  pthread_cleanup_push(cleanupHandler, NULL);
  sleep(1);  /* Simulate more code here */
  pthread_cleanup_pop(1);
  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(5);
  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPCLPO0
Create thread using the NULL attributes
Entered secondary thread, you should see the cleanup handler
In the cleanup handler
Main completed