From 7523c7c4d75652f67cd31cb123e1268790394c8b Mon Sep 17 00:00:00 2001 From: rpj Date: Fri, 6 May 2005 07:27:10 +0000 Subject: '' --- manual/pthread_setcanceltype.html | 207 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 manual/pthread_setcanceltype.html (limited to 'manual/pthread_setcanceltype.html') diff --git a/manual/pthread_setcanceltype.html b/manual/pthread_setcanceltype.html new file mode 100644 index 0000000..935ed82 --- /dev/null +++ b/manual/pthread_setcanceltype.html @@ -0,0 +1,207 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

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) (not supported under +Pthreads-w32)

+

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.

+

See Also

+

pthread_exit(3) , +pthread_cleanup_push(3) +, pthread_cleanup_pop(3) +, Pthreads-w32 package README file 'Prerequisites' section. +

+

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
+ + + -- cgit v1.2.3