release/man3/pthread_setcancelstate.3

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