pthread_setcancelstate(3P)pthread_setcancelstate(3P)NAME
pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel -
manage cancelability of a thread
C SYNOPSIS
#include <pthread.h>
int pthread_setcancelstate(int new_state, int *old_state);
int pthread_setcanceltype(int new_type, int *old_type);
void pthread_testcancel(void);
DESCRIPTION
The cancelability of a thread determines when, if ever, it acts upon
cancellation requests [see pthread_cancel(), and pthread_exit()].
Cancellation state may be either PTHREAD_CANCEL_ENABLE or
PTHREAD_CANCEL_DISABLE. If it is PTHREAD_CANCEL_DISABLE, then
cancellation requests are blocked (held pending) indefinitely. If the
state is PTHREAD_CANCEL_ENABLE, the cancellation type is the governing
factor.
Cancellation type may be either PTHREAD_CANCEL_ASYNCHRONOUS or
PTHREAD_CANCEL_DEFERRED. The type only affects the cancelability of a
thread if the cancellation state is PTHREAD_CANCEL_ENABLE.
If the type is PTHREAD_CANCEL_DEFERRED, cancellation requests are only
acted on when the thread is in a known state, namely that it enters or is
waiting in a set of functions known as cancellation points (see NOTES).
Usually these are functions in which a thread may block for an unbounded
period of time. If the cancellation request is acted upon at a
cancellation point, the operation associated with the function is
aborted. For example, if a read() is in progress when the thread is
cancelled, then either the read() will return data or the cancellation
will be acted upon. Should the thread read data before the request
arrives, it will not be cancelled.
If the type is PTHREAD_CANCEL_ASYNCHRONOUS, then cancellation requests
may take effect immediately. This type of cancellation should only be
used when the state of target thread is known. If the target thread is
executing exclusively in user code (for example in a computation loop)
this is safe. However, this is not the case if the thread makes calls to
a library. For this reason deferred cancellation should be preferred to
asynchronous cancellation.
Cancellation handlers [see pthread_cleanup_push()] can be used to restore
application state when a thread is cancelled.
When threads start, their cancellation state is PTHREAD_CANCEL_ENABLE and
their cancellation type is PTHREAD_CANCEL_DEFERRED.
Page 1
pthread_setcancelstate(3P)pthread_setcancelstate(3P)
The pthread_setcancelstate() function changes the calling thread's
cancellation state to new_state which can be either
PTHREAD_CANCEL_DISABLE or PTHREAD_CANCEL_ENABLE. If old_state is not
NULL, then it is used to return the previous state. If the state is
changed to PTHREAD_CANCEL_ENABLE and there is a cancellation request
pending, then it will be acted on immediately.
The pthread_setcanceltype() function changes the calling thread's
cancellation type to new_type which can be either
PTHREAD_CANCEL_ASYNCHRONOUS or PTHREAD_CANCEL_DEFERRED. If old_type is
not NULL, then it is used to return the previous type.
The pthread_testcancel() function is a cancellation point. If
cancellation is enabled and a cancellation request is pending on the
thread, then calling this function will terminate the thread.
DIAGNOSTICS
The functions pthread_setcancelstate() and pthread_setcanceltype() return
zero.
SEE ALSOpthread_cancel(3P), pthread_exit(3P), pthread_cleanup_push(3P).
NOTES
The following functions are cancellation points:
accept(2)aio_suspend(3)close(2)connect(2)creat(2)fcntl(2)fsync(2)getmsg(2)getpmsg(2)lockf(3C) mq_receive mq_send
msgrcv(2)msgsnd(2)msync(2)nanosleep(2)open(2)pause(2)poll(2)pread(2)pthread_cond_timedwait(3P)pthread_cond_wait(3P)pthread_join(3P)pthread_testcancel(3P)putmsg(2)putpmsg(2)pwrite(2)read(2)readv(2)recv(2)recvfrom(2)recvmsg(2)select(2)
sem_wait semop(2)send(2)sendmsgsendto(2)sigpause(2)sigsuspend(2)sigtimedwait(3)sigwait(3)sigwaitinfo(3)sleep(3C)system(3S)tcdrain(3t)usleep(3C)wait(2)wait3(2)waitid(2)waitpid(2)write(2)writev(2)
Page 2
