diff options
Diffstat (limited to 'linuxthreads/man/pthread_cancel.man')
| -rw-r--r-- | linuxthreads/man/pthread_cancel.man | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/linuxthreads/man/pthread_cancel.man b/linuxthreads/man/pthread_cancel.man new file mode 100644 index 0000000000..202d5c9b26 --- /dev/null +++ b/linuxthreads/man/pthread_cancel.man @@ -0,0 +1,155 @@ +.TH PTHREAD_CANCEL 3 LinuxThreads + +.XREF pthread_setcancelstate +.XREF pthread_setcanceltype +.XREF pthread_testcancel + +.SH NAME +pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel \- thread cancellation + +.SH 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); + +.SH 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 till 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, finalization +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!. + +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) +.br +!pthread_cond_wait!(3) +.br +!pthread_cond_timedwait!(3) +.br +!pthread_testcancel!(3) +.br +!sem_wait!(3) +.br +!sigwait!(3) + +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. + +.SH "RETURN VALUE" + +!pthread_cancel!, !pthread_setcancelstate! and +!pthread_setcanceltype! return 0 on success and a non-zero error code +on error. + +.SH ERRORS +!pthread_cancel! returns the following error code on error: +.RS +.TP +!ESRCH! +no thread could be found corresponding to that specified by the |thread| ID. +.RE + +!pthread_setcancelstate! returns the following error code on error: +.RS +.TP +!EINVAL! +the |state| argument is not !PTHREAD_CANCEL_ENABLE! nor +!PTHREAD_CANCEL_DISABLE! +.RE + +!pthread_setcanceltype! returns the following error code on error: +.RS +.TP +!EINVAL! +the |type| argument is not !PTHREAD_CANCEL_DEFERRED! nor +!PTHREAD_CANCEL_ASYNCHRONOUS! +.RE + +.SH AUTHOR +Xavier Leroy <Xavier.Leroy@inria.fr> + +.SH "SEE ALSO" +!pthread_exit!(3), +!pthread_cleanup_push!(3), +!pthread_cleanup_pop!(3). + +.SH 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. LinuxThreads is not yet +integrated enough with the C library to implement this, and thus none +of the C library functions is a cancellation point. + +For system calls at least, there is a workaround. Cancellation +requests are transmitted to the target thread by sending it a +signal. That signal will interrupt all blocking system calls, causing +them to return immediately with the !EINTR! error. So, checking for +cancellation during a !read! system call, for instance, can be +achieved as follows: + +.RS +.ft 3 +.nf +.sp +pthread_testcancel(); +retcode = read(fd, buffer, length); +pthread_testcancel(); +.ft +.LP +.RE +.fi |