pthread_cancel() -- cancel execution of a thread

SYNOPSIS

#include <pthread.h>

int pthread_cancel(pthread_t thread);

The pthread_cancel() function requests that thread be canceled. Assuming that cancellation is enabled for the specified thread (see pthread_setcancelstate()), cancellation either happens immediately (if the thread has PTHREAD_CANCEL_ASYNCHRONOUS type set) or when the thread reaches a cancellation point (if the thread has PTHREAD_CANCEL_DEFERRED type set) The default cancellation type is PTHREAD_CANCEL_DEFERRED (see pthread_setcanceltype()). Cancellation cleanup handlers for thread are called when the cancellation is acted on. thread terminates when the last destructor function returns. The thread exit status returned by pthread_join() on a canceled thread is PTHREAD_CANCELED. Note that when a thread is cancelled, the thread-specific data destructor functions (see pthread_key_create()) are not invoked.

Thread Cancellation

Thread cancellation lets a thread terminate the execution of any other thread in the process. When a cancellation requested is acted on, the target thread (the thread being cancelled) is allowed to defer cancellation requests and to perform application-specific cleanup processing.

As a thread acquires resources (for example, mutexes) around areas where it may be cancelled (that is, before a cancellation point), it needs to push cancellation cleanup handlers along with the acquisition of these resources. The cleanup handlers release these resources and are invoked only if the thread were to be cancelled. As the thread leaves the last cancellation point before releasing a resource, it needs to pop the cleanup handler it had pushed earlier for this resource.

When a thread is cancelled, all the currently stacked cleanup handlers are executed and thread execution is terminated when the last cancellation cleanup handler returns. The thread exit status returned by pthread_join() on a canceled thread is PTHREAD_CANCELED.

Cancellation State and Type

The thread's cancellation state and type determine when, if ever, a thread cancellation request is acted on. The cancellation state can be set to PTHREAD_CANCEL_DISABLE, in which case all cancellation requests are held pending. If the cancellation state is PTHREAD_CANCEL_ENABLE, cancellation requests are acted on according to the threads cancellation type. The default cancellation state is PTHREAD_CANCEL_ENABLE.

The thread cancellation type determines when the cancellation request is acted on. If the cancellation type is set to PTHREAD_CANCEL_ASYNCHRONOUS, the cancellation request is acted on immediately. If the cancellation type is set to PTHREAD_CANCEL_DEFERRED, the cancellation request is not acted on until the thread reaches a cancellation point. (see Cancellation Points). The default cancellation type is PTHREAD_CANCEL_DEFERRED.

If cancellation is enabled and asynchronous cancellation has been requested, the thread must call only async-cancel-safe functions, since the thread may be cancelled by the system at any time. At this time, the only async-cancel-safe functions are pthread_testcancel(), pthread_setcanceltype(), and pthread_setcancelstate(). Calling any other functions may leave the process in an inconsistent state.

Cancellation Points

If cancellation is enabled, and its type is deferred, the system tests for pending cancellation requests in certain defined functions (usually any blocking system function). These points are known as cancellation points.

Cancellation points may be created in user code with the pthread_testcancel() function.

Other thread-related functions that are cancellation points include pthread_cond_wait(), pthread_cond_timedwait(), pthread_join(), and sigwait(). pthread_mutex_lock() is not a cancellation point, although it may block indefinitely; making pthread_mutex_lock() a cancellation point would make writing correct cancellation handlers difficult, if not impossible.

The following functions are cancellation points: close(), creat(), fcntl(), fsync(), lockf(), nanosleep(), open(), pause(), pthread_cond_timedwait(), pthread_cond_wait(), pthread_join(), pthread_testcancel(), read(), readv(), select(), sigpause(), sigsuspend(), sigwait(), sleep(), system(), tcdrain(), usleep(), wait(), waitpid(), write(), writev().

In addition, a cancellation point may occur in the following functions: catclose(), catgets(), catopen(), closedir(), closelog(), ctermid(), dlclose(), dlopen(), fclose(), fcntl(), fflush(), fgetc(), fgetpos(), fgets(), fopen(), fprintf(), fputc(), fputs(), fread(), freopen(), fscanf(), fseek(), fsetpos(), ftell(), fwrite(), getc(), getc_unlocked() getchar(), getchar_unlocked(), getcwd(), getgrgid(), getgrgid_r(), getgrnam(), getgrnam_r(), getlogin(), getlogin_r(), getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), gets(), getwd(), glob(), ioctl(), lseek(), mkstemp(), opendir(), openlog(), pclose(), perror(), popen(), printf(), putc(), putc_unlocked() putchar(), putchar_unlocked(), puts(), readdir(), readdir_r(), remove(), rename(), rewind(), rewinddir(), scanf(), semop(), strerror(), syslog(), tmpfile(), tmpnam(), ttyname(), ttyname_r(), ungetc(), unlink(), vfprintf(), vprintf().

Cancellation Cleanup Handlers

An application should set up a cancellation cleanup handling function to restore any resources before a thread reaches a cancellation point. Specified cancellation points allow programmers to easily keep track of actions needed in a cancellation cleanup handler. A thread should only be made asynchronously cancelable when it is not in the process of acquiring or releasing resources (or locks), or otherwise, not in a difficult or impossible recover state.

Cancellation handlers are installed and removed with the pthread_cleanup_push() and pthread_cleanup_pop() functions. When a cancellation request is acted on, the routines in the list are invoked one-by-one in LIFO (last-in, first-out) order.

PARAMETERS

thread: Is the thread to be cancelled.

RETURN VALUES

On success, pthread_cancel() returns 0. On error, one of the following values is returned:

ESRCH: thread does not specify a currently running thread in the process.

pthread_cancel()
cancel execution of a thread

Function

SYNOPSIS

DESCRIPTION

Thread Cancellation

Cancellation State and Type

Cancellation Points

Cancellation Cleanup Handlers

PARAMETERS

RETURN VALUES

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO

pthread_cancel() cancel execution of a thread

Function

pthread_cancel()
cancel execution of a thread