release/man3/pthread_setcancelstate.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_SETCANCELSTATE 3 2008\-11\-24 Linux "Linux Programmer's Manual"
  30 .SH 名前
  31 pthread_setcancelstate, pthread_setcanceltype \- cancelability state と
  32 type を設定する
  33 .SH 書式
  34 .nf
  35 \fB#include <pthread.h>\fP
  36
  37 \fBint pthread_setcancelstate(int \fP\fIstate\fP\fB, int *\fP\fIoldstate\fP\fB);\fP
  38 \fBint pthread_setcanceltype(int \fP\fItype\fP\fB, int *\fP\fIoldtype\fP\fB);\fP
  39 .sp
  40 \fI\-pthread\fP でコンパイルしてリンクする。
  41 .fi
  42 .SH 説明
  43 \fBpthread_setcancelstate\fP() は、呼び出したスレッドの
  44 cancelability state に \fIstate\fP で指定された値を設定する。
  45 変更前のスレッドの cancelability state は
  46 \fIoldstate\fP が指すバッファで返される。
  47 \fIstate\fP 引き数には以下の値のいずれか一つを指定しなければならない。
  48 .TP
  49 \fBPTHREAD_CANCEL_ENABLE\fP
  50 スレッドは取り消し可能 (cancelable) である。
  51 これが全ての新しく作成されるスレッドでのデフォルトの cancelability
  52 state である。これには最初のスレッドも含まれる。
  53 スレッドの cancelability type により、取り消し可能なスレッドが
  54 取り消し要求にいつ反応するかが決まる。
  55 .TP
  56 \fBPTHREAD_CANCEL_DISABLE\fP
  57 スレッドは取り消しできない。取り消し要求を受信した際は、
  58 取り消し可能に設定されるまでその要求はブロックされる。
  59 .PP
  60 \fBpthread_setcanceltype\fP() は、呼び出したスレッドの
  61 cancelability type に \fItype\fP で指定された値を設定する。
  62 変更前のスレッドの cancelability type は
  63 \fIoldtype\fP が指すバッファで返される。
  64 \fItype\fP 引き数には以下の値のいずれか一つを指定しなければならない。
  65 .TP
  66 \fBPTHREAD_CANCEL_DEFERRED\fP
  67 そのスレッドが次に取り消しポイント (cancellation point) の関数を
  68 呼び出すまで取り消し要求が遅延される。これが全ての新しく作成される
  69 スレッドでのデフォルトの cancellation type である。
  70 これには最初のスレッドも含まれる。
  71 .TP
  72 \fBPTHREAD_CANCEL_ASYNCHRONOUS\fP
  73 スレッドはいつでも取り消すことができる (通常はすぐにキャンセルされるが、
  74 システムがそのことを保証しているわけではない)。
  75 .PP
  76 これらの関数により実行される「設定と取得」操作 (set\-and\-get operation) は、
  77 同じ関数を呼び出したプロセス内の他のスレッドがあっても、
  78 アトミックに行われる。
  79 .SH 返り値
  80 成功すると、これらの関数は 0 を返す。
  81 エラーの場合、0 以外のエラー番号を返す。
  82 .SH エラー
  83 \fBpthread_setcancelstate\fP() は以下のエラーで失敗する場合がある。
  84 .TP
  85 \fBEINVAL\fP
  86 \fIstate\fP に無効な値が指定された。
  87 .PP
  88 \fBpthread_setcanceltype\fP() は以下のエラーで失敗する場合がある。
  89 .TP
  90 \fBEINVAL\fP
  91 .\" .SH VERSIONS
  92 .\" Available since glibc 2.0
  93 \fItype\fP に無効な値が指定された。
  94 .SH 準拠
  95 POSIX.1\-2001.
  96 .SH 注意
  97 スレッドが取り消された場合に何が起こるかの詳細については
  98 \fBpthread_cancel\fP(3) を参照。
  99
 100 取り消し要求により中断されてはならない重要なアクションをスレッドが
 101 実行する場合、短い時間だけ cancelability を無効にするのは有用である。
 102 長い時間 cancelability を無効にしたり、長い時間停止 (block) される
 103 可能性のある操作の前後で cancelability を無効にしたりする際には
 104 注意すること。なぜなら、無効にしてしまうと、キャンセル要求に対して
 105 スレッドが応答しない状態になってしまうからである。
 106
 107 cancelability type を \fBPTHREAD_CANCEL_ASYNCHRONOUS\fP に設定して役に立つ
 108 ことはめったにない。スレッドは\fIいつでも\fPキャンセルすることができること
 109 になるので、スレッドが安全にリソースの確保 (例えば \fBmalloc\fP(3) で
 110 メモリを割り当てる) や mutex、セマフォ、ロックなどの獲得を行うことがで
 111 きない。アプリケーションは、スレッドがキャンセルされる際に、これらのリ
 112 ソースがどのような状態にあるかを知る術はないので、リソースの確保が安全
 113 ではなくなる。つまり、キャンセルが起こったのが、リソースの確保前なのか、
 114 確保中なのか、確保後なのかが分からない。さらに、関数呼び出しの最中に
 115 キャンセルが発生すると、いくつかの内部データ構造 (例えば、\fBmalloc\fP(3)
 116 関連の関数が管理している未使用ブロックのリンクリスト) が一貫性のない
 117 状態のままになってしまう可能性がある。その結果、クリーンアップハンドラ
 118 が役に立たないものになってしまう。
 119 非同期で安全にキャンセルできる関数は \fIasync\-cancel\-safe functions\fP と
 120 呼ばれる。 POSIX.1\-2001 で、非同期で安全にキャンセルできるように求めら
 121 れている関数は \fBpthread_cancel\fP(3), \fBpthread_setcancelstate\fP(),
 122 \fBpthread_setcanceltype\fP() だけである。一般的には、それ以外のライブラリ
 123 関数は、非同期にキャンセルできるスレッドから安全に呼び出すことはできな
 124 い。非同期でのキャンセルが有効な数少ない状況としては、純粋に計算だけを
 125 行うループに入っているスレッドをキャンセルするといった場面がある。
 126
 127 .\" It looks like at least Solaris, FreeBSD and Tru64 support this.
 128 Linux のスレッド実装では、 \fBpthread_setcancelstate\fP() の \fIoldstate\fP
 129 引き数に NULL を指定することを認めている。 NULL が指定された場合、
 130 変更前の cancelability state の情報が呼び出し側に返されない。
 131 他の多くの実装でも \fIoldstate\fP 引き数に NULL を指定することを認めて
 132 いるが、 POSIX.1\-2001 ではこの点については規定されていない。
 133 したがって、移植性が必要なアプリケーションでは常に \fIoldstate\fP に
 134 NULL 以外の値を指定するようにすべきである。
 135 \fBpthread_setcanceltype\fP() の \fIoldtype\fP 引き数についても、
 136 全く同じことが言える。
 137 .SH 例
 138 \fBpthread_cancel\fP(3) を参照。
 139 .SH 関連項目
 140 \fBpthread_cancel\fP(3), \fBpthread_cleanup_push\fP(3), \fBpthread_testcancel\fP(3),
 141 \fBpthreads\fP(7)
 142 .SH この文書について
 143 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.41 の一部
 144 である。プロジェクトの説明とバグ報告に関する情報は
 145 http://www.kernel.org/doc/man\-pages/ に書かれている。