mirror of https://github.com/PCSX2/pcsx2.git
286 lines
12 KiB
Plaintext
286 lines
12 KiB
Plaintext
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.
|