.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk .\" .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one. .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 2012 Akihiro MOTOKI .\" all rights reserved. .\" Translated 2012-05-31, Akihiro MOTOKI .\" .TH PTHREAD_SETCANCELSTATE 3 2014\-05\-13 Linux "Linux Programmer's Manual" .SH 名前 pthread_setcancelstate, pthread_setcanceltype \- cancelability state と cancelability type を設定する .SH 書式 .nf \fB#include \fP \fBint pthread_setcancelstate(int \fP\fIstate\fP\fB, int *\fP\fIoldstate\fP\fB);\fP \fBint pthread_setcanceltype(int \fP\fItype\fP\fB, int *\fP\fIoldtype\fP\fB);\fP .sp \fI\-pthread\fP でコンパイルしてリンクする。 .fi .SH 説明 \fBpthread_setcancelstate\fP() は、呼び出したスレッドの cancelability state に \fIstate\fP で指定された 値を設定する。変更前のスレッドの cancelability state は \fIoldstate\fP が指すバッファーで返される。 \fIstate\fP 引き数には以下の値のいずれか一つを指定しなければならない。 .TP \fBPTHREAD_CANCEL_ENABLE\fP スレッドは取り消し可能 (cancelable) である。 これが全ての新しく作成されるスレッドでのデフォルトの cancelability state である。これには最初のスレッドも含まれる。 スレッドの cancelability type により、取り消し可能なスレッドが 取り消し要求にいつ反応するかが決まる。 .TP \fBPTHREAD_CANCEL_DISABLE\fP スレッドは取り消しできない。取り消し要求を受信した際は、 取り消し可能に設定されるまでその要求はブロックされる。 .PP \fBpthread_setcanceltype\fP() は、呼び出したスレッドの cancelability type に \fItype\fP で指定された値を設定する。 変更前のスレッドの cancelability type は \fIoldtype\fP が指すバッファーで返される。 \fItype\fP 引き数には以下の値のいずれか一つを指定しなければならない。 .TP \fBPTHREAD_CANCEL_DEFERRED\fP そのスレッドが次に取り消しポイント (cancellation point) の関数を 呼び出すまで取り消し要求が遅延される。これが全ての新しく作成される スレッドでのデフォルトの cancelability type である。 これには最初のスレッドも含まれる。 .TP \fBPTHREAD_CANCEL_ASYNCHRONOUS\fP スレッドはいつでも取り消すことができる (通常はすぐにキャンセルされるが、 システムがそのことを保証しているわけではない)。 .PP これらの関数により実行される「設定と取得」操作 (set\-and\-get operation) は、 同じ関数を呼び出したプロセス内の他のスレッドがあっても、 アトミックに行われる。 .SH 返り値 成功すると、これらの関数は 0 を返す。 エラーの場合、0 以外のエラー番号を返す。 .SH エラー \fBpthread_setcancelstate\fP() は以下のエラーで失敗する場合がある。 .TP \fBEINVAL\fP \fIstate\fP に無効な値が指定された。 .PP \fBpthread_setcanceltype\fP() は以下のエラーで失敗する場合がある。 .TP \fBEINVAL\fP .\" .SH VERSIONS .\" Available since glibc 2.0 \fItype\fP に無効な値が指定された。 .SH 属性 .SS "マルチスレッディング (pthreads(7) 参照)" 関数 \fBpthread_setcancelstate\fP() と \fBpthread_setcanceltype\fP() はスレッドセーフである。 .SH 準拠 POSIX.1\-2001. .SH 注意 スレッドが取り消された場合に何が起こるかの詳細については \fBpthread_cancel\fP(3) を参照。 取り消し要求により中断されてはならない重要なアクションをスレッドが 実行する場合、短い時間だけ cancelability を無効にするのは有用である。 長い時間 cancelability を無効にしたり、長い時間停止 (block) される 可能性のある操作の前後で cancelability を無効にしたりする際には 注意すること。なぜなら、無効にしてしまうと、キャンセル要求に対して スレッドが応答しない状態になってしまうからである。 .SS 非同期キャンセル cancelability type を \fBPTHREAD_CANCEL_ASYNCHRONOUS\fP に設定して役に立つことはめったにない。スレッドは\fIいつでも\fPキャンセルすることができることになるので、スレッドが安全にリソースの確保 (例えば \fBmalloc\fP(3) でメモリーを割り当てる) や mutex、セマフォ、ロックなどの獲得を行うことができない。アプリケーションは、スレッドがキャンセルされる際に、これらのリソースがどのような状態にあるかを知る術はないので、リソースの確保が安全ではなくなる。つまり、キャンセルが起こったのが、リソースの確保前なのか、確保中なのか、確保後なのかが分からない。さらに、関数呼び出しの最中にキャンセルが発生すると、いくつかの内部データ構造 (例えば、\fBmalloc\fP(3) 関連の関数が管理している未使用ブロックのリンクリスト) が一貫性のない状態のままになってしまう可能性がある。その結果、クリーンアップハンドラーが役に立たないものになってしまう。 非同期で安全にキャンセルできる関数は \fIasync\-cancel\-safe functions\fP と呼ばれる。 POSIX.1\-2001 で、非同期で安全にキャンセルできるように求められている関数は \fBpthread_cancel\fP(3), \fBpthread_setcancelstate\fP(), \fBpthread_setcanceltype\fP() だけである。 一般的には、それ以外のライブラリ関数は、非同期にキャンセルできるスレッドから安全に呼び出すことはできない。 非同期でのキャンセルが有効な数少ない状況としては、純粋に計算だけを行うループに入っているスレッドをキャンセルするといった場面がある。 .SS 移植性に関する注意 .\" It looks like at least Solaris, FreeBSD and Tru64 support this. Linux のスレッド実装では、 \fBpthread_setcancelstate\fP() の \fIoldstate\fP 引き数に NULL を指定することを認めている。 NULL が指定された場合、 変更前の cancelability state の情報が呼び出し側に返されない。 他の多くの実装でも \fIoldstate\fP 引き数に NULL を指定することを認めて いるが、 POSIX.1\-2001 ではこの点については規定されていない。 したがって、移植性が必要なアプリケーションでは常に \fIoldstate\fP に NULL 以外の値を指定するようにすべきである。 \fBpthread_setcanceltype\fP() の \fIoldtype\fP 引き数についても、 全く同じことが言える。 .SH 例 \fBpthread_cancel\fP(3) を参照。 .SH 関連項目 \fBpthread_cancel\fP(3), \fBpthread_cleanup_push\fP(3), \fBpthread_testcancel\fP(3), \fBpthreads\fP(7) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man\-pages/ に書かれている。