pthread_setcancelstate
Section: C Library Functions (3)
Updated: 2025-05-17
Index
JM Home Page
roff page
名前
pthread_setcancelstate, pthread_setcanceltype - cancelability state と
cancelability type を設定する
ライブラリ
POSIX スレッドライブラリ (libpthread,~-lpthread)
書式
#include <pthread.h>
int pthread_setcancelstate(int state, int *oldstate);
int pthread_setcanceltype(int type, int *oldtype);
説明
pthread_setcancelstate() は、呼び出したスレッドの
cancelability state に state で指定された
値を設定する。変更前のスレッドの cancelability state は
oldstate が指すバッファーで返される。
state 引数には以下の値のいずれか一つを指定しなければならない。
- PTHREAD_CANCEL_ENABLE
-
The thread is cancelable. This is the default cancelability state in all
new threads, including the initial thread. The thread's cancelability type
determines when a cancelable thread will respond to a cancelation request.
- PTHREAD_CANCEL_DISABLE
-
The thread is not cancelable. If a cancelation request is received, it is
blocked until cancelability is enabled.
pthread_setcanceltype() は、呼び出したスレッドの
cancelability type に type で指定された値を設定する。
変更前のスレッドの cancelability type は
oldtype が指すバッファーで返される。
type 引数には以下の値のいずれか一つを指定しなければならない。
- PTHREAD_CANCEL_DEFERRED
-
A cancelation request is deferred until the thread next calls a function
that is a cancelation point (see pthreads(7)). This is the default
cancelability type in all new threads, including the initial thread.
-
Even with deferred cancelation, a cancelation point in an asynchronous
signal handler may still be acted upon and the effect is as if it was an
asynchronous cancelation.
- PTHREAD_CANCEL_ASYNCHRONOUS
-
The thread can be canceled at any time. (Typically, it will be canceled
immediately upon receiving a cancelation request, but the system doesn't
guarantee this.)
これらの関数により実行される「設定と取得」操作 (set-and-get operation) は、
同じ関数を呼び出したプロセス内の他のスレッドがあっても、
アトミックに行われる。
返り値
成功すると、これらの関数は 0 を返す。
エラーの場合、0 以外のエラー番号を返す。
エラー
pthread_setcancelstate() は以下のエラーで失敗する場合がある。
- EINVAL
-
state に無効な値が指定された。
pthread_setcanceltype() は以下のエラーで失敗する場合がある。
- EINVAL
-
type に無効な値が指定された。
属性
この節で使用されている用語の説明については、 attributes(7) を参照。
| インターフェース | 属性 | 値
|
|
pthread_setcancelstate(),
pthread_setcanceltype()
| Thread safety |
MT-Safe
|
|
pthread_setcancelstate(),
pthread_setcanceltype()
| Async-cancel safety |
AC-Safe
|
標準規格
POSIX.1-2008.
歴史
glibc 2.0 POSIX.1-2001.
注意
For details of what happens when a thread is canceled, see
pthread_cancel(3).
Briefly disabling cancelability is useful if a thread performs some critical
action that must not be interrupted by a cancelation request. Beware of
disabling cancelability for long periods, or around operations that may
block for long periods, since that will render the thread unresponsive to
cancelation requests.
非同期キャンセル
Setting the cancelability type to PTHREAD_CANCEL_ASYNCHRONOUS is rarely
useful. Since the thread could be canceled at any time, it cannot safely
reserve resources (e.g., allocating memory with malloc(3)), acquire
mutexes, semaphores, or locks, and so on. Reserving resources is unsafe
because the application has no way of knowing what the state of these
resources is when the thread is canceled; that is, did cancelation occur
before the resources were reserved, while they were reserved, or after they
were released? Furthermore, some internal data structures (e.g., the linked
list of free blocks managed by the malloc(3) family of functions) may be
left in an inconsistent state if cancelation occurs in the middle of the
function call. Consequently, clean-up handlers cease to be useful.
非同期で安全にキャンセルできる関数は async-cancel-safe functions と呼ばれる。 POSIX.1-2001 と
POSIX.1-2008 で、非同期で安全にキャンセルできるように求められている関数は pthread_cancel(3),
pthread_setcancelstate(), pthread_setcanceltype() だけである。
一般的には、それ以外のライブラリ関数は、非同期にキャンセルできるスレッドから安全に呼び出すことはできない。
One of the few circumstances in which asynchronous cancelability is useful
is for cancelation of a thread that is in a pure compute-bound loop.
移植性に関する注意
Linux のスレッド実装では、 pthread_setcancelstate() の oldstate 引数に NULL
を指定することを認めている。 NULL が指定された場合、変更前の cancelability state
の情報が呼び出し側に返されない。他の多くの実装でも oldstate 引数に NULL を指定することを認めているが、 POSIX.1
ではこの点については規定されていない。したがって、移植性が必要なアプリケーションでは常に oldstate に NULL
以外の値を指定するようにすべきである。 pthread_setcanceltype() の oldtype
引数についても、全く同じことが言える。
例
pthread_cancel(3) を参照。
関連項目
pthread_cancel(3), pthread_cleanup_push(3), pthread_testcancel(3),
pthreads(7)
Index
- 名前
-
- ライブラリ
-
- 書式
-
- 説明
-
- 返り値
-
- エラー
-
- 属性
-
- 標準規格
-
- 歴史
-
- 注意
-
- 非同期キャンセル
-
- 移植性に関する注意
-
- 例
-
- 関連項目
-
This document was created by
man2html,
using the manual pages.