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 =========================================
6 -----
8 Q 1 What is it?
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?
14 Q 3 What is the library naming convention?
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?
19 Q 5 Why is the default library version now less exception-friendly?
21 Q 6 Should I use Cygwin or Mingw32 as a development environment?
23 Q 7 Now that pthreads-win32 builds under Mingw32, why do I get
24 memory access violations (segfaults)?
26 Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0)
28 Q 9 Cancelation doesn't work for me, why?
30 Q 10 How do I generate pthreadGCE.dll and libpthreadw32.a for use
31 with Mingw32?
33 =============================================================================
35 Q 1 What is it?
36 ---
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.
46 See the file "ANNOUNCE" for more information including standards
47 conformance details and list of supported routines.
50 ------------------------------------------------------------------------------
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?
56 Simply, you only use one of them, but you need to choose carefully.
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).
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).
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?
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.
82 Now you may be asking: why have you kept the EH versions of
83 the library?
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.
95 ------------------------------------------------------------------------------
97 Q 3 What is the library naming convention?
98 ---
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.
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.
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.
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.
122 In general:
123 pthread[VG]{SE,CE,C}.dll
124 pthread[VG]{SE,CE,C}.lib
126 where:
127 [VG] indicates the compiler
128 V - MS VC
129 G - GNU C
131 {SE,CE,C} indicates the exception handling scheme
132 SE - Structured EH
133 CE - C++ EH
134 C - no exceptions - uses setjmp/longjmp
136 For example:
137 pthreadVSE.dll (MSVC/SEH)
138 pthreadGCE.dll (GNUC/C++ EH)
139 pthreadGC.dll (GNUC/not dependent on exceptions)
141 The GNU library archive file names have changed to:
143 libpthreadGCE.a
144 libpthreadGC.a
147 ------------------------------------------------------------------------------
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?
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:
157 __CLEANUP_CXX C++, including MSVC++, GNU G++
158 __CLEANUP_C C, including GNU GCC, not MSVC
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).
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().
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.
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:
184 __CLEANUP_SEH pthreadVSE.dll
185 __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll
186 __CLEANUP_C pthreadVC.dll or pthreadGC.dll
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.
193 THIS NOW CHANGES, as has been explained above. For example:
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.
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().
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.
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.
216 ------------------------------------------------------------------------------
218 Q 5 Why is the default library version now less exception-friendly?
219 ---
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.)
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.
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.
243 ------------------------------------------------------------------------------
245 Q 6 Should I use Cygwin or Mingw32 as a development environment?
246 ---
248 Important: see Q7 also.
250 Use Mingw32 with the MSVCRT library to build applications that use
251 the pthreads DLL.
253 Cygwin's own internal support for POSIX threads is growing.
254 Consult that project's documentation for more information.
256 ------------------------------------------------------------------------------
258 Q 7 Now that pthreads-win32 builds under Mingw32, why do I get
259 --- memory access violations (segfaults)?
261 The latest Mingw32 package has thread-safe exception handling (see Q10).
262 Also, see Q6 above.
264 ------------------------------------------------------------------------------
266 Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0)
267 ---
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 >
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).
282 The .dll can go in any directory listed in your PATH environment
283 variable, so putting it into C:\WINDOWS should work.
285 The .lib file can go in any directory listed in your LIB environment
286 variable.
288 The .h files can go in any directory listed in your INCLUDE
289 environment variable.
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:-
295 C:\Program Files\DevStudio\vc\bin\vcvars32.bat
297 The .def file isn't used by anything in the pre-compiled version but
298 is included for information.
300 Cheers.
301 Ross
303 ------------------------------------------------------------------------------
305 Q 9 Cancelation doesn't work for me, why?
306 ---
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.
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.
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.
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.
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.
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.
361 Effectively, the only mandatory cancelation points that pthreads-win32
362 recognises are those the library implements itself, ie.
364 pthread_testcancel
365 pthread_cond_wait
366 pthread_cond_timedwait
367 pthread_join
368 sem_wait
369 sem_timedwait
370 pthread_delay_np
372 The following routines from the non-mandatory list in SUSV3 are
373 cancelation points in pthreads-win32:
375 pthread_rwlock_wrlock
376 pthread_rwlock_timedwrlock
378 The following routines from the non-mandatory list in SUSV3 are not
379 cancelation points in pthreads-win32:
381 pthread_rwlock_rdlock
382 pthread_rwlock_timedrdlock
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:
388 pthreadCancelableWait(HANDLE waitHandle) /* Infinite wait */
390 pthreadCancelableTimedWait(HANDLE waitHandle, DWORD timeout)
392 ------------------------------------------------------------------------------
395 Q 10 How do I create thread-safe applications using
396 ---- pthreadGCE.dll, libpthreadw32.a and Mingw32?
398 This should not be a problem with recent versions of MinGW32.
400 For early versions, see Thomas Pfaff's email at:
401 http://sources.redhat.com/ml/pthreads-win32/2002/msg00000.html
402 ------------------------------------------------------------------------------

  ViewVC Help
Powered by ViewVC 1.1.22