PTHREAD_CANCEL(3) manual page

From 41f88a82b33cdb357c83b582381232733ed2d039 Mon Sep 17 00:00:00 2001 From: rpj Date: Thu, 5 May 2005 14:18:27 +0000 Subject: '' --- manual/pthread_cancel.html | 203 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 manual/pthread_cancel.html (limited to 'manual/pthread_cancel.html') diff --git a/manual/pthread_cancel.html b/manual/pthread_cancel.html new file mode 100644 index 0000000..d8a6429 --- /dev/null +++ b/manual/pthread_cancel.html @@ -0,0 +1,203 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

Table of Contents

Name

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

Synopsis

#include <pthread.h> +

int pthread_cancel(pthread_t thread); +

int pthread_setcancelstate(int state, int +*oldstate); +

int pthread_setcanceltype(int type, int +*oldtype); +

void pthread_testcancel(void); +

Description

Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, +the target thread can then either ignore the request, honor it +immediately, or defer it until it reaches a cancellation point. +

When a thread eventually honors a cancellation request, it +performs as if pthread_exit(PTHREAD_CANCELED) has been called +at that point: all cleanup handlers are executed in reverse order, +destructor functions for thread-specific data are called, and finally +the thread stops executing with the return value PTHREAD_CANCELED. +See pthread_exit(3) for more +information. +

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

pthread_setcancelstate changes the cancellation state for +the calling thread -- that is, whether cancellation requests are +ignored or not. The state argument is the new cancellation +state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or +PTHREAD_CANCEL_DISABLE to disable cancellation (cancellation +requests are ignored). If oldstate is not NULL, the +previous cancellation state is stored in the location pointed to by +oldstate, and can thus be restored later by another call to +pthread_setcancelstate. +

pthread_setcanceltype changes the type of responses to +cancellation requests for the calling thread: asynchronous +(immediate) or deferred. The type argument is the new +cancellation type: either PTHREAD_CANCEL_ASYNCHRONOUS to +cancel the calling thread as soon as the cancellation request is +received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation +request pending until the next cancellation point. If oldtype +is not NULL, the previous cancellation state is stored in the +location pointed to by oldtype, and can thus be restored later +by another call to pthread_setcanceltype. +

Pthreads-w32 provides two levels of support for +PTHREAD_CANCEL_ASYNCHRONOUS: full and partial. Full support +requires an additional DLL and driver be installed on the Windows +system (see the See Also section below) that allows blocked threads +to be cancelled immediately. Partial support means that the target +thread will not cancel until it resumes execution naturally. Partial +support is provided if either the DLL or the driver are not +automatically detected by the pthreads-w32 library at run-time.

Threads are always created by pthread_create(3) +with cancellation enabled and deferred. That is, the initial +cancellation state is PTHREAD_CANCEL_ENABLE and the initial +type is PTHREAD_CANCEL_DEFERRED. +

Cancellation points are those points in the program execution +where a test for pending cancellation requests is performed and +cancellation is executed if positive. The following POSIX threads +functions are cancellation points: +

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3)
sem_wait(3) +
sem_timedwait(3)
sigwait(3)

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

pthreadCancelableWait() +
pthreadCancelableTimedWait()

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

pthread_testcancel does nothing except testing for pending +cancellation and executing it. Its purpose is to introduce explicit +checks for cancellation in long sequences of code that do not call +cancellation point functions otherwise. +

Return Value

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

Errors

pthread_cancel returns the following error code on error: +

ESRCH +: + no thread could be found corresponding to that specified by the + thread ID. +

+ +

+pthread_setcancelstate returns the following error code on +error: +

EINVAL +: + the state argument is not +

+ +

+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +

pthread_setcanceltype returns the following error code on +error: +

EINVAL +: + the type argument is not +

+ +

+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +

Author

Xavier Leroy <Xavier.Leroy@inria.fr> +

Modified by Ross Johnson for use with Pthreads-w32.

Bugs

POSIX specifies that a number of system calls (basically, all +system calls that may block, such as read(2) +, write(2) , wait(2) +, etc.) and library functions that may call these system calls (e.g. +fprintf(3) ) are cancellation +points. Pthreads-win32 is not integrated enough with the C +library to implement this, and thus none of the C library functions +is a cancellation point. +

A workaround for these calls is to temporarily switch to +asynchronous cancellation (assuming full asynchronous cancellation +support is installed). So, checking for cancellation during a read +system call, for instance, can be achieved as follows: +

+

pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);

Table of Contents

Name +
+
Synopsis +
+
Description +
+
Return + Value +
+
Errors +
+
Author +
+
See + Also +
+
Bugs +
+

+ + -- cgit v1.2.3