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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
<TITLE>PTHREAD_ATTR_INIT(3) manual page</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.3 (Linux)">
<META NAME="CREATED" CONTENT="20050504;10092900">
<META NAME="CHANGED" CONTENT="20050505;16540200">
<!-- manual page source format generated by PolyglotMan v3.2, -->
<!-- available at http://polyglotman.sourceforge.net/ -->
</HEAD>
<BODY LANG="en-GB" BGCOLOR="#ffffff" DIR="LTR">
<H4>POSIX Threads for Windows – REFERENCE - <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A></H4>
<P><A HREF="index.html">Reference Index</A></P>
<P><A HREF="#toc">Table of Contents</A></P>
<H2><A HREF="#toc0" NAME="sect0">Name</A></H2>
<P>pthread_attr_init, pthread_attr_destroy,
pthread_attr_setdetachstate, pthread_attr_getdetachstate,
pthread_attr_setschedparam, pthread_attr_getschedparam,
pthread_attr_setschedpolicy, pthread_attr_getschedpolicy,
pthread_attr_setinheritsched, pthread_attr_getinheritsched,
pthread_attr_setscope, pthread_attr_getscope - thread creation
attributes
</P>
<H2><A HREF="#toc1" NAME="sect1">Synopsis</A></H2>
<P><B>#include <pthread.h></B>
</P>
<P><B>int pthread_attr_init(pthread_attr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_attr_destroy(pthread_attr_t *</B><I>attr</I><B>);</B>
</P>
<P><B>int pthread_attr_setdetachstate(pthread_attr_t *</B><I>attr</I><B>,
int </B><I>detachstate</I><B>);</B>
</P>
<P><B>int pthread_attr_getdetachstate(const pthread_attr_t *</B><I>attr</I><B>,
int *</B><I>detachstate</I><B>);</B>
</P>
<P><B>int pthread_attr_setschedpolicy(pthread_attr_t *</B><I>attr</I><B>,
int </B><I>policy</I><B>);</B>
</P>
<P><B>int pthread_attr_getschedpolicy(const pthread_attr_t *</B><I>attr</I><B>,
int *</B><I>policy</I><B>);</B>
</P>
<P><B>int pthread_attr_setschedparam(pthread_attr_t *</B><I>attr</I><B>,
const struct sched_param *</B><I>param</I><B>);</B>
</P>
<P><B>int pthread_attr_getschedparam(const pthread_attr_t *</B><I>attr</I><B>,
struct sched_param *</B><I>param</I><B>);</B>
</P>
<P><B>int pthread_attr_setinheritsched(pthread_attr_t *</B><I>attr</I><B>,
int </B><I>inherit</I><B>);</B>
</P>
<P><B>int pthread_attr_getinheritsched(const pthread_attr_t *</B><I>attr</I><B>,
int *</B><I>inherit</I><B>);</B>
</P>
<P><B>int pthread_attr_setscope(pthread_attr_t *</B><I>attr</I><B>,
int </B><I>scope</I><B>);</B>
</P>
<P><B>int pthread_attr_getscope(const pthread_attr_t *</B><I>attr</I><B>,
int *</B><I>scope</I><B>);</B>
</P>
<H2><A HREF="#toc2" NAME="sect2">Description</A></H2>
<P>Setting attributes for threads is achieved by filling a thread
attribute object <I>attr</I> of type <B>pthread_attr_t</B>, then
passing it as second argument to <A HREF="pthread_create.html"><B>pthread_create</B>(3)</A>
. Passing <B>NULL</B> is equivalent to passing a thread attribute
object with all attributes set to their default values.
</P>
<P><B>pthread_attr_init</B> initializes the thread attribute object
<I>attr</I> and fills it with default values for the attributes. (The
default values are listed below for each attribute.)
</P>
<P>Each attribute <I>attrname</I> (see below for a list of all
attributes) can be individually set using the function
<B>pthread_attr_set</B><I>attrname</I> and retrieved using the
function <B>pthread_attr_get</B><I>attrname.</I>
</P>
<P><B>pthread_attr_destroy</B> destroys a thread attribute object,
which must not then be reused until it is reinitialized.
</P>
<P>Attribute objects are consulted only when creating a new thread.
The same attribute object can be used for creating several threads.
Modifying an attribute object after a call to <B>pthread_create</B>
does not change the attributes of the thread previously created.
</P>
<P>The following thread attributes are supported:
</P>
<H3><A HREF="#toc3" NAME="sect3">detachstate</A></H3>
<P>Control whether the thread is created in the joinable state (value
<B>PTHREAD_CREATE_JOINABLE</B>) or in the detached state (
<B>PTHREAD_CREATE_DETACHED</B>).
</P>
<P>Default value: <B>PTHREAD_CREATE_JOINABLE</B>.
</P>
<P>In the joinable state, another thread can synchronize on the
thread termination and recover its termination code using
<A HREF="pthread_join.html"><B>pthread_join</B>(3)</A> . When a
joinable thread terminates, some of the thread resources are kept
allocated, and released only when another thread performs
<A HREF="pthread_join.html"><B>pthread_join</B>(3)</A> on that
thread.
</P>
<P>In the detached state, the thread's resources are released
immediately when it terminates. <A HREF="pthread_join.html"><B>pthread_join</B>(3)</A>
cannot be used to synchronize on the thread termination.
</P>
<P>A thread created in the joinable state can later be put in the
detached thread using <A HREF="pthread_detach.html"><B>pthread_detach</B>(3)</A>
.
</P>
<H3><A HREF="#toc4" NAME="sect4">schedpolicy</A></H3>
<P>Select the scheduling policy for the thread: one of <B>SCHED_OTHER</B>
(regular, non-real-time scheduling), <B>SCHED_RR</B> (real-time,
round-robin) or <B>SCHED_FIFO</B> (real-time, first-in first-out).
</P>
<P><B>Pthreads-w32</B> only supports <B>SCHED_OTHER</B> - attempting
to set one of the other policies will return an error ENOTSUP.</P>
<P>Default value: <B>SCHED_OTHER</B>.
</P>
<P><B>Pthreads-w32</B> only supports <B>SCHED_OTHER</B> - attempting
to set one of the other policies will return an error ENOTSUP.</P>
<P>The scheduling policy of a thread can be changed after creation
with <A HREF="pthread_setschedparam.html"><B>pthread_setschedparam</B>(3)</A>
.
</P>
<H3><A HREF="#toc5" NAME="sect5">schedparam</A></H3>
<P>Contain the scheduling parameters (essentially, the scheduling
priority) for the thread.</P>
<P><B>Pthreads-w32</B> supports the priority levels defined by the
Windows system it is running on. Under Windows, thread priorities are
relative to the process priority class, which must be set via the
Windows W32 API.</P>
<P>Default value: priority is 0 (Win32 level <B>THREAD_PRIORITY_NORMAL</B>).
</P>
<P>The scheduling priority of a thread can be changed after creation
with <A HREF="pthread_setschedparam.html"><B>pthread_setschedparam</B>(3)</A>
.
</P>
<H3><A HREF="#toc6" NAME="sect6">inheritsched</A></H3>
<P>Indicate whether the scheduling policy and scheduling parameters
for the newly created thread are determined by the values of the
<I>schedpolicy</I> and <I>schedparam</I> attributes (value
<B>PTHREAD_EXPLICIT_SCHED</B>) or are inherited from the parent
thread (value <B>PTHREAD_INHERIT_SCHED</B>).
</P>
<P>Default value: <B>PTHREAD_EXPLICIT_SCHED</B>.
</P>
<H3><A HREF="#toc7" NAME="sect7">scope</A></H3>
<P>Define the scheduling contention scope for the created thread. The
only value supported in the <B>Pthreads-w32</B> implementation is
<B>PTHREAD_SCOPE_SYSTEM</B>, meaning that the threads contend for CPU
time with all processes running on the machine. The other value
specified by the standard, <B>PTHREAD_SCOPE_PROCESS</B>, means that
scheduling contention occurs only between the threads of the running
process.</P>
<P><B>Pthreads-w32</B> only supports <B>PTHREAD_SCOPE_SYSTEM</B>.</P>
<P>Default value: <B>PTHREAD_SCOPE_SYSTEM</B>.
</P>
<H2><A HREF="#toc8" NAME="sect8">Return Value</A></H2>
<P>All functions return 0 on success and a non-zero error code on
error. On success, the <B>pthread_attr_get</B><I>attrname</I>
functions also store the current value of the attribute <I>attrname</I>
in the location pointed to by their second argument.
</P>
<H2><A HREF="#toc9" NAME="sect9">Errors</A></H2>
<P>The <B>pthread_attr_setdetachstate</B> function returns the
following error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the specified <I>detachstate</I> is not one of
<B>PTHREAD_CREATE_JOINABLE</B> or <B>PTHREAD_CREATE_DETACHED</B>.
</DD></DL>
</DL>
<P>
The <B>pthread_attr_setschedparam</B> function returns the following
error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the priority specified in <I>param</I> is outside the range of
allowed priorities for the scheduling policy currently in <I>attr</I>
(1 to 99 for <B>SCHED_FIFO</B> and <B>SCHED_RR</B>; 0 for
<B>SCHED_OTHER</B>).
</DD></DL>
</DL>
<P>
The <B>pthread_attr_setschedpolicy</B> function returns the following
error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the specified <I>policy</I> is not one of <B>SCHED_OTHER</B>,
<B>SCHED_FIFO</B>, or <B>SCHED_RR</B>.
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ENOTSUP</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<I>policy</I> is not <B>SCHED_OTHER</B>, the only value supported
by <B>Pthreads-w32</B>.</DD></DL>
</DL>
<P>
The <B>pthread_attr_setinheritsched</B> function returns the
following error codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the specified <I>inherit</I> is not one of <B>PTHREAD_INHERIT_SCHED</B>
or <B>PTHREAD_EXPLICIT_SCHED</B>.
</DD></DL>
</DL>
<P>
The <B>pthread_attr_setscope</B> function returns the following error
codes on error:
</P>
<DL>
<DL>
<DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm"><B>EINVAL</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the specified <I>scope</I> is not one of <B>PTHREAD_SCOPE_SYSTEM</B>
or <B>PTHREAD_SCOPE_PROCESS</B>.
</DD><DT STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
<B>ENOTSUP</B>
</DT><DD STYLE="margin-right: 1cm; margin-bottom: 0.5cm">
the specified <I>scope</I> is <B>PTHREAD_SCOPE_PROCESS</B> (not
supported by <B>Pthreads-w32</B>).
</DD></DL>
</DL>
<H2>
<A HREF="#toc10" NAME="sect10">Author</A></H2>
<P>Xavier Leroy <Xavier.Leroy@inria.fr>
</P>
<P>Modified by Ross Johnson for use with <A HREF="http://sources.redhat.com/pthreads-win32">Pthreads-w32</A>.</P>
<H2><A HREF="#toc11" NAME="sect11">See Also</A></H2>
<P><A HREF="pthread_create.html"><B>pthread_create</B>(3)</A> ,
<A HREF="pthread_join.html"><B>pthread_join</B>(3)</A> ,
<A HREF="pthread_detach.html"><B>pthread_detach</B>(3)</A> ,
<A HREF="pthread_setschedparam.html"><B>pthread_setschedparam</B>(3)</A>
.
</P>
<HR>
<P><A NAME="toc"></A><B>Table of Contents</B></P>
<UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect0" NAME="toc0">Name</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect1" NAME="toc1">Synopsis</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect2" NAME="toc2">Description</A>
</P>
<UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect3" NAME="toc3">detachstate</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect4" NAME="toc4">schedpolicy</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect5" NAME="toc5">schedparam</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect6" NAME="toc6">inheritsched</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect7" NAME="toc7">scope</A>
</P>
</UL>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect8" NAME="toc8">Return
Value</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect9" NAME="toc9">Errors</A>
</P>
<LI><P STYLE="margin-bottom: 0cm"><A HREF="#sect10" NAME="toc10">Author</A>
</P>
<LI><P><A HREF="#sect11" NAME="toc11">See Also</A>
</P>
</UL>
</BODY>
</HTML>
|
