draft/man3/pthread_cancel.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" This file was generated with po4a. Translate the source file.
  27 .\"
  28 .\"*******************************************************************
  29 .TH PTHREAD_CANCEL 3 2008\-11\-17 Linux "Linux Programmer's Manual"
  30 .SH 名前
  31 pthread_cancel \- スレッドにキャンセル要求を送る
  32 .SH 書式
  33 .nf
  34 \fB#include <pthread.h>\fP
  35
  36 \fBint pthread_cancel(pthread_t \fP\fIthread\fP\fB);\fP
  37 .sp
  38 \fI\-pthread\fP でコンパイルしてリンクする。
  39 .fi
  40 .SH 説明
  41 \fBpthread_cancel\fP() 関数は指定されたスレッド \fIthread\fP にキャンセル要求
  42 を送信する。対象のスレッドがキャンセル要求に反応するかどうか、いつ反応
  43 するかは対象のスレッドの制御下にある 2 つの属性、cancelability
  44 \fIstate\fP と \fItype\fPにより決まる。
  45
  46 あるスレッドの cancelability state は \fBpthread_setcancelstate\fP(3) で
  47 設定され、\fIenabled\fP と \fIdisabled\fP のいずれとなる (\fIenabled\fP が新しい
  48 スレッドのデフォルト値である)。スレッドがキャンセルを無効にしていた場合、
  49 キャンセル要求はそのスレッドがキャンセルを有効にするまでキューに入れら
  50 れたままになる。スレッドがキャンセルを有効にしていた場合、
  51 cancelability type によって、いつキャンセルが発生するかが決まる。
  52
  53 スレッドの cancellation type は \fBpthread_setcanceltype\fP(3) で設定され、
  54 \fIasynchronous\fP か \fIdeferred\fP のいずれかとなる(\fIdeferred\fP が新しいスレッド
  55 のデフォルト値である)。
  56 非同期キャンセル (asynchronous cancelability) は、そのスレッドはいつでも
  57 キャンセルされることを意味する (通常はすぐにキャンセルされるが、システムが
  58 そのことを保証しているわけではない)。
  59 遅延キャンセル (deferred cancelability) では、そのスレッドが \fIcancellation
  60 point\fP となっている関数を次に呼び出すまでキャンセルが遅延される。
  61 取り消しポイント (cancellation point) に設定されていたり設定したりできる
  62 関数のリストは \fIpthreads\fP(7) に記載している。
  63
  64 キャンセル要求が実行されると、
  65 \fIthread\fP では以下のステップが (この順序で) 行われる。
  66 .IP 1. 3
  67 キャンセルクリーンアップハンドラが (push されたのと逆順で)
  68 取り出され (pop され)、呼び出される。
  69 (\fBpthread_cleanup_push\fP(3) 参照)
  70 .IP 2.
  71 スレッド固有データのデストラクタ (destructor) が呼び出される。
  72 呼び出し順序は規定されていない。
  73 (\fBpthread_key_create\fP(3) 参照)
  74 .IP 3.
  75 スレッドが終了される。 (\fBpthread_exit\fP(3) 参照)
  76 .PP
  77 上記のステップは \fBpthread_cancel\fP() の呼び出しとは非同期に行われる。
  78 \fBpthread_cancel\fP() の返却ステータスは単にキャンセル要求が正常に
  79 キューに入れられたかどうかを呼び出し元に示すだけのものである。
  80 .PP
  81 キャンセルされたスレッドが終了された後に、
  82 \fBpthread_join\fP(3) でそのスレッドを join すると、
  83 そのスレッドの終了ステータスとして \fBPTHREAD_CANCELED\fP が得られる。
  84 (スレッドの join はキャンセルが完了したかを知る唯一の方法である)
  85 .SH 返り値
  86 成功すると、 \fBpthread_cancel\fP() は 0 を返す。
  87 エラーの場合、0 以外のエラー番号を返す。
  88 .SH エラー
  89 .TP
  90 \fBESRCH\fP
  91 .\" .SH VERSIONS
  92 .\" Available since glibc 2.0
  93 ID が \fIthread\fP のスレッドが見つからなかった。
  94 .SH 準拠
  95 POSIX.1\-2001.
  96 .SH 注意
  97 Linux では、キャンセルはシグナルを使って実装されている。NPTL スレッド実装では、
  98 最初のリアルタイムシグナル (つまり、シグナル 32)がこのために使用される。
  99 LinuxThreads では、リアルタイムシグナルが利用可能な場合は2 番目のリアルタイム
 100 シグナルが使用され、そうでない場合は \fBSIGUSR2\fP が使用される。
 101 .SH 例
 102 以下のプログラムは、スレッドを一つ作成してから、そのスレッドをキャンセルする。
 103 メインスレッドはキャンセルされたスレッドをジョインし、
 104 キャンセルされたスレッドの終了ステータスが \fBPTHREAD_CANCELED\fP かどうかを
 105 確認する。以下のシェルセッションはこのプログラムを実行した際の実行例である。
 106
 107 .in +4n
 108 .nf
 109 $ ./a.out
 110 thread_func(): started; cancellation disabled
 111 main(): sending cancellation request
 112 thread_func(): about to enable cancellation
 113 main(): thread was canceled
 114 .fi
 115 .in
 116 .SS プログラムのソース
 117 \&
 118 .nf
 119 #include <pthread.h>
 120 #include <stdio.h>
 121 #include <errno.h>
 122 #include <stdlib.h>
 123 #include <unistd.h>
 124
 125 #define handle_error_en(en, msg) \e
 126         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 127
 128 static void *
 129 thread_func(void *ignored_argument)
 130 {
 131     int s;
 132
 133     /* Disable cancellation for a while, so that we don\(aqt
 134        immediately react to a cancellation request */
 135
 136     s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
 137     if (s != 0)
 138         handle_error_en(s, "pthread_setcancelstate");
 139
 140     printf("thread_func(): started; cancellation disabled\en");
 141     sleep(5);
 142     printf("thread_func(): about to enable cancellation\en");
 143
 144     s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);
 145     if (s != 0)
 146         handle_error_en(s, "pthread_setcancelstate");
 147
 148     /* sleep() is a cancellation point */
 149
 150     sleep(1000);        /* Should get canceled while we sleep */
 151
 152     /* Should never get here */
 153
 154     printf("thread_func(): not canceled!\en");
 155     return NULL;
 156 }
 157
 158 int
 159 main(void)
 160 {
 161     pthread_t thr;
 162     void *res;
 163     int s;
 164
 165     /* Start a thread and then send it a cancellation request */
 166
 167     s = pthread_create(&thr, NULL, &thread_func, NULL);
 168     if (s != 0)
 169         handle_error_en(s, "pthread_create");
 170
 171     sleep(2);           /* Give thread a chance to get started */
 172
 173     printf("main(): sending cancellation request\en");
 174     s = pthread_cancel(thr);
 175     if (s != 0)
 176         handle_error_en(s, "pthread_cancel");
 177
 178     /* Join with thread to see what its exit status was */
 179
 180     s = pthread_join(thr, &res);
 181     if (s != 0)
 182         handle_error_en(s, "pthread_join");
 183
 184     if (res == PTHREAD_CANCELED)
 185         printf("main(): thread was canceled\en");
 186     else
 187         printf("main(): thread wasn\(aqt canceled (shouldn\(aqt happen!)\en");
 188     exit(EXIT_SUCCESS);
 189 }
 190 .fi
 191 .SH 関連項目
 192 \fBpthread_cleanup_push\fP(3), \fBpthread_create\fP(3), \fBpthread_exit\fP(3),
 193 \fBpthread_join\fP(3), \fBpthread_key_create\fP(3), \fBpthread_setcancelstate\fP(3),
 194 \fBpthread_setcanceltype\fP(3), \fBpthread_testcancel\fP(3), \fBpthreads\fP(7)
 195 .SH この文書について
 196 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部
 197 である。プロジェクトの説明とバグ報告に関する情報は
 198 http://www.kernel.org/doc/man\-pages/ に書かれている。