PTHREAD_CANCEL(3) PTHREAD_CANCEL(3)
NAME
pthread_cancel, pthread_setcancelstate, pthread_setcancel-
type, pthread_testcancel - thread cancellation
SYNOPSIS#include<pthread.h>intpthread_cancel(pthread_tthread);intpthread_setcancelstate(intstate,int*oldstate);intpthread_setcanceltype(inttype,int*oldtype);voidpthread_testcancel(void);DESCRIPTION
Cancellation is the mechanism by which a thread can termi-
nate 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 cancel-
lation (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 cancella-
tion point. If oldtype is not NULL, the previous cancella-
tion state is stored in the location pointed to by old-type, and can thus be restored later by another call to
pthread_setcanceltype.
Threads are always created by pthread_create(3) with can-
cellation enabled and deferred. That is, the initial can-
cellation state is PTHREAD_CANCEL_ENABLE and the initial
type is PTHREAD_CANCEL_DEFERRED.
Cancellation points are those points in the program execu-
tion 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)
sigwait(3)
All other POSIX threads functions are guaranteed not to be
cancellation points. That is, they never perform cancella-
tion 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.
RETURNVALUEpthread_cancel, pthread_setcancelstate and pthread_set-canceltype return 0 on success and a non-zero error code
on error.
ERRORSpthread_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_CAN-CEL_ENABLE nor PTHREAD_CANCEL_DISABLEpthread_setcanceltype returns the following error code on
error:
EINVAL the type argument is not PTHREAD_CAN-CEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUSAUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>
SEEALSOpthread_exit(3), pthread_cleanup_push(3),
pthread_cleanup_pop(3).
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 cancella-
tion 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. Cancel-
lation requests are transmitted to the target thread by
sending it a signal. That signal will interrupt all block-
ing 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 fol-
lows:
pthread_testcancel();retcode=read(fd,buffer,length);pthread_testcancel();
LinuxThreads 1