1
This file documents non-portable functions and other issues.
3
Non-portable functions included in pthreads-win32
4
-------------------------------------------------
7
pthread_win32_test_features_np(int mask)
9
This routine allows an application to check which
10
run-time auto-detected features are available within
13
The possible features are:
15
PTW32_SYSTEM_INTERLOCKED_COMPARE_EXCHANGE
16
Return TRUE if the native version of
17
InterlockedCompareExchange() is being used.
18
PTW32_ALERTABLE_ASYNC_CANCEL
19
Return TRUE is the QueueUserAPCEx package
20
QUSEREX.DLL is available and the AlertDrv.sys
21
driver is loaded into Windows, providing
22
alertable (pre-emptive) asyncronous threads
23
cancelation. If this feature returns FALSE
24
then the default async cancel scheme is in
25
use, which cannot cancel blocked threads.
27
Features may be Or'ed into the mask parameter, in which case
28
the routine returns TRUE if any of the Or'ed features would
29
return TRUE. At this stage it doesn't make sense to Or features
34
pthread_timechange_handler_np(void *)
36
To improve tolerance against operator or time service
37
initiated system clock changes.
39
This routine can be called by an application when it
40
receives a WM_TIMECHANGE message from the system. At
41
present it broadcasts all condition variables so that
42
waiting threads can wake up and re-evaluate their
43
conditions and restart their timed waits if required.
45
It has the same return type and argument type as a
46
thread routine so that it may be called directly
47
through pthread_create(), i.e. as a separate thread.
51
Although a parameter must be supplied, it is ignored.
52
The value NULL can be used.
56
It can return an error EAGAIN to indicate that not
57
all condition variables were broadcast for some reason.
58
Otherwise, 0 is returned.
60
If run as a thread, the return value is returned
61
through pthread_join().
63
The return value should be cast to an integer.
67
pthread_getw32threadhandle_np(pthread_t thread);
69
Returns the win32 thread handle that the POSIX
70
thread "thread" is running as.
72
Applications can use the win32 handle to set
73
win32 specific attributes of the thread.
76
pthread_getw32threadid_np (pthread_t thread)
78
Returns the win32 thread ID that the POSIX
79
thread "thread" is running as.
81
Only valid when the library is built where
82
! defined (__MINGW32__) || defined (__MSVCRT__) || defined (__DMC__)
83
and otherwise returns 0.
87
pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind)
90
pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind)
92
These two routines are included for Linux compatibility
93
and are direct equivalents to the standard routines
94
pthread_mutexattr_settype
95
pthread_mutexattr_gettype
97
pthread_mutexattr_setkind_np accepts the following
100
PTHREAD_MUTEX_ERRORCHECK_NP
101
PTHREAD_MUTEX_RECURSIVE_NP
103
These are really just equivalent to (respectively):
105
PTHREAD_MUTEX_ERRORCHECK
106
PTHREAD_MUTEX_RECURSIVE
109
pthread_delay_np (const struct timespec *interval);
111
This routine causes a thread to delay execution for a specific period of time.
112
This period ends at the current time plus the specified interval. The routine
113
will not return before the end of the period is reached, but may return an
114
arbitrary amount of time after the period has gone by. This can be due to
115
system load, thread priorities, and system timer granularity.
117
Specifying an interval of zero (0) seconds and zero (0) nanoseconds is
118
allowed and can be used to force the thread to give up the processor or to
119
deliver a pending cancelation request.
121
This routine is a cancelation point.
123
The timespec structure contains the following two fields:
125
tv_sec is an integer number of seconds.
126
tv_nsec is an integer number of nanoseconds.
130
If an error condition occurs, this routine returns an integer value
131
indicating the type of error. Possible return values are as follows:
133
0 Successful completion.
134
[EINVAL] The value specified by interval is invalid.
137
pthread_num_processors_np (void)
139
This routine (found on HPUX systems) returns the number of processors
140
in the system. This implementation actually returns the number of
141
processors available to the process, which can be a lower number
142
than the system's number, depending on the process's affinity mask.
145
pthread_win32_process_attach_np (void);
148
pthread_win32_process_detach_np (void);
151
pthread_win32_thread_attach_np (void);
154
pthread_win32_thread_detach_np (void);
156
These functions contain the code normally run via dllMain
157
when the library is used as a dll but which need to be
158
called explicitly by an application when the library
159
is statically linked.
161
You will need to call pthread_win32_process_attach_np() before
162
you can call any pthread routines when statically linking.
163
You should call pthread_win32_process_detach_np() before
164
exiting your application to clean up.
166
pthread_win32_thread_attach_np() is currently a no-op, but
167
pthread_win32_thread_detach_np() is needed to clean up
168
the implicit pthread handle that is allocated to a Win32 thread if
169
it calls certain pthreads routines. Call this routine when the
172
These functions invariably return TRUE except for
173
pthread_win32_process_attach_np() which will return FALSE
174
if pthreads-win32 initialisation fails.
177
pthreadCancelableWait (HANDLE waitHandle);
180
pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);
182
These two functions provide hooks into the pthread_cancel
183
mechanism that will allow you to wait on a Windows handle
184
and make it a cancellation point. Both functions block
185
until either the given w32 handle is signaled, or
186
pthread_cancel has been called. It is implemented using
187
WaitForMultipleObjects on 'waitHandle' and a manually
188
reset w32 event used to implement pthread_cancel.
196
POSIX defines a single contiguous range of numbers that determine a
197
thread's priority. Win32 defines priority classes and priority
198
levels relative to these classes. Classes are simply priority base
199
levels that the defined priority levels are relative to such that,
200
changing a process's priority class will change the priority of all
201
of it's threads, while the threads retain the same relativity to each
204
A Win32 system defines a single contiguous monotonic range of values
205
that define system priority levels, just like POSIX. However, Win32
206
restricts individual threads to a subset of this range on a
209
The following table shows the base priority levels for combinations
210
of priority class and priority value in Win32.
212
Process Priority Class Thread Priority Level
213
-----------------------------------------------------------------
214
1 IDLE_PRIORITY_CLASS THREAD_PRIORITY_IDLE
215
1 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
216
1 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
217
1 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
218
1 HIGH_PRIORITY_CLASS THREAD_PRIORITY_IDLE
219
2 IDLE_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
220
3 IDLE_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
221
4 IDLE_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
222
4 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
223
5 IDLE_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
224
5 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
225
5 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
226
6 IDLE_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
227
6 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
228
6 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
229
7 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
230
7 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
231
7 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
232
8 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
233
8 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
234
8 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
235
8 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
236
9 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
237
9 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
238
9 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
239
10 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
240
10 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
241
11 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
242
11 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
243
11 HIGH_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
244
12 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
245
12 HIGH_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
246
13 HIGH_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
247
14 HIGH_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
248
15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
249
15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
250
15 IDLE_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
251
15 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
252
15 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
253
15 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
254
16 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_IDLE
255
17 REALTIME_PRIORITY_CLASS -7
256
18 REALTIME_PRIORITY_CLASS -6
257
19 REALTIME_PRIORITY_CLASS -5
258
20 REALTIME_PRIORITY_CLASS -4
259
21 REALTIME_PRIORITY_CLASS -3
260
22 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
261
23 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
262
24 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
263
25 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
264
26 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
265
27 REALTIME_PRIORITY_CLASS 3
266
28 REALTIME_PRIORITY_CLASS 4
267
29 REALTIME_PRIORITY_CLASS 5
268
30 REALTIME_PRIORITY_CLASS 6
269
31 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
271
Windows NT: Values -7, -6, -5, -4, -3, 3, 4, 5, and 6 are not supported.
274
As you can see, the real priority levels available to any individual
275
Win32 thread are non-contiguous.
277
An application using pthreads-win32 should not make assumptions about
278
the numbers used to represent thread priority levels, except that they
279
are monotonic between the values returned by sched_get_priority_min()
280
and sched_get_priority_max(). E.g. Windows 95, 98, NT, 2000, XP make
281
available a non-contiguous range of numbers between -15 and 15, while
282
at least one version of WinCE (3.0) defines the minimum priority
283
(THREAD_PRIORITY_LOWEST) as 5, and the maximum priority
284
(THREAD_PRIORITY_HIGHEST) as 1.
286
Internally, pthreads-win32 maps any priority levels between
287
THREAD_PRIORITY_IDLE and THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST,
288
or between THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to
289
THREAD_PRIORITY_HIGHEST. Currently, this also applies to
290
REALTIME_PRIORITY_CLASSi even if levels -7, -6, -5, -4, -3, 3, 4, 5, and 6
293
If it wishes, a Win32 application using pthreads-win32 can use the Win32
294
defined priority macros THREAD_PRIORITY_IDLE through
295
THREAD_PRIORITY_TIME_CRITICAL.
added
removed
win32/3rdparty/pthreads/README.NONPORTABLE
