.\"   Copyright (C) 1994-1999 Free Software Foundation, Inc.
.\"
.\"   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.
.\"
.\"   Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for modified
.\" versions, except that this permission notice may be stated in a
.\" translation approved by the Foundation.
.\"
.\" Copyright (C) 1999 Xavier Leroy.
.\" 
.\" Japanese Version Copyright (C) 2000 WAKABAYASHI, Takeyasu
.\"         all rights reserved.
.\" Translated on Fri Jan 14 16:50:24 JST 2000
.\"         by WAKABAYASHI, Takeyasu <twakaba@eco.toyama-u.ac.jp>
.\"
.\" 
.\" .TH PTHREAD_CANCEL 3 LinuxThreads
.\"
.\"
.\" .SH NAME
.\" pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel \- thread cancellation
.\"
.\" .SH SYNOPSIS
.\" .B #include <pthread.h>
.\"
.\" .BI "int pthread_cancel(pthread_t " thread ");"
.\"
.\" .BI "int pthread_setcancelstate(int " state ", int *" oldstate ");"
.\"
.\" .BI "int pthread_setcanceltype(int " type ", int *" oldtype ");"
.\"
.\" .BI "void pthread_testcancel(void);"
.TH PTHREAD_CANCEL 3 LinuxThreads


.SH NAME
pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel \- スレッドの取り消し

.SH 書式
.B #include <pthread.h>

.BI "int pthread_cancel(pthread_t " thread ");"

.BI "int pthread_setcancelstate(int " state ", int *" oldstate ");"

.BI "int pthread_setcanceltype(int " type ", int *" oldtype ");"

.BI "void pthread_testcancel(void);"

.\" .SH DESCRIPTION
.\"
.\" Cancellation is the mechanism by which a thread can terminate the
.\" execution of another thread. More precisely, a thread can send a
.\" cancellation request to another thread. Depending on its settings, the
.\" target thread can then either ignore the request, honor it
.\" immediately, or defer it till it reaches a cancellation point.
.SH 説明

取り消しは、あるスレッドが他のスレッドの実行を終了させることを可能
にするメカニズムである。より正確には、スレッドは他のスレッドに対して
取消要求を送ることができる。設定次第で、目標のスレッドは、要求を無視
したり、直ちに実現したり、ある取り消しポイントに至るまでその要求の実行
を延期したりできる。

.\" When a thread eventually honors a cancellation request, it performs as
.\" if 
.\" .B "pthread_exit(PTHREAD_CANCELED)"
.\" has been called at that point:
.\" all cleanup handlers are executed in reverse order, finalization
.\" functions for thread-specific data are called, and finally the thread
.\" stops executing with the return value 
.\" .BR "PTHREAD_CANCELED" .
.\" See
.\" .BR "pthread_exit" (3)
.\" for more information.
スレッドが最終的に取り消し要求を実現する際には、それはあたかも
.B "pthread_exit(PTHREAD_CANCELED)"
がその時点で呼び出されたかのように振舞う。すなわち、全てのクリーン
アップハンドラが逆順に実行され、スレッド固有データの終了処理関数が
呼び出され、最後にスレッドは、返り値
.BR "PTHREAD_CANCEL"
で実行を停止する。詳しくは
.BR "pthread_exit" (3)
を見よ。

.\" .B "pthread_cancel"
.\" sends a cancellation request to the thread denoted
.\" by the 
.\" .I "thread"
.\" argument.
.BR "pthread_cancel"
は
.I "thread"
引数で指定されたスレッドに対して、取り消し要求を送る。

.\" .B "pthread_setcancelstate"
.\" changes the cancellation state for the
.\" calling thread -- that is, whether cancellation requests are ignored
.\" or not. The 
.\" .I "state"
.\" argument is the new cancellation state: either
.\" .B "PTHREAD_CANCEL_ENABLE"
.\" to enable cancellation, or
.\" .B "PTHREAD_CANCEL_DISABLE"
.\" to disable cancellation (cancellation
.\" requests are ignored). If 
.\" .I "oldstate"
.\" is not 
.\" .BR "NULL" ,
.\" the previous
.\" cancellation state is stored in the location pointed to by 
.\" .IR "oldstate" ,
.\" and can thus be restored later by another call to
.\" .BR "pthread_setcancelstate" .
.B "pthread_setcancelstate"
は、これを呼び出すスレッドの取り消し状態を変更する。
すなわち、取り消し要求を受け入れるか否かを変更する。
.I "state"
引数は新たな取り消し状態である。これは取り消しを可能にする
.B "PTHREAD_CANCEL_ENABLE"
もしくは、取り消しを不可能にする(取り消し要求を無視する)
.B "PTHREAD_CANCEL_DISABLE"
のいずれかである。
.I "oldstate"
が
.BR "NULL"
でなければ、以前の取り消し状態が
.IR "oldstate"
が指す場所に格納され、従って、後で別の
.BR "pthread_setcancelstate"
の呼び出しにより、回復することができる。

.\" .B "pthread_setcanceltype"
.\" changes the type of responses to cancellation
.\" requests for the calling thread: asynchronous (immediate) or deferred.
.\" The 
.\" .I "type"
.\" argument is the new cancellation type: either
.\" .B "PTHREAD_CANCEL_ASYNCHRONOUS"
.\" to cancel the calling thread as soon as
.\" the cancellation request is received, or 
.\" .B "PTHREAD_CANCEL_DEFERRED"
.\" to
.\" keep the cancellation request pending until the next cancellation
.\" point. If 
.\" .I "oldtype"
.\" is not 
.\" .BR "NULL" ,
.\" the previous
.\" cancellation state is stored in the location pointed to by 
.\" .IR "oldtype" ,
.\" and can thus be restored later by another call to
.\" .BR "pthread_setcanceltype" .
.B "pthread_setcanceltype"
は、これを呼び出すスレッドの取り消し要求に対する反応の型を変更する。
これは、非同期(即時)または遅延のいずれかである。
.I "type"
引数は、新たな取り消し方であり、取り消し要求が届くと直ちに呼び出し
スレッドを取り消す
.B "PTHREAD_CANCEL_ASYNCHRONOUS"
か、取り消し要求を次の取り消しポイントまで留保する
.B "PTHREAD_CANCEL_DEFERRED"
かのいずれかである。
.I "oldtype"
が
.BR "NULL"
でなければ、以前の取り消し型が
.IR "oldtype"
の指す場所に格納され、従って、後から別の
.BR "pthread_setcanceltype"
の呼び出しによって回復することが可能である。

.\" Threads are always created by 
.\" .BR "pthread_create" (3)
.\" with cancellation
.\" enabled and deferred. That is, the initial cancellation state is
.\" .B "PTHREAD_CANCEL_ENABLE"
.\" and the initial type is
.\" .BR "PTHREAD_CANCEL_DEFERRED" .
スレッドは常に
.BR "pthread_create" (3)
によって、取り消し可能かつ遅延で作成される。
すなわち、初期の取り消し状態は
.B "PTHREAD_CANCEL_ENABLE"
であり、初期の型は
.BR "PTHREAD_CANCEL_DEFERRED"
である。

.\" Cancellation points are those points in the program execution where a
.\" test for pending cancellation requests is performed and cancellation
.\" is executed if positive. The following POSIX threads functions
.\" are cancellation points:
取り消しポイントとは、保留中の取り消し要求に対するテストが行われ、
実際に要求があれば取り消しが実行される点である。以下の POSIX スレッド
関数は取り消しポイントである:

.\" .BR "pthread_join" (3)
.\" .br
.\" .BR "pthread_cond_wait" (3)
.\" .br
.\" .BR "pthread_cond_timedwait" (3)
.\" .br
.\" .BR "pthread_testcancel" (3)
.\" .br
.\" .BR "sem_wait" (3)
.\" .br
.\" .BR "sigwait" (3)
.BR "pthread_join" (3)
.br
.BR "pthread_cond_wait" (3)
.br
.BR "pthread_cond_timedwait" (3)
.br
.BR "pthread_testcancel" (3)
.br
.BR "sem_wait" (3)
.br
.BR "sigwait" (3)

.\" All other POSIX threads functions are guaranteed not to be
.\" cancellation points. That is, they never perform cancellation in
.\" deferred cancellation mode.
これ以外の全ての POSIX スレッド関数は取り消しポイントではないことが保証
されている。すなわち、それらは遅延取り消しモードで決して取り消しを
実現することはない。

.\" .B "pthread_testcancel"
.\" does nothing except testing for pending
.\" cancellation and executing it. Its purpose is to introduce explicit
.\" checks for cancellation in long sequences of code that do not call
.\" cancellation point functions otherwise.
.B "pthread_testcancel"
は保留中の取り消し要求を調べ、それを実現するだけである。その目的は、
他に取り消しポイントとなる関数を呼び出すことのない、長い連続した
コードの中に、明示的に取り消しのチェックを導入することである。

.\" .SH "RETURN VALUE"
.\"
.\" .BR "pthread_cancel" ,
.\" .B "pthread_setcancelstate"
.\" and
.\" .B "pthread_setcanceltype"
.\" return 0 on success and a non-zero error code
.\" on error.
.SH 返り値

.BR "pthread_cancel"、
.B "pthread_setcancelstate"
および
.B "pthread_setcanceltype"
は成功すると 0 を返し、エラーならば、非ゼロのエラーコードを返す。

.\" .SH ERRORS
.\"
.\" .B "pthread_cancel"
.\" returns the following error code on error:
.\" .RS
.\" .TP
.\" .B "ESRCH"
.\" no thread could be found corresponding to that specified by the 
.\" .I "thread"
.\" ID.
.\" .RE
.SH エラー
.B "pthread_cancel"
はエラーの際に次のエラーコードを返す:
.RS
.TP
.B "ESRCH"
.I "thread"
で指定されたものに対応するスレッドが存在しない。
ID.
.RE

.\" .B "pthread_setcancelstate"
.\" returns the following error code on error:
.\" .RS
.\" .TP
.\" .B "EINVAL"
.\" the 
.\" .I "state"
.\" argument is not 
.\" .B "PTHREAD_CANCEL_ENABLE"
.\" nor
.\" .B "PTHREAD_CANCEL_DISABLE"
.\" .RE
.B "pthread_setcancelstate"
はエラーの際に次のエラーコードを返す:
.RS
.TP
.B "EINVAL"
.I "state"
が
.B "PTHREAD_CANCEL_ENABLE"
でも
.B "PTHREAD_CANCEL_DISABLE"
でもない。
.RE

.\" .B "pthread_setcanceltype"
.\" returns the following error code on error:
.\" .RS
.\" .TP
.\" .B "EINVAL"
.\" the 
.\" .I "type"
.\" argument is not 
.\" .B "PTHREAD_CANCEL_DEFERRED"
.\" nor
.\" .B "PTHREAD_CANCEL_ASYNCHRONOUS"
.\" .RE
.B "pthread_setcanceltype"
はエラーの際に次のエラーコードを返す:
.RS
.TP
.B "EINVAL"
.I "type"
引数が
.B "PTHREAD_CANCEL_DEFERRED"
でも
.B "PTHREAD_CANCEL_ASYNCHRONOUS"
でもない。
.RE

.\" .SH AUTHOR
.\" Xavier Leroy <Xavier.Leroy@inria.fr>
.\"
.\" .SH "SEE ALSO"
.\" .BR "pthread_exit" (3),
.\" .BR "pthread_cleanup_push" (3),
.\" .BR "pthread_cleanup_pop" (3).
.SH 著者
Xavier Leroy <Xavier.Leroy@inria.fr>

.SH 関連項目
.BR "pthread_exit" (3),
.BR "pthread_cleanup_push" (3),
.BR "pthread_cleanup_pop" (3).

.\".SH BUGS
.SH バグ

.\" POSIX specifies that a number of system calls (basically, all
.\" system calls that may block, such as 
.\" .BR "read" (2),
.\" .BR "write" (2),
.\" .BR "wait" (2),
.\" etc.) and library functions that may call these system calls (e.g.
.\" .BR "fprintf" (3))
.\" are cancellation points.  LinuxThreads is not yet
.\" integrated enough with the C library to implement this, and thus none
.\" of the C library functions is a cancellation point.
POSIX は一連のシステムコール(基本的には
.BR "read" (2),
.BR "write" (2),
.BR "wait" (2),
等のようなブロックの可能性のある全ての関数)とそれらのシステムコール
を呼ぶようなライブラリ関数(例えば
.BR "fprintf" (3))
が取り消しポイントであると規定している。 LinuxThreads はこれを実装する
には、まだ十分に C ライブラリと統合されていると言えず、
従っていかなる C ライブラリの関数も取り消しポイントではない。

.\" For system calls at least, there is a workaround. Cancellation
.\" requests are transmitted to the target thread by sending it a
.\" signal. That signal will interrupt all blocking system calls, causing
.\" them to return immediately with the 
.\" .B "EINTR"
.\" error. So, checking for
.\" cancellation during a 
.\" .B "read"
.\" system call, for instance, can be
.\" achieved as follows:
少なくとも、システムコールに対してはこれを回避する方法がある。
取り消し要求は、目標スレッドにシグナルを送ることによって送信される。
このシグナルはブロックしているシステムコール全てに対して割込みを掛け、
それらは直ちに
.B "EINTR"
で戻る。よって、例えば
.B "read"
システムコールを呼んでいる間に取り消しをチェックするには、次のように
すれば良い:

.RS
.ft 3
.nf
.sp
pthread_testcancel();
retcode = read(fd, buffer, length);
pthread_testcancel();
.ft
.LP
.RE
.fi


[訳注] 上の記述は glibc2 を用いたシステムでは正しくない。以下は 
glib-2.1.2 の info ファイルからの引用である。

.\"    Cancellation points are the points where the thread checks for
.\" pending cancellation requests and performs them.  The POSIX threads
.\" functions `pthread_join', `pthread_cond_wait',
.\" `pthread_cond_timedwait', `pthread_testcancel', `sem_wait', and
.\" `sigwait' are cancellation points.  In addition, these system calls are
.\" cancellation points:
.\"
.\" accept                   open                     sendmsg                  
.\" close                    pause                    sendto                   
.\" connect                  read                     system                   
.\" fcntl                    recv                     tcdrain                  
.\" fsync                    recvfrom                 wait                     
.\" lseek                    recvmsg                  waitpid                  
.\" msync                    send                     write                    
.\" nanosleep                                                                  
.\"
.\" All library functions that call these functions (such as `printf') are
.\"also cancellation points.
取り消しポイントとは、保留中の取り消し要求に対するテストが行われ、
実際に要求があれば取り消しが実行される点である。POSIX スレッド関数
のうち、`pthread_join', `pthread_cond_wait', `pthread_cond_timed_wait', 
`pthread_testcancel', `sem_wait' 及び `sigwait' は取り消しポイント
である。 これに加えて、以下のシステムコールは取り消しポイントである:

 accept                   open                     sendmsg                  
 close                    pause                    sendto                   
 connect                  read                     system                   
 fcntl                    recv                     tcdrain                  
 fsync                    recvfrom                 wait                     
 lseek                    recvmsg                  waitpid                  
 msync                    send                     write                    
 nanosleep                                                                  

これらの関数を呼び出す可能性のある printf() などのライブラリ関数も
取り消しポイントになる場合がある。