pthread_cancel

Allows a thread to request that it or another thread terminate execution.

Syntax

pthread_cancel( thread );

Argument Data Type Access

thread opaque pthread_t read

C Binding

#include 


int
pthread_cancel (
         pthread_t   thread);

Arguments

thread: Thread that receives a cancel request.

Description

This routine sends a cancel to the specified thread. A cancel is a mechanism by which a calling thread requests the specified thread to terminate as quickly as possible. Issuing a cancel does not guarantee that the specified thread will receive or handle the cancel. When the cancellation is acted on, all active cleanup handlers for thread are called. When the last cleanup handler returns, the thread-specific data destructor functions shall be called for each thread-specific data key with a destructor and for which the thread has a non-NULL value. Finally, the thread is terminated.

The cancellation processing in the target thread runs asychronously with respect to the calling thread returning from pthread_cancel. The target thread cancelability state and type determine when or if the cancellation takes place:

The canceled thread can delay cancellation during critical operations by setting its cancelability state to PTHREAD_CANCEL_ DISABLE.
Because of communication delays, the calling thread can only rely on the fact that a cancel will eventually become pending in the designated thread (provided that the thread does not terminate beforehand).
The calling thread has no guarantee that a pending cancel will be delivered, because delivery is controlled by the designated thread.

When a cancel is delivered to a thread, termination processing is similar to pthread_exit. For more information about thread termination, see the Thread Termination section of pthread_create.

This routine is preferred in implementing an Ada abort statement and any other language- or software-defined construct for requesting thread cancellation.

The results of this routine are unpredictable if the value specified in thread refers to a thread that does not currently exist.

Return Values

If an error condition occurs, this routine returns an integer indicating the type of error. Possible return values are as follows:

Return Description

0 Successful completion. [EINVAL] The specified thread is invalid. [ESRCH] thread does not specify an existing thread.

Associated Routines

   pthread_cleanup_pop
   pthread_cleanup_push
   pthread_create
   pthread_exit
   pthread_join
   pthread_setcancelstate
   pthread_setcanceltype
   pthread_testcancel