This file documents non-portable functions and other issues. | |
Non-portable functions included in pthreads-win32 | |
------------------------------------------------- | |
BOOL | |
pthread_win32_test_features_np(int mask) | |
This routine allows an application to check which | |
run-time auto-detected features are available within | |
the library. | |
The possible features are: | |
PTW32_SYSTEM_INTERLOCKED_COMPARE_EXCHANGE | |
Return TRUE if the native version of | |
InterlockedCompareExchange() is being used. | |
PTW32_ALERTABLE_ASYNC_CANCEL | |
Return TRUE is the QueueUserAPCEx package | |
QUSEREX.DLL is available and the AlertDrv.sys | |
driver is loaded into Windows, providing | |
alertable (pre-emptive) asyncronous threads | |
cancelation. If this feature returns FALSE | |
then the default async cancel scheme is in | |
use, which cannot cancel blocked threads. | |
Features may be Or'ed into the mask parameter, in which case | |
the routine returns TRUE if any of the Or'ed features would | |
return TRUE. At this stage it doesn't make sense to Or features | |
but it may some day. | |
void * | |
pthread_timechange_handler_np(void *) | |
To improve tolerance against operator or time service | |
initiated system clock changes. | |
This routine can be called by an application when it | |
receives a WM_TIMECHANGE message from the system. At | |
present it broadcasts all condition variables so that | |
waiting threads can wake up and re-evaluate their | |
conditions and restart their timed waits if required. | |
It has the same return type and argument type as a | |
thread routine so that it may be called directly | |
through pthread_create(), i.e. as a separate thread. | |
Parameters | |
Although a parameter must be supplied, it is ignored. | |
The value NULL can be used. | |
Return values | |
It can return an error EAGAIN to indicate that not | |
all condition variables were broadcast for some reason. | |
Otherwise, 0 is returned. | |
If run as a thread, the return value is returned | |
through pthread_join(). | |
The return value should be cast to an integer. | |
HANDLE | |
pthread_getw32threadhandle_np(pthread_t thread); | |
Returns the win32 thread handle that the POSIX | |
thread "thread" is running as. | |
Applications can use the win32 handle to set | |
win32 specific attributes of the thread. | |
int | |
pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind) | |
int | |
pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind) | |
These two routines are included for Linux compatibility | |
and are direct equivalents to the standard routines | |
pthread_mutexattr_settype | |
pthread_mutexattr_gettype | |
pthread_mutexattr_setkind_np accepts the following | |
mutex kinds: | |
PTHREAD_MUTEX_FAST_NP | |
PTHREAD_MUTEX_ERRORCHECK_NP | |
PTHREAD_MUTEX_RECURSIVE_NP | |
These are really just equivalent to (respectively): | |
PTHREAD_MUTEX_NORMAL | |
PTHREAD_MUTEX_ERRORCHECK | |
PTHREAD_MUTEX_RECURSIVE | |
int | |
pthread_delay_np (const struct timespec *interval); | |
This routine causes a thread to delay execution for a specific period of time. | |
This period ends at the current time plus the specified interval. The routine | |
will not return before the end of the period is reached, but may return an | |
arbitrary amount of time after the period has gone by. This can be due to | |
system load, thread priorities, and system timer granularity. | |
Specifying an interval of zero (0) seconds and zero (0) nanoseconds is | |
allowed and can be used to force the thread to give up the processor or to | |
deliver a pending cancelation request. | |
This routine is a cancelation point. | |
The timespec structure contains the following two fields: | |
tv_sec is an integer number of seconds. | |
tv_nsec is an integer number of nanoseconds. | |
Return Values | |
If an error condition occurs, this routine returns an integer value | |
indicating the type of error. Possible return values are as follows: | |
0 Successful completion. | |
[EINVAL] The value specified by interval is invalid. | |
int | |
pthread_num_processors_np | |
This routine (found on HPUX systems) returns the number of processors | |
in the system. This implementation actually returns the number of | |
processors available to the process, which can be a lower number | |
than the system's number, depending on the process's affinity mask. | |
BOOL | |
pthread_win32_process_attach_np (void); | |
BOOL | |
pthread_win32_process_detach_np (void); | |
BOOL | |
pthread_win32_thread_attach_np (void); | |
BOOL | |
pthread_win32_thread_detach_np (void); | |
These functions contain the code normally run via dllMain | |
when the library is used as a dll but which need to be | |
called explicitly by an application when the library | |
is statically linked. | |
You will need to call pthread_win32_process_attach_np() before | |
you can call any pthread routines when statically linking. | |
You should call pthread_win32_process_detach_np() before | |
exiting your application to clean up. | |
pthread_win32_thread_attach_np() is currently a no-op, but | |
pthread_win32_thread_detach_np() is needed to clean up | |
the implicit pthread handle that is allocated to a Win32 thread if | |
it calls certain pthreads routines. Call this routine when the | |
Win32 thread exits. | |
These functions invariably return TRUE except for | |
pthread_win32_process_attach_np() which will return FALSE | |
if pthreads-win32 initialisation fails. | |
int | |
pthreadCancelableWait (HANDLE waitHandle); | |
int | |
pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout); | |
These two functions provide hooks into the pthread_cancel | |
mechanism that will allow you to wait on a Windows handle | |
and make it a cancellation point. Both functions block | |
until either the given w32 handle is signaled, or | |
pthread_cancel has been called. It is implemented using | |
WaitForMultipleObjects on 'waitHandle' and a manually | |
reset w32 event used to implement pthread_cancel. | |
Non-portable issues | |
------------------- | |
Thread priority | |
POSIX defines a single contiguous range of numbers that determine a | |
thread's priority. Win32 defines priority classes and priority | |
levels relative to these classes. Classes are simply priority base | |
levels that the defined priority levels are relative to such that, | |
changing a process's priority class will change the priority of all | |
of it's threads, while the threads retain the same relativity to each | |
other. | |
A Win32 system defines a single contiguous monotonic range of values | |
that define system priority levels, just like POSIX. However, Win32 | |
restricts individual threads to a subset of this range on a | |
per-process basis. | |
The following table shows the base priority levels for combinations | |
of priority class and priority value in Win32. | |
Process Priority Class Thread Priority Level | |
----------------------------------------------------------------- | |
1 IDLE_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
1 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
1 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
1 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
1 HIGH_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
2 IDLE_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
3 IDLE_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
4 IDLE_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
4 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
5 IDLE_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
5 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
5 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
6 IDLE_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
6 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
6 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
7 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
7 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
7 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
8 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
8 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
8 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
8 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
9 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
9 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
9 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
10 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
10 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
11 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
11 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
11 HIGH_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
12 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
12 HIGH_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
13 HIGH_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
14 HIGH_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
15 IDLE_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
15 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
15 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
15 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
16 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_IDLE | |
17 REALTIME_PRIORITY_CLASS -7 | |
18 REALTIME_PRIORITY_CLASS -6 | |
19 REALTIME_PRIORITY_CLASS -5 | |
20 REALTIME_PRIORITY_CLASS -4 | |
21 REALTIME_PRIORITY_CLASS -3 | |
22 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_LOWEST | |
23 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL | |
24 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_NORMAL | |
25 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL | |
26 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST | |
27 REALTIME_PRIORITY_CLASS 3 | |
28 REALTIME_PRIORITY_CLASS 4 | |
29 REALTIME_PRIORITY_CLASS 5 | |
30 REALTIME_PRIORITY_CLASS 6 | |
31 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL | |
Windows NT: Values -7, -6, -5, -4, -3, 3, 4, 5, and 6 are not supported. | |
As you can see, the real priority levels available to any individual | |
Win32 thread are non-contiguous. | |
An application using pthreads-win32 should not make assumptions about | |
the numbers used to represent thread priority levels, except that they | |
are monotonic between the values returned by sched_get_priority_min() | |
and sched_get_priority_max(). E.g. Windows 95, 98, NT, 2000, XP make | |
available a non-contiguous range of numbers between -15 and 15, while | |
at least one version of WinCE (3.0) defines the minimum priority | |
(THREAD_PRIORITY_LOWEST) as 5, and the maximum priority | |
(THREAD_PRIORITY_HIGHEST) as 1. | |
Internally, pthreads-win32 maps any priority levels between | |
THREAD_PRIORITY_IDLE and THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST, | |
or between THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to | |
THREAD_PRIORITY_HIGHEST. Currently, this also applies to | |
REALTIME_PRIORITY_CLASSi even if levels -7, -6, -5, -4, -3, 3, 4, 5, and 6 | |
are supported. | |
If it wishes, a Win32 application using pthreads-win32 can use the Win32 | |
defined priority macros THREAD_PRIORITY_IDLE through | |
THREAD_PRIORITY_TIME_CRITICAL. |