• 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.

Cancellation Points

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

pthread_cancel(3THR)

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.

Return Values

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.

ESRCH

No thread could be found corresponding to that specified by the given thread ID.

Enable or Disable Cancellation

pthread_setcancelstate(3THR)

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);

Return Values

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.

EINVAL

The state is not PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.

Set Cancellation Type

pthread_setcanceltype(3THR)

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);

Return Values

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.

EINVAL

The type is not PTHREAD_CANCEL_DEFERRED or PTHREAD_CANCEL_ASYNCHRONOUS.

Create a Cancellation Point

pthread_testcancel(3THR)

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.