1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\"*******************************************************************
28 .\" This file was generated with po4a. Translate the source file.
30 .\"*******************************************************************
31 .TH PTHREAD_CANCEL 3 2008\-11\-17 Linux "Linux Programmer's Manual"
33 pthread_cancel \- スレッドにキャンセル要求を送る
36 \fB#include <pthread.h>\fP
38 \fBint pthread_cancel(pthread_t \fP\fIthread\fP\fB);\fP
40 \fI\-pthread\fP でコンパイルしてリンクする。
43 \fBpthread_cancel\fP() 関数は指定されたスレッド \fIthread\fP にキャンセル要求
44 を送信する。対象のスレッドがキャンセル要求に反応するかどうか、いつ反応
45 するかは対象のスレッドの制御下にある 2 つの属性、cancelability
46 \fIstate\fP と \fItype\fPにより決まる。
48 あるスレッドの cancelability state は \fBpthread_setcancelstate\fP(3) で
49 設定され、\fIenabled\fP と \fIdisabled\fP のいずれとなる (\fIenabled\fP が新しい
50 スレッドのデフォルト値である)。スレッドがキャンセルを無効にしていた場合、
51 キャンセル要求はそのスレッドがキャンセルを有効にするまでキューに入れら
52 れたままになる。スレッドがキャンセルを有効にしていた場合、
53 cancelability type によって、いつキャンセルが発生するかが決まる。
55 スレッドのキャンセル種別 (cancelability type) は
56 \fBpthread_setcanceltype\fP(3) で設定され、\fIasynchronous\fP か \fIdeferred\fP
57 のいずれかとなる(\fIdeferred\fP が新しいスレッドのデフォルト値である)。
58 非同期キャンセル (asynchronous cancelability) は、そのスレッドはいつで
59 もキャンセルされることを意味する (通常はすぐにキャンセルされるが、
60 システムがそのことを保証しているわけではない)。遅延キャンセル
61 (deferred cancelability) では、そのスレッドが \fI取り消しポイント
62 (cancellation point)\fP となっている関数を次に呼び出すまでキャンセルが
63 遅延される。取り消しポイントに設定されていたり設定
64 したりできる関数のリストは \fIpthreads\fP(7) に記載している。
67 \fIthread\fP では以下のステップが (この順序で) 行われる。
69 キャンセルクリーンアップハンドラが (push されたのと逆順で)
70 取り出され (pop され)、呼び出される。
71 (\fBpthread_cleanup_push\fP(3) 参照)
73 スレッド固有データのデストラクタ (destructor) が呼び出される。
75 (\fBpthread_key_create\fP(3) 参照)
77 スレッドが終了される。 (\fBpthread_exit\fP(3) 参照)
79 上記のステップは \fBpthread_cancel\fP() の呼び出しとは非同期に行われる。
80 \fBpthread_cancel\fP() の返却ステータスは単にキャンセル要求が正常に
81 キューに入れられたかどうかを呼び出し元に示すだけのものである。
84 \fBpthread_join\fP(3) でそのスレッドを join すると、
85 そのスレッドの終了ステータスとして \fBPTHREAD_CANCELED\fP が得られる。
86 (スレッドの join はキャンセルが完了したかを知る唯一の方法である)
88 成功すると、 \fBpthread_cancel\fP() は 0 を返す。
94 .\" Available since glibc 2.0
95 ID が \fIthread\fP のスレッドが見つからなかった。
99 Linux では、キャンセルはシグナルを使って実装されている。NPTL スレッド実装では、
100 最初のリアルタイムシグナル (つまり、シグナル 32)がこのために使用される。
101 LinuxThreads では、リアルタイムシグナルが利用可能な場合は2 番目のリアルタイム
102 シグナルが使用され、そうでない場合は \fBSIGUSR2\fP が使用される。
104 以下のプログラムは、スレッドを一つ作成してから、そのスレッドをキャンセルする。
105 メインスレッドはキャンセルされたスレッドをジョインし、
106 キャンセルされたスレッドの終了ステータスが \fBPTHREAD_CANCELED\fP かどうかを
107 確認する。以下のシェルセッションはこのプログラムを実行した際の実行例である。
112 thread_func(): started; cancellation disabled
113 main(): sending cancellation request
114 thread_func(): about to enable cancellation
115 main(): thread was canceled
127 #define handle_error_en(en, msg) \e
128 do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
131 thread_func(void *ignored_argument)
135 /* Disable cancellation for a while, so that we don\(aqt
136 immediately react to a cancellation request */
138 s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
140 handle_error_en(s, "pthread_setcancelstate");
142 printf("thread_func(): started; cancellation disabled\en");
144 printf("thread_func(): about to enable cancellation\en");
146 s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
148 handle_error_en(s, "pthread_setcancelstate");
150 /* sleep() is a cancellation point */
152 sleep(1000); /* Should get canceled while we sleep */
154 /* Should never get here */
156 printf("thread_func(): not canceled!\en");
167 /* Start a thread and then send it a cancellation request */
169 s = pthread_create(&thr, NULL, &thread_func, NULL);
171 handle_error_en(s, "pthread_create");
173 sleep(2); /* Give thread a chance to get started */
175 printf("main(): sending cancellation request\en");
176 s = pthread_cancel(thr);
178 handle_error_en(s, "pthread_cancel");
180 /* Join with thread to see what its exit status was */
182 s = pthread_join(thr, &res);
184 handle_error_en(s, "pthread_join");
186 if (res == PTHREAD_CANCELED)
187 printf("main(): thread was canceled\en");
189 printf("main(): thread wasn\(aqt canceled (shouldn\(aqt happen!)\en");
196 \fBpthread_cleanup_push\fP(3), \fBpthread_create\fP(3), \fBpthread_exit\fP(3),
197 \fBpthread_join\fP(3), \fBpthread_key_create\fP(3), \fBpthread_setcancelstate\fP(3),
198 \fBpthread_setcanceltype\fP(3), \fBpthread_testcancel\fP(3), \fBpthreads\fP(7)
200 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.53 の一部
201 である。プロジェクトの説明とバグ報告に関する情報は
202 http://www.kernel.org/doc/man\-pages/ に書かれている。