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

Contents of /trunk/3rdparty/w32pthreads/FAQ

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: 15359 byte(s)
committing r3113 initial commit again...
1 =========================================
2 PTHREADS-WIN32 Frequently Asked Questions
3 =========================================
4
5 INDEX
6 -----
7
8 Q 1 What is it?
9
10 Q 2 Which of the several dll versions do I use?
11 or,
12 What are all these pthread*.dll and pthread*.lib files?
13
14 Q 3 What is the library naming convention?
15
16 Q 4 Cleanup code default style or: it used to work when I built
17 the library myself, but now it doesn't - why?
18
19 Q 5 Why is the default library version now less exception-friendly?
20
21 Q 6 Should I use Cygwin or Mingw32 as a development environment?
22
23 Q 7 Now that pthreads-win32 builds under Mingw32, why do I get
24 memory access violations (segfaults)?
25
26 Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0)
27
28 Q 9 Cancelation doesn't work for me, why?
29
30 Q 10 How do I generate pthreadGCE.dll and libpthreadw32.a for use
31 with Mingw32?
32
33 =============================================================================
34
35 Q 1 What is it?
36 ---
37
38 Pthreads-win32 is an Open Source Software implementation of the
39 Threads component of the POSIX 1003.1c 1995 Standard for Microsoft's
40 Win32 environment. Some functions from POSIX 1003.1b are also
41 supported including semaphores. Other related functions include
42 the set of read-write lock functions. The library also supports
43 some of the functionality of the Open Group's Single Unix
44 specification, version 2, namely mutex types.
45
46 See the file "ANNOUNCE" for more information including standards
47 conformance details and list of supported routines.
48
49
50 ------------------------------------------------------------------------------
51
52 Q 2 Which of the several dll versions do I use?
53 --- or,
54 What are all these pthread*.dll and pthread*.lib files?
55
56 Simply, you only use one of them, but you need to choose carefully.
57
58 The most important choice you need to make is whether to use a
59 version that uses exceptions internally, or not (there are versions
60 of the library that use exceptions as part of the thread
61 cancelation and cleanup implementation, and one that uses
62 setjmp/longjmp instead).
63
64 There is some contension amongst POSIX threads experts as
65 to how POSIX threads cancelation and exit should work
66 with languages that include exceptions and handlers, e.g.
67 C++ and even C (Microsoft's Structured Exceptions).
68
69 The issue is: should cancelation of a thread in, say,
70 a C++ application cause object destructors and C++ exception
71 handlers to be invoked as the stack unwinds during thread
72 exit, or not?
73
74 There seems to be more opinion in favour of using the
75 standard C version of the library (no EH) with C++ applications
76 since this appears to be the assumption commercial pthreads
77 implementations make. Therefore, if you use an EH version
78 of pthreads-win32 then you may be under the illusion that
79 your application will be portable, when in fact it is likely to
80 behave very differently linked with other pthreads libraries.
81
82 Now you may be asking: why have you kept the EH versions of
83 the library?
84
85 There are a couple of reasons:
86 - there is division amongst the experts and so the code may
87 be needed in the future. (Yes, it's in the repository and we
88 can get it out anytime in the future, but ...)
89 - pthreads-win32 is one of the few implementations, and possibly
90 the only freely available one, that has EH versions. It may be
91 useful to people who want to play with or study application
92 behaviour under these conditions.
93
94
95 ------------------------------------------------------------------------------
96
97 Q 3 What is the library naming convention?
98 ---
99
100 Because the library is being built using various exception
101 handling schemes and compilers - and because the library
102 may not work reliably if these are mixed in an application,
103 each different version of the library has it's own name.
104
105 Note 1: the incompatibility is really between EH implementations
106 of the different compilers. It should be possible to use the
107 standard C version from either compiler with C++ applications
108 built with a different compiler. If you use an EH version of
109 the library, then you must use the same compiler for the
110 application. This is another complication and dependency that
111 can be avoided by using only the standard C library version.
112
113 Note 2: if you use a standard C pthread*.dll with a C++
114 application, then any functions that you define that are
115 intended to be called via pthread_cleanup_push() must be
116 __cdecl.
117
118 Note 3: the intention is to also name either the VC or GC
119 version (it should be arbitrary) as pthread.dll, including
120 pthread.lib and libpthread.a as appropriate.
121
122 In general:
123 pthread[VG]{SE,CE,C}.dll
124 pthread[VG]{SE,CE,C}.lib
125
126 where:
127 [VG] indicates the compiler
128 V - MS VC
129 G - GNU C
130
131 {SE,CE,C} indicates the exception handling scheme
132 SE - Structured EH
133 CE - C++ EH
134 C - no exceptions - uses setjmp/longjmp
135
136 For example:
137 pthreadVSE.dll (MSVC/SEH)
138 pthreadGCE.dll (GNUC/C++ EH)
139 pthreadGC.dll (GNUC/not dependent on exceptions)
140
141 The GNU library archive file names have changed to:
142
143 libpthreadGCE.a
144 libpthreadGC.a
145
146
147 ------------------------------------------------------------------------------
148
149 Q 4 Cleanup code default style or: it used to work when I built
150 --- the library myself, but now it doesn't - why?
151
152 Up to and including snapshot 2001-07-12, if not defined, the cleanup
153 style was determined automatically from the compiler used, and one
154 of the following was defined accordingly:
155
156 __CLEANUP_SEH MSVC only
157 __CLEANUP_CXX C++, including MSVC++, GNU G++
158 __CLEANUP_C C, including GNU GCC, not MSVC
159
160 These defines determine the style of cleanup (see pthread.h) and,
161 most importantly, the way that cancelation and thread exit (via
162 pthread_exit) is performed (see the routine ptw32_throw() in private.c).
163
164 In short, the exceptions versions of the library throw an exception
165 when a thread is canceled or exits (via pthread_exit()), which is
166 caught by a handler in the thread startup routine, so that the
167 the correct stack unwinding occurs regardless of where the thread
168 is when it's canceled or exits via pthread_exit().
169
170 After snapshot 2001-07-12, unless your build explicitly defines (e.g.
171 via a compiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then
172 the build now ALWAYS defaults to __CLEANUP_C style cleanup. This style
173 uses setjmp/longjmp in the cancelation and pthread_exit implementations,
174 and therefore won't do stack unwinding even when linked to applications
175 that have it (e.g. C++ apps). This is for consistency with most/all
176 commercial Unix POSIX threads implementations.
177
178 Although it was not clearly documented before, it is still necessary to
179 build your application using the same __CLEANUP_* define as was
180 used for the version of the library that you link with, so that the
181 correct parts of pthread.h are included. That is, the possible
182 defines require the following library versions:
183
184 __CLEANUP_SEH pthreadVSE.dll
185 __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll
186 __CLEANUP_C pthreadVC.dll or pthreadGC.dll
187
188 THE POINT OF ALL THIS IS: if you have not been defining one of these
189 explicitly, then the defaults have been set according to the compiler
190 and language you are using, as described at the top of this
191 section.
192
193 THIS NOW CHANGES, as has been explained above. For example:
194
195 If you were building your application with MSVC++ i.e. using C++
196 exceptions (rather than SEH) and not explicitly defining one of
197 __CLEANUP_*, then __CLEANUP_C++ was defined for you in pthread.h.
198 You should have been linking with pthreadVCE.dll, which does
199 stack unwinding.
200
201 If you now build your application as you had before, pthread.h will now
202 set __CLEANUP_C as the default style, and you will need to link
203 with pthreadVC.dll. Stack unwinding will now NOT occur when a
204 thread is canceled, nor when the thread calls pthread_exit().
205
206 Your application will now most likely behave differently to previous
207 versions, and in non-obvious ways. Most likely is that local
208 objects may not be destroyed or cleaned up after a thread
209 is canceled.
210
211 If you want the same behaviour as before, then you must now define
212 __CLEANUP_C++ explicitly using a compiler option and link with
213 pthreadVCE.dll as you did before.
214
215
216 ------------------------------------------------------------------------------
217
218 Q 5 Why is the default library version now less exception-friendly?
219 ---
220
221 Because most commercial Unix POSIX threads implementations don't allow you to
222 choose to have stack unwinding. (Compaq's TRU64 Unix is possibly an exception.)
223
224 Therefore, providing it in pthread-win32 as a default could be dangerous
225 and non-portable. We still provide the choice but you must now consciously
226 make it.
227
228 WHY NOT REMOVE THE EXCEPTIONS VERSIONS OF THE LIBRARY ALTOGETHER?
229 There are a few reasons:
230 - because there are well respected POSIX threads people who believe
231 that POSIX threads implementations should be exceptions-aware and
232 do the expected thing in that context. (There are equally respected
233 people who believe it should not be easily accessible, if it's there
234 at all.)
235 - because pthreads-win32 is one of the few implementations that has
236 the choice, perhaps the only freely available one, and so offers
237 a laboratory to people who may want to explore the effects;
238 - although the code will always be around somewhere for anyone who
239 wants it, once it's removed from the current version it will not be
240 nearly as visible to people who may have a use for it.
241
242
243 ------------------------------------------------------------------------------
244
245 Q 6 Should I use Cygwin or Mingw32 as a development environment?
246 ---
247
248 Important: see Q7 also.
249
250 Use Mingw32 with the MSVCRT library to build applications that use
251 the pthreads DLL.
252
253 Cygwin's own internal support for POSIX threads is growing.
254 Consult that project's documentation for more information.
255
256 ------------------------------------------------------------------------------
257
258 Q 7 Now that pthreads-win32 builds under Mingw32, why do I get
259 --- memory access violations (segfaults)?
260
261 The latest Mingw32 package has thread-safe exception handling (see Q10).
262 Also, see Q6 above.
263
264 ------------------------------------------------------------------------------
265
266 Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0)
267 ---
268
269 >
270 > I'm a "rookie" when it comes to your pthread implementation. I'm currently
271 > desperately trying to install the prebuilt .dll file into my MSVC compiler.
272 > Could you please provide me with explicit instructions on how to do this (or
273 > direct me to a resource(s) where I can acquire such information)?
274 >
275 > Thank you,
276 >
277
278 You should have a .dll, .lib, .def, and three .h files. It is recommended
279 that you use pthreadVC.dll, rather than pthreadVCE.dll or pthreadVSE.dll
280 (see Q2 above).
281
282 The .dll can go in any directory listed in your PATH environment
283 variable, so putting it into C:\WINDOWS should work.
284
285 The .lib file can go in any directory listed in your LIB environment
286 variable.
287
288 The .h files can go in any directory listed in your INCLUDE
289 environment variable.
290
291 Or you might prefer to put the .lib and .h files into a new directory
292 and add its path to LIB and INCLUDE. You can probably do this easiest
293 by editing the file:-
294
295 C:\Program Files\DevStudio\vc\bin\vcvars32.bat
296
297 The .def file isn't used by anything in the pre-compiled version but
298 is included for information.
299
300 Cheers.
301 Ross
302
303 ------------------------------------------------------------------------------
304
305 Q 9 Cancelation doesn't work for me, why?
306 ---
307
308 > I'm investigating a problem regarding thread cancelation. The thread I want
309 > to cancel has PTHREAD_CANCEL_ASYNCHRONOUS, however, this piece of code
310 > blocks on the join():
311 >
312 > if ((retv = Pthread_cancel( recvThread )) == 0)
313 > {
314 > retv = Pthread_join( recvThread, 0 );
315 > }
316 >
317 > Pthread_* are just macro's; they call pthread_*.
318 >
319 > The thread recvThread seems to block on a select() call. It doesn't get
320 > cancelled.
321 >
322 > Two questions:
323 >
324 > 1) is this normal behaviour?
325 >
326 > 2) if not, how does the cancel mechanism work? I'm not very familliar to
327 > win32 programming, so I don't really understand how the *Event() family of
328 > calls work.
329
330 The answer to your first question is, normal POSIX behaviour would
331 be to asynchronously cancel the thread. However, even that doesn't
332 guarantee cancelation as the standard only says it should be
333 cancelled as soon as possible.
334
335 Snapshot 99-11-02 or earlier only partially supports asynchronous cancellation.
336 Snapshots since then simulate async cancelation by poking the address of
337 a cancelation routine into the PC of the threads context. This requires
338 the thread to be resumed in some way for the cancelation to actually
339 proceed. This is not true async cancelation, but it is as close as we've
340 been able to get to it.
341
342 If the thread you're trying to cancel is blocked (for instance, it could be
343 waiting for data from the network), it will only get cancelled when it unblocks
344 (when the data arrives). For true pre-emptive cancelation in these cases,
345 pthreads-win32 from snapshot 2004-05-16 can automatically recognise and use the
346 QueueUserAPCEx package by Panagiotis E. Hadjidoukas. This package is available
347 from the pthreads-win32 ftp site and is included in the pthreads-win32
348 self-unpacking zip from 2004-05-16 onwards.
349
350 Using deferred cancelation would normally be the way to go, however,
351 even though the POSIX threads standard lists a number of C library
352 functions that are defined as deferred cancelation points, there is
353 no hookup between those which are provided by Windows and the
354 pthreads-win32 library.
355
356 Incidently, it's worth noting for code portability that the older POSIX
357 threads standards cancelation point lists didn't include "select" because
358 (as I read in Butenhof) it wasn't part of POSIX. However, it does appear in
359 the SUSV3.
360
361 Effectively, the only mandatory cancelation points that pthreads-win32
362 recognises are those the library implements itself, ie.
363
364 pthread_testcancel
365 pthread_cond_wait
366 pthread_cond_timedwait
367 pthread_join
368 sem_wait
369 sem_timedwait
370 pthread_delay_np
371
372 The following routines from the non-mandatory list in SUSV3 are
373 cancelation points in pthreads-win32:
374
375 pthread_rwlock_wrlock
376 pthread_rwlock_timedwrlock
377
378 The following routines from the non-mandatory list in SUSV3 are not
379 cancelation points in pthreads-win32:
380
381 pthread_rwlock_rdlock
382 pthread_rwlock_timedrdlock
383
384 Pthreads-win32 also provides two functions that allow you to create
385 cancelation points within your application, but only for cases where
386 a thread is going to block on a Win32 handle. These are:
387
388 pthreadCancelableWait(HANDLE waitHandle) /* Infinite wait */
389
390 pthreadCancelableTimedWait(HANDLE waitHandle, DWORD timeout)
391
392 ------------------------------------------------------------------------------
393
394
395 Q 10 How do I create thread-safe applications using
396 ---- pthreadGCE.dll, libpthreadw32.a and Mingw32?
397
398 This should not be a problem with recent versions of MinGW32.
399
400 For early versions, see Thomas Pfaff's email at:
401 http://sources.redhat.com/ml/pthreads-win32/2002/msg00000.html
402 ------------------------------------------------------------------------------
403

  ViewVC Help
Powered by ViewVC 1.1.22