pthread_cleanup_push()--Push Cleanup Handler onto Cancellation Cleanup Stack
Syntax:
#include <pthread.h> void pthread_cleanup_push(void (*routine)(void *), void *arg);Service Program Name: QP0WPTHR
Default Public Authority: *USE
Threadsafe: Yes
Signal Safe: No
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
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" 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
API introduced: V4R3
[ Back to top | Pthread APIs | APIs by category ]