pthread_cancel.3

rtlinux-3.1源代码

.\" This -*- nroff -*- file has been generated from
.\" DocBook SGML with docbook-to-man on Debian GNU/Linux.
...\"
...\"	transcript compatibility for postscript use.
...\"
...\"	synopsis:  .P! <file.ps>
...\"
.de P!
\\&.
.fl			\" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl			\" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u	\" move below the image
..
.de pF
.ie     \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie     !\\*(f4 \{\
.	ft \\*(f4
.	ds f4\"
'	br \}
.el .ie !\\*(f3 \{\
.	ft \\*(f3
.	ds f3\"
'	br \}
.el .ie !\\*(f2 \{\
.	ft \\*(f2
.	ds f2\"
'	br \}
.el .ie !\\*(f1 \{\
.	ft \\*(f1
.	ds f1\"
'	br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
'\" t 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n  
.TH "pthread_cancel" "3" 
.SH "NAME" 
pthread_cancel \(em stop and cancel a thread (not recommended) 
.SH "SYNOPSIS" 
.PP 
.nf 
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n 
#include <rtl_signal.h> 
#include <rtl_sched.h> 
 
int \fBpthread_cancel\fP(pthread_t \fBthread\fR); 
.fi 
.SH "DESCRIPTION" 
.PP 
This function is a standard POSIX threads function and is one of the weaker 
parts of the POSIX threads specification. The idea is that  
\fBpthread_cancel\fP will request termination of 
the target \fBthread\fR and this termination will either 
take place asynchronously or will be ignored depending on the cancel state of the target thread. If the target thread is in a DISABLED state, cancel will 
be pended until the thread goes to an ENABLED state. If the target thread has 
ENABLED it will either be in a DEFERRED or ASYNCHRONOUS mode. DEFERRED 
mode will defer the cancel until the thread is in a cancel point (one of a  
set of POSIX specified functions that correspond to states where the  
thread is sleeping). And so on. The semantics are complicated.  Note 
that canceling a thread on a different processor is not supported in  
RTLinux. 
.PP 
Cancel has a bizzare effect on a thread. If the thread is accepting the 
cancel, it will execute whatever cancel handlers it has pushed using 
\fBpthread_cleanup_push\fP. However \fIa canceled thread 
holding a mutex is not forced to cleanup the mutex lock\fP and, in general, 
a canceled thread may leave a terrible mess behind. Our recommendation is 
to avoid the use of this function as if it were designed by a committee of 
software consultants rubbing their hands with glee at the huge consulting 
fees they would get coming in to rescue your project after the use of  
\fBpthread_cancel\fP has totally randomized 
the operation of your code. If cancel was not a required part of  
POSIX spec, we would not inflict  it on our poor abused operating system. 
Forgive us. 
.SH "RETURN VALUE" 
.PP 
\fBpthread_cancel\fP returns 0 on success and a non-zero error code on error. 
.SH "ERRORS" 
.PP 
We have yet to see a good reason to use this function. 
.IP "ESRCH" 10 
No thread could be found corresponding to that specified by the given thread ID. 
.SH "AUTHOR" 
.PP 
Victor Yodaiken (\[e-mail] (link to URL mailto:[e-mail]) \fR) 
.SH "NOTES" 
.PP 
\fBpthread_cancel\fP is safe to call from thread,  
and from Linux kernel code. It is not safe to call from interrupt code. 
.SH "SEE ALSO" 
pthread_setcancelstate(3), pthread_testcancel(3) 
.PP 
\(co2001 FSMLabs Inc. 
.PP 
All rights reserved. 
...\" created by instant / docbook-to-man, Thu 26 Jul 2001, 11:19