svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
cancellation(7)
ca...n(7)Standards, Environments, Macros, Character Sets, and miscellancya...n(7)
NAME
cancellation - overview of concepts related to POSIX thread cancella‐
tion
DESCRIPTION
tab() box; cw(2.18i) |cw(3.32i) lw(2.18i) |lw(3.32i) FUNCTIONACTION _
pthread_cancel()Cancels thread execution. pthread_setcancelstate()Sets
the cancellation state of a thread. pthread_setcanceltype()Sets the
cancellation type of a thread. pthread_testcancel()T{ Creates a can‐
cellation point in the calling thread. T} pthread_cleanup_push()Pushes
a cleanup handler routine. pthread_cleanup_pop()Pops a cleanup handler
routine.
Cancellation
Thread cancellation allows a thread to terminate the execution of any
application thread in the process. Cancellation is useful when further
operations of one or more threads are undesirable or unnecessary.
An example of a situation that could benefit from using cancellation is
an asynchronously-generated cancel condition such as a user requesting
to close or exit some running operation. Another example is the comple‐
tion of a task undertaken by a number of threads, such as solving a
maze. While many threads search for the solution, one of the threads
might solve the puzzle while the others continue to operate. Since they
are serving no purpose at that point, they should all be canceled.
Planning Steps
Planning and programming for most cancellations follow this pattern:
1. Identify which threads you want to cancel, and insert
pthread_cancel(3C) statements.
2. Identify system-defined cancellation points where a thread
that might be canceled could have changed system or program
state that should be restored. See the Cancellation Points
for a list.
3. When a thread changes the system or program state just be‐
fore a cancellation point, and should restore that state be‐
fore the thread is canceled, place a cleanup handler before
the cancellation point with pthread_cleanup_push(3C). Wher‐
ever a thread restores the changed state, pop the cleanup
handler from the cleanup stack with pthread_cleanup_pop(3C).
4. Know whether the threads you are canceling call into cancel-
unsafe libraries, and disable cancellation with pthread_set‐
cancelstate(3C) before the call into the library. See Can‐
cellation State and Cancel-Safe.
5. To cancel a thread in a procedure that contains no cancella‐
tion points, insert your own cancellation points with
pthread_testcancel(3C). This function creates cancellation
points by testing for pending cancellations and performing
those cancellations if they are found. Push and pop cleanup
handlers around the cancellation point, if necessary (see
Step 3, above).
Cancellation Points
The system defines certain points at which cancellation can occur (can‐
cellation points), and you can create additional cancellation points in
your application with pthread_testcancel().
The following cancellation points are defined by the system (system-de‐
fined cancellation points): creat(2), aio_suspend(3C), close(2),
getmsg(2), getpmsg(2), lockf(3C), mq_receive(3C), mq_send(3C), ms‐
grcv(2), msgsnd(2), msync(3C), nanosleep(3C), open(2), pause(2),
poll(2), pread(2), preadv(2), pthread_cond_timedwait(3C),
pthread_cond_wait(3C), pthread_join(3C), pthread_testcancel(3C),
putmsg(2), putpmsg(2), pwrite(2), pwritev(2), read(2), readv(2), se‐
lect(3C), sem_wait(3C), sigpause(3C), sigwaitinfo(3C), sigsuspend(2),
sigtimedwait(3C), sigwait(2), sleep(3C), sync(2), system(3C),
tcdrain(3C), usleep(3C), wait(3C), waitid(2), wait3(3C), waitpid(3C),
write(2), writev(2), and fcntl(2), when specifying F_SETLKW as the com‐
mand.
When cancellation is asynchronous, cancellation can occur at any time
(before, during, or after the execution of the function defined as the
cancellation point). When cancellation is deferred (the default case),
cancellation occurs only within the scope of a function defined as a
cancellation point (after the function is called and before the func‐
tion returns). See Cancellation Type for more information about de‐
ferred and asynchronous cancellation.
Choosing where to place cancellation points and understanding how can‐
cellation affects your program depend upon your understanding of both
your application and of cancellation mechanics.
Typically, any call that might require a long wait should be a cancel‐
lation point. Operations need to check for pending cancellation re‐
quests when the operation is about to block indefinitely. This includes
threads waiting in pthread_cond_wait() and pthread_cond_timedwait(),
threads waiting for the termination of another thread in
pthread_join(), and threads blocked on sigwait().
A mutex is explicitly not a cancellation point and should be held for
only the minimal essential time.
Most of the dangers in performing cancellations deal with properly
restoring invariants and freeing shared resources. For example, a care‐
lessly canceled thread might leave a mutex in a locked state, leading
to a deadlock. Or it might leave a region of memory allocated with no
way to identify it and therefore no way to free it.
Cleanup Handlers
When a thread is canceled, it should release resources and clean up the
state that is shared with other threads. So, whenever a thread that
might be canceled changes the state of the system or of the program, be
sure to push a cleanup handler with pthread_cleanup_push(3C) before the
cancellation point.
When a thread is canceled, all the currently-stacked cleanup handlers
are executed in last-in-first-out (LIFO) order. Each handler is run in
the scope in which it was pushed. When the last cleanup handler re‐
turns, the thread-specific data destructor functions are called. Thread
execution terminates when the last destructor function returns.
When, in the normal course of the program, an uncanceled thread re‐
stores state that it had previously changed, be sure to pop the cleanup
handler (that you had set up where the change took place) using
pthread_cleanup_pop(3C). That way, if the thread is canceled later,
only currently-changed state will be restored by the handlers that are
left in the stack.
The pthread_cleanup_push() and pthread_cleanup_pop() functions can be
implemented as macros. The application must ensure that they appear as
statements, and in pairs within the same lexical scope (that is, the
pthread_cleanup_push() macro can be thought to expand to a token list
whose first token is '{' with pthread_cleanup_pop() expanding to a to‐
ken list whose last token is the corresponding '}').
The effect of the use of return, break, continue, and goto to prema‐
turely leave a code block described by a pair of pthread_cleanup_push()
and pthread_cleanup_pop() function calls is undefined.
Cancellation State
Most programmers will use only the default cancellation state of
PTHREAD_CANCEL_ENABLE, but can choose to change the state by using
pthread_setcancelstate(3C), which determines whether a thread is cance‐
lable at all. With the default state of PTHREAD_CANCEL_ENABLE, cancel‐
lation is enabled and the thread is cancelable at points determined by
its cancellation type. See Cancellation Type.
If the state is PTHREAD_CANCEL_DISABLE, cancellation is disabled, the
thread is not cancelable at any point, and all cancellation requests to
it are held pending.
You might want to disable cancellation before a call to a cancel-unsafe
library, restoring the old cancel state when the call returns from the
library. See Cancel-Safe for explanations of cancel safety.
Cancellation Type
A thread's cancellation type is set with pthread_setcanceltype(3C), and
determines whether the thread can be canceled anywhere in its execution
or only at cancellation points.
With the default type of PTHREAD_CANCEL_DEFERRED, the thread is cance‐
lable only at cancellation points, and then only when cancellation is
enabled.
If the type is PTHREAD_CANCEL_ASYNCHRONOUS, the thread is cancelable at
any point in its execution (assuming, of course, that cancellation is
enabled). Try to limit regions of asynchronous cancellation to se‐
quences with no external dependencies that could result in dangling re‐
sources or unresolved state conditions. Using asynchronous cancellation
is discouraged because of the danger involved in trying to guarantee
correct cleanup handling at absolutely every point in the program.
Table 1 Cancellation Type/State Table
tab() box; cw(1.51i) |cw(1.99i) lw(1.51i) |lw(1.99i) |lw(1.99i) TypeS‐
tate _ Enabled (Default)Disabled _ Deferred (Default)T{ Cancellation
occurs when the target thread reaches a cancellation point and a cancel
is pending. (Default) T}T{ All cancellation requests to the target
thread are held pending. T} _ AsynchronousT{ Receipt of a pthread_can‐
cel() call causes immediate cancellation. T}T{ All cancellation re‐
quests to the target thread are held pending; as soon as cancellation
is re-enabled, pending cancellations are executed immediately. T}
Cancel-Safe
With the arrival of POSIX cancellation, the Cancel-Safe level has been
added to the list of MT-Safety levels. See attributes(7). An applica‐
tion or library is Cancel-Safe whenever it has arranged for cleanup
handlers to restore system or program state wherever cancellation can
occur. The application or library is specifically Deferred-Cancel-Safe
when it is Cancel-Safe for threads whose cancellation type is
PTHREAD_CANCEL_DEFERRED. See Cancellation State. It is specifically
Asynchronous-Cancel-Safe when it is Cancel-Safe for threads whose can‐
cellation type is PTHREAD_CANCEL_ASYNCHRONOUS.
It is easier to arrange for deferred cancel safety, as this requires
system and program state protection only around cancellation points. In
general, expect that most applications and libraries are not Asynchro‐
nous-Cancel-Safe.
POSIX Threads Only
The cancellation functions described in this manual page are available
for POSIX threads only, as the Solaris threads interfaces do not pro‐
vide cancellation functions. See threads(7) for more information about
the differences between these thread APIs.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ MT-LevelMT-Safe
SEE ALSO
read(2), sigwait(2), write(2), Intro(3), pthread_cleanup_pop(3C),
pthread_cleanup_push(3C), pthread_exit(3C), pthread_join(3C),
pthread_setcancelstate(3C), pthread_setcanceltype(3C), pthread_testcan‐
cel(3C), setjmp(3C), attributes(7), condition(7), standards(7),
threads(7)
Oracle Solaris 11.4 Multithreaded Programming Guide
Oracle Solaris 11.4 8 Jan 2024 ca...n(7)