At discrete points specified by the application
By default, cancellation can occur only at well-defined points as defined by the POSIX standard.
In all cases, take care that resources and state are restored to a condition consistent with the point of origin.
Be careful to cancel a thread only when cancellation is safe. The pthreads standard specifies several cancellation points, including:
Programmatically establish a thread cancellation point through a pthread_testcancel(3THR) call.
Threads waiting for the occurrence of a particular condition in pthread_cond_wait(3THR) or pthread_cond_timedwait(3THR).
Threads waiting for termination of another thread in pthread_join(3THR).
Threads blocked on sigwait(2).
Some standard library calls. In general, these are functions in which threads can block; see the man page cancellation(3THR) for a list.
Cancellation is enabled by default. At times you might want an application to disable cancellation. This has the result of deferring all cancellation requests until they are enabled again.
See "pthread_setcancelstate(3THR)" for information about disabling cancellation.
Cancel a Thread
Use pthread_cancel(3THR) to cancel a thread.
Prototype: int pthread_cancel(pthread_t thread);
#include <pthread.h> pthread_t thread; int ret; ret = pthread_cancel(thread);
How the cancellation request is treated depends on the state of the target thread. Two functions, pthread_setcancelstate(3THR) and pthread_setcanceltype(3THR), determine that state.
pthread_cancel() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.
No thread could be found corresponding to that specified by the given thread ID.
Enable or Disable Cancellation
Use pthread_setcancelstate(3THR) to enable or disable thread cancellation. When a thread is created, thread cancellation is enabled by default.
Prototype: int pthread_setcancelstate(int state, int *oldstate);
#include <pthread.h> int oldstate; int ret; /* enabled */ ret = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, &oldstate); /* disabled */ ret = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, &oldstate);
pthread_setcancelstate() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the pthread_setcancelstate() function fails and returns the corresponding value.
The state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.
Set Cancellation Type
Use pthread_setcanceltype(3THR) to set the cancellation type to either deferred or asynchronous mode. When a thread is created, the cancellation type is set to deferred mode by default. In deferred mode, the thread can be cancelled only at cancellation points. In asynchronous mode, a thread can be cancelled at any point during its execution. Using asynchronous mode is discouraged.
Prototype: int pthread_setcanceltype(int type, int *oldtype);
#include <pthread.h> int oldtype; int ret; /* deferred mode */ ret = pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype); /* async mode*/ ret = pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldtype);
pthread_setcanceltype() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.
The type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.
Create a Cancellation Point
Use pthread_testcancel(3THR) to establish a cancellation point for a thread.
Prototype: void pthread_testcancel(void);
#include <pthread.h> pthread_testcancel();
The pthread_testcancel() function is effective when thread cancellation is enabled and in deferred mode. Calling this function while cancellation is disabled has no effect.
Be careful to insert pthread_testcancel() only in sequences where it is safe to cancel a thread. In addition to programmatically establishing cancellation points through the pthread_testcancel() call, the pthreads standard specifies several cancellation points. See "Cancellation Points" for more details.
There is no return value.