Thread cancellation APIs

You can use thread cancellation APIs to cause a thread to end prematurely, or to aid in cleanup when a thread is ended (either prematurely or normally). The thread cancellation APIs work together to provide a mechanism for thread cleanup and protecting threaded resources from cancellation. The thread cancellation APIs only provide clean up and protection in relationship to other pthread APIs. You cannot protect from or clean up when a thread ends as a result of your process ending (normally or abnormally), or when the thread ends by some mechanism outside of the pthread API set. Some examples of mechanisms that can terminate a thread that are outside o the pthread API set are the ENDJOB *IMMED CL command, a thread ending from an unhandled exception, or the operator terminating a thread using the work with threads screen (Option 20 from the WRKJOB display).

The table below lists the thread cancelability states, the cancellation types, and the cancellation action. Cancelability consists of three separate states (disabled, deferred, asynchronous) that can be represented by two boolean values. The default cancelability state is deferred.

For information about the examples included with the APIs, see the information on the API examples.

The thread cancellation APIs are:

• pthread_cancel() (Cancel Thread) requests cancellation of the target thread.
• pthread_cleanup_peek_np() (Copy Cleanup Handler from Cancellation Cleanup Stack) returns a copy of the cleanup handler entry that the next call to pthread_cleanup_pop() would pop.
• pthread_cleanup_pop() (Pop Cleanup Handler off of Cancellation Cleanup Stack) pops the last cleanup handler from the cancellation cleanup stack.
• pthread_cleanup_push() (Push Cleanup Handler onto Cancellation Cleanup Stack) pushes a cancellation cleanup routine onto the calling threads cancellation cleanup stack.
• pthread_getcancelstate_np() (Get Cancel State) gets the current cancel state of the thread.
• pthread_setcancelstate() (Set Cancel State) sets the cancel state to one of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE and returns the old cancel state into the location specified by oldstate (if oldstate is non-NULL).
• pthread_setcanceltype() (Set Cancel Type) sets the cancel type to one of PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS and returns the old cancel type into the location specified by oldtype (if oldtype is non-NULL)
• pthread_test_exit_np() (Test Thread Exit Status) returns the current state of the thread along with its exit status.
• pthread_testcancel() (Create Cancellation Point) creates a cancellation point in the calling thread.