diff options
Diffstat (limited to 'linuxthreads/man/pthread_cancel.man')
| -rw-r--r-- | linuxthreads/man/pthread_cancel.man | 155 |
1 files changed, 0 insertions, 155 deletions
diff --git a/linuxthreads/man/pthread_cancel.man b/linuxthreads/man/pthread_cancel.man deleted file mode 100644 index 202d5c9b26..0000000000 --- a/linuxthreads/man/pthread_cancel.man +++ /dev/null @@ -1,155 +0,0 @@ -.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 |