/[pcsx2_0.9.7]/trunk/3rdparty/w32pthreads/README.NONPORTABLE
ViewVC logotype

Contents of /trunk/3rdparty/w32pthreads/README.NONPORTABLE

Parent Directory Parent Directory | Revision Log Revision Log


Revision 31 - (show annotations) (download)
Tue Sep 7 03:24:11 2010 UTC (9 years, 11 months ago) by william
File size: 11729 byte(s)
committing r3113 initial commit again...
1 This file documents non-portable functions and other issues.
2
3 Non-portable functions included in pthreads-win32
4 -------------------------------------------------
5
6 BOOL
7 pthread_win32_test_features_np(int mask)
8
9 This routine allows an application to check which
10 run-time auto-detected features are available within
11 the library.
12
13 The possible features are:
14
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.
26
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
30 but it may some day.
31
32
33 void *
34 pthread_timechange_handler_np(void *)
35
36 To improve tolerance against operator or time service
37 initiated system clock changes.
38
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.
44
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.
48
49 Parameters
50
51 Although a parameter must be supplied, it is ignored.
52 The value NULL can be used.
53
54 Return values
55
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.
59
60 If run as a thread, the return value is returned
61 through pthread_join().
62
63 The return value should be cast to an integer.
64
65
66 HANDLE
67 pthread_getw32threadhandle_np(pthread_t thread);
68
69 Returns the win32 thread handle that the POSIX
70 thread "thread" is running as.
71
72 Applications can use the win32 handle to set
73 win32 specific attributes of the thread.
74
75
76 int
77 pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind)
78
79 int
80 pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind)
81
82 These two routines are included for Linux compatibility
83 and are direct equivalents to the standard routines
84 pthread_mutexattr_settype
85 pthread_mutexattr_gettype
86
87 pthread_mutexattr_setkind_np accepts the following
88 mutex kinds:
89 PTHREAD_MUTEX_FAST_NP
90 PTHREAD_MUTEX_ERRORCHECK_NP
91 PTHREAD_MUTEX_RECURSIVE_NP
92
93 These are really just equivalent to (respectively):
94 PTHREAD_MUTEX_NORMAL
95 PTHREAD_MUTEX_ERRORCHECK
96 PTHREAD_MUTEX_RECURSIVE
97
98 int
99 pthread_delay_np (const struct timespec *interval);
100
101 This routine causes a thread to delay execution for a specific period of time.
102 This period ends at the current time plus the specified interval. The routine
103 will not return before the end of the period is reached, but may return an
104 arbitrary amount of time after the period has gone by. This can be due to
105 system load, thread priorities, and system timer granularity.
106
107 Specifying an interval of zero (0) seconds and zero (0) nanoseconds is
108 allowed and can be used to force the thread to give up the processor or to
109 deliver a pending cancelation request.
110
111 This routine is a cancelation point.
112
113 The timespec structure contains the following two fields:
114
115 tv_sec is an integer number of seconds.
116 tv_nsec is an integer number of nanoseconds.
117
118 Return Values
119
120 If an error condition occurs, this routine returns an integer value
121 indicating the type of error. Possible return values are as follows:
122
123 0 Successful completion.
124 [EINVAL] The value specified by interval is invalid.
125
126 int
127 pthread_num_processors_np
128
129 This routine (found on HPUX systems) returns the number of processors
130 in the system. This implementation actually returns the number of
131 processors available to the process, which can be a lower number
132 than the system's number, depending on the process's affinity mask.
133
134 BOOL
135 pthread_win32_process_attach_np (void);
136
137 BOOL
138 pthread_win32_process_detach_np (void);
139
140 BOOL
141 pthread_win32_thread_attach_np (void);
142
143 BOOL
144 pthread_win32_thread_detach_np (void);
145
146 These functions contain the code normally run via dllMain
147 when the library is used as a dll but which need to be
148 called explicitly by an application when the library
149 is statically linked.
150
151 You will need to call pthread_win32_process_attach_np() before
152 you can call any pthread routines when statically linking.
153 You should call pthread_win32_process_detach_np() before
154 exiting your application to clean up.
155
156 pthread_win32_thread_attach_np() is currently a no-op, but
157 pthread_win32_thread_detach_np() is needed to clean up
158 the implicit pthread handle that is allocated to a Win32 thread if
159 it calls certain pthreads routines. Call this routine when the
160 Win32 thread exits.
161
162 These functions invariably return TRUE except for
163 pthread_win32_process_attach_np() which will return FALSE
164 if pthreads-win32 initialisation fails.
165
166 int
167 pthreadCancelableWait (HANDLE waitHandle);
168
169 int
170 pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);
171
172 These two functions provide hooks into the pthread_cancel
173 mechanism that will allow you to wait on a Windows handle
174 and make it a cancellation point. Both functions block
175 until either the given w32 handle is signaled, or
176 pthread_cancel has been called. It is implemented using
177 WaitForMultipleObjects on 'waitHandle' and a manually
178 reset w32 event used to implement pthread_cancel.
179
180
181 Non-portable issues
182 -------------------
183
184 Thread priority
185
186 POSIX defines a single contiguous range of numbers that determine a
187 thread's priority. Win32 defines priority classes and priority
188 levels relative to these classes. Classes are simply priority base
189 levels that the defined priority levels are relative to such that,
190 changing a process's priority class will change the priority of all
191 of it's threads, while the threads retain the same relativity to each
192 other.
193
194 A Win32 system defines a single contiguous monotonic range of values
195 that define system priority levels, just like POSIX. However, Win32
196 restricts individual threads to a subset of this range on a
197 per-process basis.
198
199 The following table shows the base priority levels for combinations
200 of priority class and priority value in Win32.
201
202 Process Priority Class Thread Priority Level
203 -----------------------------------------------------------------
204 1 IDLE_PRIORITY_CLASS THREAD_PRIORITY_IDLE
205 1 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
206 1 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
207 1 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_IDLE
208 1 HIGH_PRIORITY_CLASS THREAD_PRIORITY_IDLE
209 2 IDLE_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
210 3 IDLE_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
211 4 IDLE_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
212 4 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
213 5 IDLE_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
214 5 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
215 5 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
216 6 IDLE_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
217 6 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
218 6 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
219 7 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
220 7 Background NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
221 7 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
222 8 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
223 8 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
224 8 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
225 8 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
226 9 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
227 9 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
228 9 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
229 10 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
230 10 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
231 11 Foreground NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
232 11 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
233 11 HIGH_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
234 12 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
235 12 HIGH_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
236 13 HIGH_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
237 14 HIGH_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
238 15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
239 15 HIGH_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
240 15 IDLE_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
241 15 BELOW_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
242 15 NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
243 15 ABOVE_NORMAL_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
244 16 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_IDLE
245 17 REALTIME_PRIORITY_CLASS -7
246 18 REALTIME_PRIORITY_CLASS -6
247 19 REALTIME_PRIORITY_CLASS -5
248 20 REALTIME_PRIORITY_CLASS -4
249 21 REALTIME_PRIORITY_CLASS -3
250 22 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_LOWEST
251 23 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_BELOW_NORMAL
252 24 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_NORMAL
253 25 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_ABOVE_NORMAL
254 26 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_HIGHEST
255 27 REALTIME_PRIORITY_CLASS 3
256 28 REALTIME_PRIORITY_CLASS 4
257 29 REALTIME_PRIORITY_CLASS 5
258 30 REALTIME_PRIORITY_CLASS 6
259 31 REALTIME_PRIORITY_CLASS THREAD_PRIORITY_TIME_CRITICAL
260
261 Windows NT: Values -7, -6, -5, -4, -3, 3, 4, 5, and 6 are not supported.
262
263
264 As you can see, the real priority levels available to any individual
265 Win32 thread are non-contiguous.
266
267 An application using pthreads-win32 should not make assumptions about
268 the numbers used to represent thread priority levels, except that they
269 are monotonic between the values returned by sched_get_priority_min()
270 and sched_get_priority_max(). E.g. Windows 95, 98, NT, 2000, XP make
271 available a non-contiguous range of numbers between -15 and 15, while
272 at least one version of WinCE (3.0) defines the minimum priority
273 (THREAD_PRIORITY_LOWEST) as 5, and the maximum priority
274 (THREAD_PRIORITY_HIGHEST) as 1.
275
276 Internally, pthreads-win32 maps any priority levels between
277 THREAD_PRIORITY_IDLE and THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST,
278 or between THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to
279 THREAD_PRIORITY_HIGHEST. Currently, this also applies to
280 REALTIME_PRIORITY_CLASSi even if levels -7, -6, -5, -4, -3, 3, 4, 5, and 6
281 are supported.
282
283 If it wishes, a Win32 application using pthreads-win32 can use the Win32
284 defined priority macros THREAD_PRIORITY_IDLE through
285 THREAD_PRIORITY_TIME_CRITICAL.

  ViewVC Help
Powered by ViewVC 1.1.22