| ========================================= |
| PTHREADS-WIN32 Frequently Asked Questions |
| ========================================= |
| |
| INDEX |
| ----- |
| |
| Q 1 What is it? |
| |
| Q 2 Which of the several dll versions do I use? |
| or, |
| What are all these pthread*.dll and pthread*.lib files? |
| |
| Q 3 What is the library naming convention? |
| |
| Q 4 Cleanup code default style or: it used to work when I built |
| the library myself, but now it doesn't - why? |
| |
| Q 5 Why is the default library version now less exception-friendly? |
| |
| Q 6 Should I use Cygwin or Mingw32 as a development environment? |
| |
| Q 7 Now that pthreads-win32 builds under Mingw32, why do I get |
| memory access violations (segfaults)? |
| |
| Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0) |
| |
| Q 9 Cancelation doesn't work for me, why? |
| |
| Q 10 How do I generate pthreadGCE.dll and libpthreadw32.a for use |
| with Mingw32? |
| |
| ============================================================================= |
| |
| Q 1 What is it? |
| --- |
| |
| Pthreads-win32 is an Open Source Software implementation of the |
| Threads component of the POSIX 1003.1c 1995 Standard for Microsoft's |
| Win32 environment. Some functions from POSIX 1003.1b are also |
| supported including semaphores. Other related functions include |
| the set of read-write lock functions. The library also supports |
| some of the functionality of the Open Group's Single Unix |
| specification, version 2, namely mutex types. |
| |
| See the file "ANNOUNCE" for more information including standards |
| conformance details and list of supported routines. |
| |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 2 Which of the several dll versions do I use? |
| --- or, |
| What are all these pthread*.dll and pthread*.lib files? |
| |
| Simply, you only use one of them, but you need to choose carefully. |
| |
| The most important choice you need to make is whether to use a |
| version that uses exceptions internally, or not (there are versions |
| of the library that use exceptions as part of the thread |
| cancelation and cleanup implementation, and one that uses |
| setjmp/longjmp instead). |
| |
| There is some contension amongst POSIX threads experts as |
| to how POSIX threads cancelation and exit should work |
| with languages that include exceptions and handlers, e.g. |
| C++ and even C (Microsoft's Structured Exceptions). |
| |
| The issue is: should cancelation of a thread in, say, |
| a C++ application cause object destructors and C++ exception |
| handlers to be invoked as the stack unwinds during thread |
| exit, or not? |
| |
| There seems to be more opinion in favour of using the |
| standard C version of the library (no EH) with C++ applications |
| since this appears to be the assumption commercial pthreads |
| implementations make. Therefore, if you use an EH version |
| of pthreads-win32 then you may be under the illusion that |
| your application will be portable, when in fact it is likely to |
| behave very differently linked with other pthreads libraries. |
| |
| Now you may be asking: why have you kept the EH versions of |
| the library? |
| |
| There are a couple of reasons: |
| - there is division amongst the experts and so the code may |
| be needed in the future. (Yes, it's in the repository and we |
| can get it out anytime in the future, but ...) |
| - pthreads-win32 is one of the few implementations, and possibly |
| the only freely available one, that has EH versions. It may be |
| useful to people who want to play with or study application |
| behaviour under these conditions. |
| |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 3 What is the library naming convention? |
| --- |
| |
| Because the library is being built using various exception |
| handling schemes and compilers - and because the library |
| may not work reliably if these are mixed in an application, |
| each different version of the library has it's own name. |
| |
| Note 1: the incompatibility is really between EH implementations |
| of the different compilers. It should be possible to use the |
| standard C version from either compiler with C++ applications |
| built with a different compiler. If you use an EH version of |
| the library, then you must use the same compiler for the |
| application. This is another complication and dependency that |
| can be avoided by using only the standard C library version. |
| |
| Note 2: if you use a standard C pthread*.dll with a C++ |
| application, then any functions that you define that are |
| intended to be called via pthread_cleanup_push() must be |
| __cdecl. |
| |
| Note 3: the intention is to also name either the VC or GC |
| version (it should be arbitrary) as pthread.dll, including |
| pthread.lib and libpthread.a as appropriate. |
| |
| In general: |
| pthread[VG]{SE,CE,C}.dll |
| pthread[VG]{SE,CE,C}.lib |
| |
| where: |
| [VG] indicates the compiler |
| V - MS VC |
| G - GNU C |
| |
| {SE,CE,C} indicates the exception handling scheme |
| SE - Structured EH |
| CE - C++ EH |
| C - no exceptions - uses setjmp/longjmp |
| |
| For example: |
| pthreadVSE.dll (MSVC/SEH) |
| pthreadGCE.dll (GNUC/C++ EH) |
| pthreadGC.dll (GNUC/not dependent on exceptions) |
| |
| The GNU library archive file names have changed to: |
| |
| libpthreadGCE.a |
| libpthreadGC.a |
| |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 4 Cleanup code default style or: it used to work when I built |
| --- the library myself, but now it doesn't - why? |
| |
| Up to and including snapshot 2001-07-12, if not defined, the cleanup |
| style was determined automatically from the compiler used, and one |
| of the following was defined accordingly: |
| |
| __CLEANUP_SEH MSVC only |
| __CLEANUP_CXX C++, including MSVC++, GNU G++ |
| __CLEANUP_C C, including GNU GCC, not MSVC |
| |
| These defines determine the style of cleanup (see pthread.h) and, |
| most importantly, the way that cancelation and thread exit (via |
| pthread_exit) is performed (see the routine ptw32_throw() in private.c). |
| |
| In short, the exceptions versions of the library throw an exception |
| when a thread is canceled or exits (via pthread_exit()), which is |
| caught by a handler in the thread startup routine, so that the |
| the correct stack unwinding occurs regardless of where the thread |
| is when it's canceled or exits via pthread_exit(). |
| |
| After snapshot 2001-07-12, unless your build explicitly defines (e.g. |
| via a compiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then |
| the build now ALWAYS defaults to __CLEANUP_C style cleanup. This style |
| uses setjmp/longjmp in the cancelation and pthread_exit implementations, |
| and therefore won't do stack unwinding even when linked to applications |
| that have it (e.g. C++ apps). This is for consistency with most/all |
| commercial Unix POSIX threads implementations. |
| |
| Although it was not clearly documented before, it is still necessary to |
| build your application using the same __CLEANUP_* define as was |
| used for the version of the library that you link with, so that the |
| correct parts of pthread.h are included. That is, the possible |
| defines require the following library versions: |
| |
| __CLEANUP_SEH pthreadVSE.dll |
| __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll |
| __CLEANUP_C pthreadVC.dll or pthreadGC.dll |
| |
| THE POINT OF ALL THIS IS: if you have not been defining one of these |
| explicitly, then the defaults have been set according to the compiler |
| and language you are using, as described at the top of this |
| section. |
| |
| THIS NOW CHANGES, as has been explained above. For example: |
| |
| If you were building your application with MSVC++ i.e. using C++ |
| exceptions (rather than SEH) and not explicitly defining one of |
| __CLEANUP_*, then __CLEANUP_C++ was defined for you in pthread.h. |
| You should have been linking with pthreadVCE.dll, which does |
| stack unwinding. |
| |
| If you now build your application as you had before, pthread.h will now |
| set __CLEANUP_C as the default style, and you will need to link |
| with pthreadVC.dll. Stack unwinding will now NOT occur when a |
| thread is canceled, nor when the thread calls pthread_exit(). |
| |
| Your application will now most likely behave differently to previous |
| versions, and in non-obvious ways. Most likely is that local |
| objects may not be destroyed or cleaned up after a thread |
| is canceled. |
| |
| If you want the same behaviour as before, then you must now define |
| __CLEANUP_C++ explicitly using a compiler option and link with |
| pthreadVCE.dll as you did before. |
| |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 5 Why is the default library version now less exception-friendly? |
| --- |
| |
| Because most commercial Unix POSIX threads implementations don't allow you to |
| choose to have stack unwinding. (Compaq's TRU64 Unix is possibly an exception.) |
| |
| Therefore, providing it in pthread-win32 as a default could be dangerous |
| and non-portable. We still provide the choice but you must now consciously |
| make it. |
| |
| WHY NOT REMOVE THE EXCEPTIONS VERSIONS OF THE LIBRARY ALTOGETHER? |
| There are a few reasons: |
| - because there are well respected POSIX threads people who believe |
| that POSIX threads implementations should be exceptions-aware and |
| do the expected thing in that context. (There are equally respected |
| people who believe it should not be easily accessible, if it's there |
| at all.) |
| - because pthreads-win32 is one of the few implementations that has |
| the choice, perhaps the only freely available one, and so offers |
| a laboratory to people who may want to explore the effects; |
| - although the code will always be around somewhere for anyone who |
| wants it, once it's removed from the current version it will not be |
| nearly as visible to people who may have a use for it. |
| |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 6 Should I use Cygwin or Mingw32 as a development environment? |
| --- |
| |
| Important: see Q7 also. |
| |
| Use Mingw32 with the MSVCRT library to build applications that use |
| the pthreads DLL. |
| |
| Cygwin's own internal support for POSIX threads is growing. |
| Consult that project's documentation for more information. |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 7 Now that pthreads-win32 builds under Mingw32, why do I get |
| --- memory access violations (segfaults)? |
| |
| The latest Mingw32 package has thread-safe exception handling (see Q10). |
| Also, see Q6 above. |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 8 How do I use pthread.dll for Win32 (Visual C++ 5.0) |
| --- |
| |
| > |
| > I'm a "rookie" when it comes to your pthread implementation. I'm currently |
| > desperately trying to install the prebuilt .dll file into my MSVC compiler. |
| > Could you please provide me with explicit instructions on how to do this (or |
| > direct me to a resource(s) where I can acquire such information)? |
| > |
| > Thank you, |
| > |
| |
| You should have a .dll, .lib, .def, and three .h files. It is recommended |
| that you use pthreadVC.dll, rather than pthreadVCE.dll or pthreadVSE.dll |
| (see Q2 above). |
| |
| The .dll can go in any directory listed in your PATH environment |
| variable, so putting it into C:\WINDOWS should work. |
| |
| The .lib file can go in any directory listed in your LIB environment |
| variable. |
| |
| The .h files can go in any directory listed in your INCLUDE |
| environment variable. |
| |
| Or you might prefer to put the .lib and .h files into a new directory |
| and add its path to LIB and INCLUDE. You can probably do this easiest |
| by editing the file:- |
| |
| C:\Program Files\DevStudio\vc\bin\vcvars32.bat |
| |
| The .def file isn't used by anything in the pre-compiled version but |
| is included for information. |
| |
| Cheers. |
| Ross |
| |
| ------------------------------------------------------------------------------ |
| |
| Q 9 Cancelation doesn't work for me, why? |
| --- |
| |
| > I'm investigating a problem regarding thread cancelation. The thread I want |
| > to cancel has PTHREAD_CANCEL_ASYNCHRONOUS, however, this piece of code |
| > blocks on the join(): |
| > |
| > if ((retv = Pthread_cancel( recvThread )) == 0) |
| > { |
| > retv = Pthread_join( recvThread, 0 ); |
| > } |
| > |
| > Pthread_* are just macro's; they call pthread_*. |
| > |
| > The thread recvThread seems to block on a select() call. It doesn't get |
| > cancelled. |
| > |
| > Two questions: |
| > |
| > 1) is this normal behaviour? |
| > |
| > 2) if not, how does the cancel mechanism work? I'm not very familliar to |
| > win32 programming, so I don't really understand how the *Event() family of |
| > calls work. |
| |
| The answer to your first question is, normal POSIX behaviour would |
| be to asynchronously cancel the thread. However, even that doesn't |
| guarantee cancelation as the standard only says it should be |
| cancelled as soon as possible. |
| |
| Snapshot 99-11-02 or earlier only partially supports asynchronous cancellation. |
| Snapshots since then simulate async cancelation by poking the address of |
| a cancelation routine into the PC of the threads context. This requires |
| the thread to be resumed in some way for the cancelation to actually |
| proceed. This is not true async cancelation, but it is as close as we've |
| been able to get to it. |
| |
| If the thread you're trying to cancel is blocked (for instance, it could be |
| waiting for data from the network), it will only get cancelled when it unblocks |
| (when the data arrives). For true pre-emptive cancelation in these cases, |
| pthreads-win32 from snapshot 2004-05-16 can automatically recognise and use the |
| QueueUserAPCEx package by Panagiotis E. Hadjidoukas. This package is available |
| from the pthreads-win32 ftp site and is included in the pthreads-win32 |
| self-unpacking zip from 2004-05-16 onwards. |
| |
| Using deferred cancelation would normally be the way to go, however, |
| even though the POSIX threads standard lists a number of C library |
| functions that are defined as deferred cancelation points, there is |
| no hookup between those which are provided by Windows and the |
| pthreads-win32 library. |
| |
| Incidently, it's worth noting for code portability that the older POSIX |
| threads standards cancelation point lists didn't include "select" because |
| (as I read in Butenhof) it wasn't part of POSIX. However, it does appear in |
| the SUSV3. |
| |
| Effectively, the only mandatory cancelation points that pthreads-win32 |
| recognises are those the library implements itself, ie. |
| |
| pthread_testcancel |
| pthread_cond_wait |
| pthread_cond_timedwait |
| pthread_join |
| sem_wait |
| sem_timedwait |
| pthread_delay_np |
| |
| The following routines from the non-mandatory list in SUSV3 are |
| cancelation points in pthreads-win32: |
| |
| pthread_rwlock_wrlock |
| pthread_rwlock_timedwrlock |
| |
| The following routines from the non-mandatory list in SUSV3 are not |
| cancelation points in pthreads-win32: |
| |
| pthread_rwlock_rdlock |
| pthread_rwlock_timedrdlock |
| |
| Pthreads-win32 also provides two functions that allow you to create |
| cancelation points within your application, but only for cases where |
| a thread is going to block on a Win32 handle. These are: |
| |
| pthreadCancelableWait(HANDLE waitHandle) /* Infinite wait */ |
| |
| pthreadCancelableTimedWait(HANDLE waitHandle, DWORD timeout) |
| |
| ------------------------------------------------------------------------------ |
| |
| |
| Q 10 How do I create thread-safe applications using |
| ---- pthreadGCE.dll, libpthreadw32.a and Mingw32? |
| |
| This should not be a problem with recent versions of MinGW32. |
| |
| For early versions, see Thomas Pfaff's email at: |
| http://sources.redhat.com/ml/pthreads-win32/2002/msg00000.html |
| ------------------------------------------------------------------------------ |
| |