1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<HTML
><HEAD
><TITLE
>pthread_cancel</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"></HEAD
><BODY
CLASS="REFENTRY"
><H1
><A
NAME="AEN1"
>pthread_cancel</A
></H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5"
></A
><H2
>Name</H2
>pthread_cancel -- stop and cancel a thread (not recommended)</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN8"
></A
><H2
>Synopsis</H2
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="SYNOPSIS"
> #include <rtl_signal.h>
#include <rtl_sched.h>
int <TT
CLASS="FUNCTION"
>pthread_cancel</TT
>(pthread_t <TT
CLASS="PARAMETER"
><I
>thread</I
></TT
>);</PRE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN12"
></A
><H2
>DESCRIPTION</H2
><P
>This function is a standard POSIX threads function and is one of the weaker
parts of the POSIX threads specification. The idea is that
<TT
CLASS="FUNCTION"
>pthread_cancel</TT
> will request termination of
the target <TT
CLASS="PARAMETER"
><I
>thread</I
></TT
> 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.</P
><P
>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
<TT
CLASS="FUNCTION"
>pthread_cleanup_push</TT
>. However <I
CLASS="EMPHASIS"
>a canceled thread
holding a mutex is not forced to cleanup the mutex lock</I
> 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
<TT
CLASS="FUNCTION"
>pthread_cancel</TT
> 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.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN21"
></A
><H2
>RETURN VALUE</H2
><P
><TT
CLASS="FUNCTION"
>pthread_cancel</TT
> returns 0 on success and a non-zero error code on error.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN25"
></A
><H2
>ERRORS</H2
><P
>We have yet to see a good reason to use this function.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>ESRCH</DT
><DD
><P
>No thread could be found corresponding to that specified by the given thread ID.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN33"
></A
><H2
>AUTHOR</H2
><P
>Victor Yodaiken (<A
HREF="mailto:support@fsmlabs.com"
TARGET="_top"
>support@fsmlabs.com</A
>)</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN37"
></A
><H2
>NOTES</H2
><P
><TT
CLASS="FUNCTION"
>pthread_cancel</TT
> is safe to call from thread,
and from Linux kernel code. It is not safe to call from interrupt code.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN41"
></A
><H2
>SEE ALSO</H2
>pthread_setcancelstate(3), pthread_testcancel(3)<P
>2001 FSMLabs Inc.</P
><P
>All rights reserved.</P
></DIV
></BODY
></HTML
>
|
