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.