From d14156f2c1d4a9db64cfef0370883db8930e3a6b Mon Sep 17 00:00:00 2001 From: rpj Date: Sat, 2 Mar 2002 05:00:44 +0000 Subject: Changes to documentation and makefiles. --- ANNOUNCE | 490 +++++------------------------- FAQ | 785 ++++++++++++++++++++++++------------------------ NEWS | 482 ++++++++++++++++++++++-------- PROGRESS | 8 +- README | 870 ++++++++++++++++++++++++++++-------------------------- TODO | 14 +- tests/GNUmakefile | 4 +- tests/Makefile | 6 +- tests/exit4.c | 104 ------- 9 files changed, 1296 insertions(+), 1467 deletions(-) delete mode 100644 tests/exit4.c diff --git a/ANNOUNCE b/ANNOUNCE index 7e47bd4..795eec0 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -1,8 +1,8 @@ - PTHREADS-WIN32 SNAPSHOT 2002-??-?? - ---------------------------------- - Web Site: http://sources.redhat.com/pthreads-win32/ - FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 - Coordinator: Ross Johnson + PTHREADS-WIN32 SNAPSHOT 2002-03-02 + ---------------------------------- + Web Site: http://sources.redhat.com/pthreads-win32/ + FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 + Maintainer: Ross Johnson We are pleased to announce the availability of a new snapshot of @@ -23,366 +23,43 @@ Please see the 'Acknowledgements' section at the end of this announcement for the list of contributors. -------------------------------- -Changes since the last snapshot -------------------------------- +Acknowledgements +---------------- +This library is based substantially on a Win32 pthreads +implementation contributed by John Bossom . -Cleanup code default style. (IMPORTANT) ----------------------------------------------------------------------- -Previously, if not defined, the cleanup style was determined automatically -from the compiler/language, 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(). - -In this and future snapshots, unless the 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 -current commercial Unix POSIX threads implementations. Compaq's TRU64 -may be an exception (no pun intended) and possible future trend. - -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 - -E.g. regardless of whether your app is C or C++, if you link with -pthreadVC.lib or libpthreadGC.a, then you must define __CLEANUP_C. - - -THE POINT OF ALL THIS IS: if you have not been defining one of these -explicitly, then the defaults as described at the top of this -section were being used. - -THIS NOW CHANGES, as has been explained above, but to try to make this -clearer here's an example: - -If you were building your application with MSVC++ i.e. using C++ -exceptions and not explicitly defining one of __CLEANUP_*, then -__CLEANUP_C++ was automatically 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 -automatically 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, or 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 locally -instantiated 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. - - -WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY? -Because no commercial Unix POSIX threads implementation allows you to -choose to have stack unwinding. Therefore, providing it in pthread-win32 -as a default is dangerous. We still provide the choice but unless -you consciously choose to do otherwise, your pthreads applications will -now run or crash in similar ways irrespective of the threads platform -you use. Or at least this is the hope. - - -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, for unconditional conformity to other implementations.) -- 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. - - -Source module splitting ------------------------ -In order to enable smaller image sizes to be generated -for applications that link statically with the library, -most routines have been separated out into individual -source code files. - -This is being done in such a way as to be backward compatible. -The old source files are reused to congregate the individual -routine files into larger translation units (via a bunch of -# includes) so that the compiler can still optimise wherever -possible, e.g. through inlining, which can only be done -within the same translation unit. - -It is also possible to build the entire library by compiling -the single file named "pthread.c", which just #includes all -the secondary congregation source files. The compiler -may be able to use this to do more inlining of routines. - -Although the GNU compiler is able to produce libraries with -the necessary separation (the -ffunction-segments switch), -AFAIK, the MSVC and other compilers don't have this feature. - -Finally, since I use makefiles and command-line compilation, -I don't know what havoc this reorganisation may wreak amongst -IDE project file users. You should be able to continue -using your existing project files without modification. - - -New non-portable function -------------------------- -pthread_num_processors_np(): Returns the number of processors -in the system that are available to the process, as determined -from the processor affinity mask. - - -Platform dependence -------------------- -As Win95 doesn't provide one, the library now contains -it's own InterlockedCompareExchange() routine, which is used -whenever Windows doesn't provide it. InterlockedCompareExchange() -is used to implement spinlocks and barriers, and also in mutexes. -This routine relies on the CMPXCHG machine instruction which -is not available on i386 CPUs. This library (from snapshot -20010712 onwards) is therefore no longer supported on i386 -processor platforms. - - -New standard routines ---------------------- -For source code portability only - rwlocks cannot be process shared yet. - - pthread_rwlockattr_init() - pthread_rwlockattr_destroy() - pthread_rwlockattr_setpshared() - pthread_rwlockattr_getpshared() - -As defined in the new POSIX standard, and the Single Unix Spec version 3: - - sem_timedwait() - pthread_mutex_timedlock() - Alexander Terekhov and Thomas Pfaff - pthread_rwlock_timedrdlock() - adapted from pthread_rwlock_rdlock() - pthread_rwlock_timedwrlock() - adapted from pthread_rwlock_wrlock() - - -New non-portable routine ------------------------- -To improve tolerance against operator or time service initiated -system clock changes, the following routine is provided: - - pthread_timechange_handler_np() - -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. -- Suggested by Alexander Terekhov - - -pthread.h no longer includes windows.h --------------------------------------- -[Not yet for G++] - -This was done to prevent conflicts. - -HANDLE, DWORD, and NULL are temporarily defined within pthread.h if -they are not already. - - -pthread.h, sched.h and semaphore.h now use dllexport/dllimport --------------------------------------------------------------- -Not only to avoid the need for the pthread.def file, but to -improve performance. Apparently, declaring functions with dllimport -generates a direct call to the function and avoids the overhead -of a stub function call. - -Bug fixes ---------- -* Fixed potential NULL pointer dereferences in pthread_mutexattr_init, -pthread_mutexattr_getpshared, pthread_barrierattr_init, -pthread_barrierattr_getpshared, and pthread_condattr_getpshared. -- Scott McCaskill - -* Removed potential race condition in pthread_mutex_trylock and -pthread_mutex_lock; -- Alexander Terekhov - -* The behaviour of pthread_mutex_trylock in relation to -recursive mutexes was inconsistent with commercial implementations. -Trylock would return EBUSY if the lock was owned already by the -calling thread regardless of mutex type. Trylock now increments the -recursion count and returns 0 for RECURSIVE mutexes, and will -return EDEADLK rather than EBUSY for ERRORCHECK mutexes. This is -consistent with Solaris. -- Thomas Pfaff - -* Found a fix for the library and workaround for applications for -the known bug #2, i.e. where __CLEANUP_CXX or __CLEANUP_SEH is defined. -See the "Known Bugs in this snapshot" section below. - -This could be made transparent to applications by replacing the macros that -define the current C++ and SEH versions of pthread_cleanup_push/pop -with the C version, but AFAIK cleanup handlers would not then run in the -correct sequence with destructors and exception cleanup handlers when -an exception occurs. - -* Cancelation once started in a thread cannot now be inadvertantly -double canceled. That is, once a thread begins it's cancelation run, -cancelation is disabled and a subsequent cancel request will -return an error (ESRCH). - - ---------------------------- -Known bugs in this snapshot ---------------------------- - -1. Under MS VC++ (only tested with version 6.0), a term_func - set via the standard C++ set_terminate() function is not called. - - Notes from the MSVC++ manual: - 1) A term_func() should call exit(), otherwise - abort() will be called on return to the caller. - A call to abort() raises SIGABRT and the default signal handler - for all signals terminates the calling program with - exit code 3. - 2) A term_func() must not throw an exception. Therefore - term_func() should not call pthread_exit(), which - works by throwing an exception (pthreadVCE or pthreadVSE) - or by calling longjmp (pthreadVC). - - Workaround: avoid using pthread_exit() in C++ applications. Exit - threads by dropping through the end of the thread routine. - -2. Cancellation problems in optimised code - - Milan Gardian +The implementation of Condition Variables uses algorithms developed +by Alexander Terekhov and Louis Thomas. - Workaround [rpj - 2 Feb 2002] - ----------------------------- - The problem disappears when /Ob0 is used, i.e. /O2 /Ob0 works OK, - but if you want to use inlining optimisation you can be much more - specific about where it's switched off and on by using a pragma. - - So the inlining optimisation is interfering with the way that cleanup - handlers are run. It appears to relate to auto-inlining of class methods - since this is the only auto inlining that is performed at /O1 optimisation - (functions with the "inline" qualifier are also inlined, but the problem - doesn't appear to involve any such functions in the library or testsuite). - - In order to confirm the inlining culprit, the following use of pragmas - eliminate the problem but I don't know how to make it transparent, putting - it in, say, pthread.h where pthread_cleanup_push defined as a macro. - - #pragma inline_depth(0) - pthread_cleanup_push(handlerFunc, (void *) &arg); - - /* ... */ - - pthread_cleanup_pop(0); - #pragma inline_depth() - - Note the empty () pragma value after the pop macro. This resets depth to the - default. Or you can specify a non-zero depth here. - - The pragma is also needed (and now used) within the library itself wherever - cleanup handlers are used (condvar.c and rwlock.c). - - Use of these pragmas allows compiler optimisations /O1 and /O2 to be - used for either or both the library and applications. - - Experimenting further, I found that wrapping the actual cleanup handler - function with #pragma auto_inline(off|on) does NOT work. - - MSVC6.0 doesn't appear to support the C99 standard's _Pragma directive, - however, later versions may. This form is embeddable inside #define - macros, which would be ideal because it would mean that it could be added - to the push/pop macro definitions in pthread.h and hidden from the - application programmer. - - [/rpj] - - Original problem description - ---------------------------- - - The cancellation (actually, cleanup-after-cancel) tests fail when using VC - (professional) optimisation switches (/O1 or /O2) in pthreads library. I - have not investigated which concrete optimisation technique causes this - problem (/Og, /Oi, /Ot, /Oy, /Ob1, /Gs, /Gf, /Gy, etc.), but here is a - summary of builds and corresponding failures: - - * pthreads VSE (optimised tests): OK - * pthreads VCE (optimised tests): Failed "cleanup1" test (runtime) - - * pthreads VSE (DLL in CRT, optimised tests): OK - * pthreads VCE (DLL in CRT, optimised tests): Failed "cleanup1" test - (runtime) +The implementation of POSIX mutexes has been improved by Thomas Pfaff. - Please note that while in VSE version of the pthreads library the - optimisation does not really have any impact on the tests (they pass OK), in - VCE version addition of optimisation (/O2 in this case) causes the tests to - fail uniformly - either in "cleanup0" or "cleanup1" test cases. - - Please note that all the tests above use default pthreads DLL (no - optimisations, linked with either static or DLL CRT, based on test type). - Therefore the problem lies not within the pthreads DLL but within the - compiled client code (the application using pthreads -> involvement of - "pthread.h"). - - I think the message of this section is that usage of VCE version of pthreads - in applications relying on cancellation/cleanup AND using optimisations for - creation of production code is highly unreliable for the current version of - the pthreads library. +The implementation of Spinlocks and Barriers was contributed +by Ross Johnson. -3. errno - - Under MSVC, errno isn't working. +The implementation of read/write locks was contributed by +Aurelio Medina and improved by Alexander Terekhov. +Many others have contributed significant time and effort to solve crutial +problems in order to make the library workable, robust and reliable. + +There is also a separate CONTRIBUTORS file. This file and others are +on the web site: + + http://sources.redhat.com/pthreads-win32 + +As much as possible, the ChangeLog file acknowledges contributions to the +code base in more detail. -Special notes -------------- - -1. [See also the discussion in the FAQ file - Q2, Q4, and Q5] -Due to what is believed to be a C++ compliance error in VC++ whereby -you may not have multiple handlers for the same exception in the same -try/catch block, if your application contains catch(...) blocks in your POSIX -threads then you will need to replace the "catch(...)" with the macro -"PtW32Catch", eg. +Changes since the last snapshot +------------------------------- +These are now documented in the NEWS file. +See the ChangeLog file also. - #ifdef PtW32Catch - PtW32Catch { - ... - } - #else - catch(...) { - ... - } - #endif -Otherwise neither pthreads cancelation nor pthread_exit() will work -reliably when using versions of the library that use C++ exceptions -for cancelation and thread exit. +Known Bugs +---------- +These are now documented in the BUGS file. Level of standards conformance @@ -436,7 +113,7 @@ The following functions are implemented: pthread_setcancelstate pthread_setcanceltype pthread_testcancel - + --------------------------- Thread Specific Data --------------------------- @@ -444,7 +121,7 @@ The following functions are implemented: pthread_key_delete pthread_setspecific pthread_getspecific - + --------------------------- Mutexes --------------------------- @@ -454,9 +131,9 @@ The following functions are implemented: pthread_mutexattr_setpshared pthread_mutexattr_gettype pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT - PTHREAD_MUTEX_NORMAL - PTHREAD_MUTEX_ERRORCHECK - PTHREAD_MUTEX_RECURSIVE ) + PTHREAD_MUTEX_NORMAL + PTHREAD_MUTEX_ERRORCHECK + PTHREAD_MUTEX_RECURSIVE ) pthread_mutex_init pthread_mutex_destroy pthread_mutex_lock @@ -525,10 +202,10 @@ The following functions are implemented: sem_wait sem_trywait sem_timedwait - sem_open (returns an error ENOSYS) - sem_close (returns an error ENOSYS) - sem_unlink (returns an error ENOSYS) - sem_getvalue (returns an error ENOSYS) + sem_open (returns an error ENOSYS) + sem_close (returns an error ENOSYS) + sem_unlink (returns an error ENOSYS) + sem_getvalue (returns an error ENOSYS) --------------------------- RealTime Scheduling @@ -564,16 +241,16 @@ The following functions are implemented: pthread_timechange_handler_np pthread_delay_np pthread_mutexattr_getkind_np - pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP, - PTHREAD_MUTEX_ERRORCHECK_NP, - PTHREAD_MUTEX_RECURSIVE_NP, - PTHREAD_MUTEX_ADAPTIVE_NP, - PTHREAD_MUTEX_TIMED_NP) + pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP, + PTHREAD_MUTEX_ERRORCHECK_NP, + PTHREAD_MUTEX_RECURSIVE_NP, + PTHREAD_MUTEX_ADAPTIVE_NP, + PTHREAD_MUTEX_TIMED_NP) pthread_num_processors_np - pthread_win32_process_attach_np (Required when statically linking the library) - pthread_win32_process_detach_np (Required when statically linking the library) - pthread_win32_thread_attach_np (Required when statically linking the library) - pthread_win32_thread_detach_np (Required when statically linking the library) + pthread_win32_process_attach_np (Required when statically linking the library) + pthread_win32_process_detach_np (Required when statically linking the library) + pthread_win32_thread_attach_np (Required when statically linking the library) + pthread_win32_thread_detach_np (Required when statically linking the library) --------------------------- Static Initializers @@ -606,7 +283,7 @@ The following functions are not implemented: pthread_mutex_attr_getprotocol pthread_mutex_attr_setprioceiling pthread_mutex_attr_setprotocol - + --------------------------- Fork Handlers --------------------------- @@ -619,7 +296,7 @@ The following functions are not implemented: ftrylockfile funlockfile getc_unlocked - getchar_unlocked + getchar_unlocked putc_unlocked putchar_unlocked @@ -675,7 +352,7 @@ Mailing List There is a mailing list for discussing pthreads on Win32. To join, send email to: - pthreads-win32-subscribe@sourceware.cygnus.com + pthreads-win32-subscribe@sourceware.cygnus.com Application Development Environments @@ -690,7 +367,7 @@ MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your applicatio Mingw32: -See FAQ Questions 6 and 10. +See the FAQ, Questions 6 and 10. Mingw using C++ EH works. Distribute pthreadGCE.dll with your application. Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application. @@ -712,7 +389,7 @@ For convenience, the following pre-built files are available on the FTP site pthread.h - for POSIX 1c threads semaphore.h - for POSIX 1b semaphores - sched.h - for POSIX 1b scheduling + sched.h - for POSIX 1b scheduling pthreadVCE.dll - built with MSVC++ compiler using C++ EH pthreadVCE.lib pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp @@ -721,62 +398,45 @@ For convenience, the following pre-built files are available on the FTP site pthreadVSE.lib pthreadGCE.dll - built with Mingw32 G++ 2.95.2-1 pthreadGC.dll - built with Mingw32 GCC 2.95.2-1 using setjmp/longjmp - libpthreadGCE.a - derived from pthreadGCE.dll + libpthreadGCE.a - derived from pthreadGCE.dll libpthreadGC.a - derived from pthreadGC.dll - gcc.dll - needed if distributing applications that use pthreadGCE.dll + gcc.dll - needed if distributing applications that use + pthreadGCE.dll (but see the FAQ Q 10 for the latest + related information) These are the only files you need in order to build POSIX threads applications for Win32 using either MSVC or Mingw32. - + See the FAQ file in the source tree for additional information. Documentation ------------- -Currently, there is no documentation included in the package apart -from the copious comments in the source code. +For the authoritative reference, see the online POSIX +standard reference: + + http://www.UNIX-systems.org/version3/ieee_std.html For POSIX Thread API programming, several reference books are -available: +available: - Programming with POSIX Threads - David R. Butenhof - Addison-Wesley (pub) + Programming with POSIX Threads + David R. Butenhof + Addison-Wesley (pub) - Pthreads Programming - By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell - O'Reilly (pub) + Pthreads Programming + By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell + O'Reilly (pub) On the web: see the links at the bottom of the pthreads-win32 site: - http://sources.redhat.com/pthreads-win32/ - - -Acknowledgements ----------------- - -This library is based substantially on a Win32 pthreads -implementation contributed by John Bossom . - -The implementation of Condition Variables uses algorithms developed -by Alexander Terekhov and Louis Thomas. - -The implementation of POSIX mutexes has been improved by Thomas Pfaff. - -The implementation of read/write locks was contributed by -Aurelio Medina and improved by Alexander Terekhov. - -Many others have contributed significant time and effort to solve critical -problems in order to make the library workable, robust and reliable. + http://sources.redhat.com/pthreads-win32/ -There is also a separate CONTRIBUTORS file. This file and others are -on the web site: + Currently, there is no documentation included in the package apart + from the copious comments in the source code. - http://sources.redhat.com/pthreads-win32 -As much as possible, the ChangeLog file acknowledges contributions to the -code base in more detail. Enjoy! diff --git a/FAQ b/FAQ index 2efc820..9bed82a 100644 --- a/FAQ +++ b/FAQ @@ -1,393 +1,392 @@ - ========================================= - 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 Thread won't block after two calls to mutex_lock - -Q 11 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 exit 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. 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. - -Async cancelation should be in versions post snapshot-1999-11-02 -of pthreads-win32 (currently only for x86 architectures). - -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. - -However ... - -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). Unfortunately, there is no way to do so from -outside the thread. - -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 POSIX -threads standard list doesn't include "select" because (as I read in -Butenhof) it isn't part of POSIX. - -Effectively, the only cancelation points that pthreads-win32 can -recognise are those the library implements itself, ie. - - pthread_testcancel - pthread_cond_wait - pthread_cond_timedwait - pthread_join - sem_wait - pthread_delay_np - -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) - -Regards. -Ross - ------------------------------------------------------------------------------- - - -Q 10 How do I create thread-safe applications using ----- pthreadGCE.dll, libpthreadw32.a and Mingw32? - -See Thomas Pfaff's email at: -http://sources.redhat.com/ml/pthreads-win32/2002/msg00000.html - ------------------------------------------------------------------------------- - + ========================================= + 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 exit 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. 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. + +Async cancelation should be in versions post snapshot-1999-11-02 +of pthreads-win32 (currently only for x86 architectures). + +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. + +However ... + +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). Unfortunately, there is no way to do so from +outside the thread. + +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 POSIX +threads standard list doesn't include "select" because (as I read in +Butenhof) it isn't part of POSIX. + +Effectively, the only cancelation points that pthreads-win32 can +recognise are those the library implements itself, ie. + + pthread_testcancel + pthread_cond_wait + pthread_cond_timedwait + pthread_join + sem_wait + pthread_delay_np + +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) + +Regards. +Ross + +------------------------------------------------------------------------------ + + +Q 10 How do I create thread-safe applications using +---- pthreadGCE.dll, libpthreadw32.a and Mingw32? + +See Thomas Pfaff's email at: +http://sources.redhat.com/ml/pthreads-win32/2002/msg00000.html + +------------------------------------------------------------------------------ + diff --git a/NEWS b/NEWS index 0ba7e58..d4cd9c0 100644 --- a/NEWS +++ b/NEWS @@ -1,118 +1,364 @@ -SNAPSHOT 2000-08-13 -------------------- - -New: -- Renamed DLL and LIB files: - pthreadVSE.dll (MS VC++/Structured EH) - pthreadVSE.lib - pthreadVCE.dll (MS VC++/C++ EH) - pthreadVCE.lib - pthreadGCE.dll (GNU G++/C++ EH) - libpthreadw32.a - - Both your application and the pthread dll should use the - same exception handling scheme. - -Bugs fixed: -- MSVC++ C++ exception handling. - -Some new tests have been added. - - -SNAPSHOT 2000-08-10 -------------------- - -New: -- asynchronous cancelation on X86 (Jason Nye) -- Makefile compatible with MS nmake to replace - buildlib.bat -- GNUmakefile for Mingw32 -- tests/Makefile for MS nmake replaces runall.bat -- tests/GNUmakefile for Mingw32 - -Bugs fixed: -- kernel32 load/free problem -- attempt to hide internel exceptions from application - exception handlers (__try/__except and try/catch blocks) -- Win32 thread handle leakage bug - (David Baggett/Paul Redondo/Eyal Lebedinsky) - -Some new tests have been added. - - -SNAPSHOT 1999-11-02 -------------------- - -Bugs fixed: -- ctime_r macro had an incorrect argument (Erik Hensema), -- threads were not being created - PTHREAD_CANCEL_DEFERRED. This should have - had little effect as deferred is the only - supported type. (Ross Johnson). - -Some compatibility improvements added, eg. -- pthread_setcancelstate accepts NULL pointer - for the previous value argument. Ditto for - pthread_setcanceltype. This is compatible - with Solaris but should not affect - standard applications (Erik Hensema) - -Some new tests have been added. - - -SNAPSHOT 1999-10-17 -------------------- - -Bug fix - Cancelation of threads waiting on condition variables -now works properly (Lorin Hochstein and Peter Slacik) - - -SNAPSHOT 1999-08-12 -------------------- - -Fixed exception stack cleanup if calling pthread_exit() -- (Lorin Hochstein and John Bossom). - -Fixed bugs in condition variables - (Peter Slacik): - - additional contention checks - - properly adjust number of waiting threads after timed - condvar timeout. - - -SNAPSHOT 1999-05-30 -------------------- - -Some minor bugs have been fixed. See the ChangeLog file for details. - -Some more POSIX 1b functions are now included but ony return an -error (ENOSYS) if called. They are: - - sem_open - sem_close - sem_unlink - sem_getvalue - - -SNAPSHOT 1999-04-07 -------------------- - -Some POSIX 1b functions which were internally supported are now -available as exported functions: - - sem_init - sem_destroy - sem_wait - sem_trywait - sem_post - sched_yield - sched_get_priority_min - sched_get_priority_max - -Some minor bugs have been fixed. See the ChangeLog file for details. - - -SNAPSHOT 1999-03-16 -------------------- - -Initial release. - +SNAPSHOT 2002-03-02 +------------------- + +Cleanup code default style. (IMPORTANT) +---------------------------------------------------------------------- +Previously, if not defined, the cleanup style was determined automatically +from the compiler/language, 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(). + +In this and future snapshots, unless the 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 +current commercial Unix POSIX threads implementations. Compaq's TRU64 +may be an exception (no pun intended) and possible future trend. + +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 + +E.g. regardless of whether your app is C or C++, if you link with +pthreadVC.lib or libpthreadGC.a, then you must define __CLEANUP_C. + + +THE POINT OF ALL THIS IS: if you have not been defining one of these +explicitly, then the defaults as described at the top of this +section were being used. + +THIS NOW CHANGES, as has been explained above, but to try to make this +clearer here's an example: + +If you were building your application with MSVC++ i.e. using C++ +exceptions and not explicitly defining one of __CLEANUP_*, then +__CLEANUP_C++ was automatically 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 +automatically 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, or 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 locally +instantiated 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. + + +WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY? +Because no commercial Unix POSIX threads implementation allows you to +choose to have stack unwinding. Therefore, providing it in pthread-win32 +as a default is dangerous. We still provide the choice but unless +you consciously choose to do otherwise, your pthreads applications will +now run or crash in similar ways irrespective of the threads platform +you use. Or at least this is the hope. + + +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, for unconditional conformity to other implementations.) +- 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. + + +Source module splitting +----------------------- +In order to enable smaller image sizes to be generated +for applications that link statically with the library, +most routines have been separated out into individual +source code files. + +This is being done in such a way as to be backward compatible. +The old source files are reused to congregate the individual +routine files into larger translation units (via a bunch of +# includes) so that the compiler can still optimise wherever +possible, e.g. through inlining, which can only be done +within the same translation unit. + +It is also possible to build the entire library by compiling +the single file named "pthread.c", which just #includes all +the secondary congregation source files. The compiler +may be able to use this to do more inlining of routines. + +Although the GNU compiler is able to produce libraries with +the necessary separation (the -ffunction-segments switch), +AFAIK, the MSVC and other compilers don't have this feature. + +Finally, since I use makefiles and command-line compilation, +I don't know what havoc this reorganisation may wreak amongst +IDE project file users. You should be able to continue +using your existing project files without modification. + + +New non-portable functions +-------------------------- +pthread_num_processors_np(): + Returns the number of processors in the system that are + available to the process, as determined from the processor + affinity mask. + +pthread_timechange_handler_np(): + 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. + - Suggested by Alexander Terekhov + + +Platform dependence +------------------- +As Win95 doesn't provide one, the library now contains +it's own InterlockedCompareExchange() routine, which is used +whenever Windows doesn't provide it. InterlockedCompareExchange() +is used to implement spinlocks and barriers, and also in mutexes. +This routine relies on the CMPXCHG machine instruction which +is not available on i386 CPUs. This library (from snapshot +20010712 onwards) is therefore no longer supported on i386 +processor platforms. + + +New standard routines +--------------------- +For source code portability only - rwlocks cannot be process shared yet. + + pthread_rwlockattr_init() + pthread_rwlockattr_destroy() + pthread_rwlockattr_setpshared() + pthread_rwlockattr_getpshared() + +As defined in the new POSIX standard, and the Single Unix Spec version 3: + + sem_timedwait() + pthread_mutex_timedlock() - Alexander Terekhov and Thomas Pfaff + pthread_rwlock_timedrdlock() - adapted from pthread_rwlock_rdlock() + pthread_rwlock_timedwrlock() - adapted from pthread_rwlock_wrlock() + + +pthread.h no longer includes windows.h +-------------------------------------- +[Not yet for G++] + +This was done to prevent conflicts. + +HANDLE, DWORD, and NULL are temporarily defined within pthread.h if +they are not already. + + +pthread.h, sched.h and semaphore.h now use dllexport/dllimport +-------------------------------------------------------------- +Not only to avoid the need for the pthread.def file, but to +improve performance. Apparently, declaring functions with dllimport +generates a direct call to the function and avoids the overhead +of a stub function call. + +Bug fixes +--------- +* Fixed potential NULL pointer dereferences in pthread_mutexattr_init, +pthread_mutexattr_getpshared, pthread_barrierattr_init, +pthread_barrierattr_getpshared, and pthread_condattr_getpshared. +- Scott McCaskill + +* Removed potential race condition in pthread_mutex_trylock and +pthread_mutex_lock; +- Alexander Terekhov + +* The behaviour of pthread_mutex_trylock in relation to +recursive mutexes was inconsistent with commercial implementations. +Trylock would return EBUSY if the lock was owned already by the +calling thread regardless of mutex type. Trylock now increments the +recursion count and returns 0 for RECURSIVE mutexes, and will +return EDEADLK rather than EBUSY for ERRORCHECK mutexes. This is +consistent with Solaris. +- Thomas Pfaff + +* Found a fix for the library and workaround for applications for +the known bug #2, i.e. where __CLEANUP_CXX or __CLEANUP_SEH is defined. +See the "Known Bugs in this snapshot" section below. + +This could be made transparent to applications by replacing the macros that +define the current C++ and SEH versions of pthread_cleanup_push/pop +with the C version, but AFAIK cleanup handlers would not then run in the +correct sequence with destructors and exception cleanup handlers when +an exception occurs. + +* Cancelation once started in a thread cannot now be inadvertantly +double canceled. That is, once a thread begins it's cancelation run, +cancelation is disabled and a subsequent cancel request will +return an error (ESRCH). + +* errno: An incorrect compiler directive caused a local version +of errno to be used instead of the Win32 errno. Both instances are +thread-safe but applications checking errno after a pthreads-win32 +call would be wrong. Fixing this also fixed a bad compiler +option in the testsuite (/MT should have been /MD) which is +needed to link with the correct library MSVCRT.LIB. + + +SNAPSHOT 2001-07-12 +------------------- + +To be added + + +SNAPSHOT 2001-07-03 +------------------- + +To be added + + +SNAPSHOT 2000-08-13 +------------------- + +New: +- Renamed DLL and LIB files: + pthreadVSE.dll (MS VC++/Structured EH) + pthreadVSE.lib + pthreadVCE.dll (MS VC++/C++ EH) + pthreadVCE.lib + pthreadGCE.dll (GNU G++/C++ EH) + libpthreadw32.a + + Both your application and the pthread dll should use the + same exception handling scheme. + +Bugs fixed: +- MSVC++ C++ exception handling. + +Some new tests have been added. + + +SNAPSHOT 2000-08-10 +------------------- + +New: +- asynchronous cancelation on X86 (Jason Nye) +- Makefile compatible with MS nmake to replace + buildlib.bat +- GNUmakefile for Mingw32 +- tests/Makefile for MS nmake replaces runall.bat +- tests/GNUmakefile for Mingw32 + +Bugs fixed: +- kernel32 load/free problem +- attempt to hide internel exceptions from application + exception handlers (__try/__except and try/catch blocks) +- Win32 thread handle leakage bug + (David Baggett/Paul Redondo/Eyal Lebedinsky) + +Some new tests have been added. + + +SNAPSHOT 1999-11-02 +------------------- + +Bugs fixed: +- ctime_r macro had an incorrect argument (Erik Hensema), +- threads were not being created + PTHREAD_CANCEL_DEFERRED. This should have + had little effect as deferred is the only + supported type. (Ross Johnson). + +Some compatibility improvements added, eg. +- pthread_setcancelstate accepts NULL pointer + for the previous value argument. Ditto for + pthread_setcanceltype. This is compatible + with Solaris but should not affect + standard applications (Erik Hensema) + +Some new tests have been added. + + +SNAPSHOT 1999-10-17 +------------------- + +Bug fix - Cancelation of threads waiting on condition variables +now works properly (Lorin Hochstein and Peter Slacik) + + +SNAPSHOT 1999-08-12 +------------------- + +Fixed exception stack cleanup if calling pthread_exit() +- (Lorin Hochstein and John Bossom). + +Fixed bugs in condition variables - (Peter Slacik): + - additional contention checks + - properly adjust number of waiting threads after timed + condvar timeout. + + +SNAPSHOT 1999-05-30 +------------------- + +Some minor bugs have been fixed. See the ChangeLog file for details. + +Some more POSIX 1b functions are now included but ony return an +error (ENOSYS) if called. They are: + + sem_open + sem_close + sem_unlink + sem_getvalue + + +SNAPSHOT 1999-04-07 +------------------- + +Some POSIX 1b functions which were internally supported are now +available as exported functions: + + sem_init + sem_destroy + sem_wait + sem_trywait + sem_post + sched_yield + sched_get_priority_min + sched_get_priority_max + +Some minor bugs have been fixed. See the ChangeLog file for details. + + +SNAPSHOT 1999-03-16 +------------------- + +Initial release. + diff --git a/PROGRESS b/PROGRESS index 230e76a..3e90bec 100644 --- a/PROGRESS +++ b/PROGRESS @@ -1,4 +1,4 @@ -Please see the ANNOUNCE file "Level of Standards Conformance" -or the web page: - -http://sourceware.cygnus.com/pthreads-win32/conformance.html +Please see the ANNOUNCE file "Level of Standards Conformance" +or the web page: + +http://sources.redhat.com/pthreads-win32/conformance.html diff --git a/README b/README index b4e0288..1e49e74 100644 --- a/README +++ b/README @@ -1,419 +1,451 @@ -PTHREADS-WIN32 -============== - -Pthreads-win32 is free software, distributed under the GNU Lesser -General Public License (LGPL). See the file 'COPYING.LIB' for terms -and conditions. Also see the file 'COPYING' for information -specific to pthreads-win32, copyrights and the LGPL. - - -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. - - -Which of the several dll versions to 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 exit 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. - - -Library naming --------------- - -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 - - -Other name changes ------------------- - -All snapshots prior to and including snapshot 2000-08-13 -used "_pthread_" as the prefix to library internal -functions, and "_PTHREAD_" to many library internal -macros. These have now been changed to "ptw32_" and "PTW32_" -respectively so as to not conflict with the ANSI standard's -reservation of identifiers beginning with "_" and "__" for -use by compiler implementations only. - -If you have written any applications and you are linking -statically with the pthreads-win32 library then you may have -included a call to _pthread_processInitialize. You will -now have to change that to ptw32_processInitialize. - - -A note on Cleanup code default style ------------------------------------- - -Previously, 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(). - -In this snapshot, unless the 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 as described at the top of this -section were being used. - -THIS NOW CHANGES, as has been explained above, but to try to make this -clearer here's an 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, or 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 locally -instantiated 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. - - -WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY? -Because no commercial Unix POSIX threads implementation allows you to -choose to have stack unwinding. Therefore, providing it in pthread-win32 -as a default is dangerous. We still provide the choice but unless -you consciously choose to do otherwise, your pthreads applications will -now run or crash in similar ways irrespective of the threads platform -you use. Or at least this is the hope. - - - -Building under VC++ using C++ EH, Structured EH, or just C ----------------------------------------------------------- - -From the source directory run one of the following: - -nmake clean VCE (builds the VC++ C++ EH version pthreadVCE.dll) - -or: - -nmake clean VSE (builds the VC++ structured EH version pthreadVSE.dll) - -or: - -nmake clean VC (builds the VC setjmp/longjmp version of pthreadVC.dll) - -You can run the testsuite by changing to the "tests" directory and -running the target corresponding to the DLL version you built: - -nmake clean VCE - -or: - -nmake clean VSE - -or: - -nmake clean VC - -or: - -nmake clean VCX (tests the VC version of the library with C++ (EH) - applications) - - -Building under Mingw32 ----------------------- - -The dll can be built with Mingw32 gcc-2.95.2-1 after you've -made the changes to Mingw32 desribed in Question 6 of the FAQ. - -From the source directory, run - -make clean GCE - -or: - -make clean GC - -You can run the testsuite by changing to the "tests" directory and -running - -make clean GCE - -or: - -make clean GC - -or: - -make clean GCX (tests the GC version of the library with C++ (EH) - applications) - - -Building the library under Cygwin ---------------------------------- - -Not tested by me although I think some people have done this. -Not sure how successfully though. - -Cygwin is implementing it's own POSIX threads routines and these -will be the ones to use if you develop using Cygwin. - - -Ready to run binaries ---------------------- - -For convenience, the following ready-to-run files can be downloaded -from the FTP site (see under "Availability" below): - - pthread.h - semaphore.h - sched.h - pthread.def - pthreadVCE.dll - built with MSVC++ compiler using C++ EH - pthreadVCE.lib - pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp - pthreadVC.lib - pthreadVSE.dll - built with MSVC compiler using SEH - pthreadVSE.lib - pthreadGCE.dll - built with Mingw32 G++ - pthreadGCE.a - derived from pthreadGCE.dll - pthreadGC.dll - built with Mingw32 GCC - pthreadGC.a - derived from pthreadGC.dll - gcc.dll - needed to build and run applications that use - pthreadGCE.dll. - - -Building applications with the library --------------------------------------- - -Use the appropriate DLL and LIB files to match the exception handing -that you use in your application, or specifically, in your POSIX -threads. Don't mix them or neither thread cancelation nor -pthread_exit() will work reliably if at all. - -If in doubt use the C (no-exceptions) versions of the library. - - -Building applications with GNU compilers ----------------------------------------- - -If you're using pthreadGCE.dll: - -Use gcc-2.95.2-1 or later modified as per pthreads-win32 FAQ question 11. - -With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a -in the same directory as your application myapp.c, you could compile, -link and run myapp.c under Mingw32 as follows: - - gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE - myapp - -Or put pthreadGCE.dll and gcc.dll in an appropriate directory in -your PATH, put libpthreadGCE.a in MINGW_ROOT\i386-mingw32\lib, and -put the three header files in MINGW_ROOT\i386-mingw32\include, -then use: - - gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE - myapp - -If you're using pthreadGC.dll: - -With the three header files, pthreadGC.dll and libpthreadGC.a in the -same directory as your application myapp.c, you could compile, link -and run myapp.c under Mingw32 as follows: - - gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC - myapp - -Or put pthreadGC.dll in an appropriate directory in your PATH, -put libpthreadGC.a in MINGW_ROOT\i386-mingw32\lib, and -put the three header files in MINGW_ROOT\i386-mingw32\include, -then use: - - gcc -o myapp.exe myapp.c -lpthreadGC - myapp - - -Availability ------------- - -The complete source code in either unbundled, self-extracting -Zip file, or tar/gzipped format can be found at: - - ftp://sources.redhat.com/pub/pthreads-win32 - -The pre-built DLL, export libraries and matching pthread.h can -be found at: - - ftp://sources.redhat.com/pub/pthreads-win32/dll-latest - -Home page: - - http://sources.redhat.com/pthreads-win32/ - - -Mailing list ------------- - -There is a mailing list for discussing pthreads on Win32. -To join, send email to: - - pthreads-win32-subscribe@sources.redhat.com - -Unsubscribe by sending mail to: - - pthreads-win32-unsubscribe@sources.redhat.com - - -Acknowledgements ----------------- - -Pthreads-win32 is based substantially on a Win32 Pthreads -implementation contributed by John E. Bossom. -Many others have contributed important new code, -improvements and bug fixes. Thanks go to Alexander Terekhov -and Louis Thomas for their improvements to the implementation -of condition variables. - -See the 'CONTRIBUTORS' file for the list of contributors. - -As much as possible, the ChangeLog file also attributes -contributions and patches that have been incorporated -in the library. - ----- -Ross Johnson - - - - - - - - - +PTHREADS-WIN32 +============== + +Pthreads-win32 is free software, distributed under the GNU Lesser +General Public License (LGPL). See the file 'COPYING.LIB' for terms +and conditions. Also see the file 'COPYING' for information +specific to pthreads-win32, copyrights and the LGPL. + + +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. + + +Which of the several dll versions to 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 exit 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. + +Finally, for a proper version of the library with no internal +exceptions to be usable with C++ applications, the C version +should compiled as C++ so that it knows about and can propagate +exceptions even if it doesn't use C++ features. + + +Notes: + +[If you use either pthreadVCE or pthreadGCE] + +1. [See also the discussion in the FAQ file - Q2, Q4, and Q5] + +Due to what is believed to be a C++ compliance error in VC++ whereby +you may not have multiple handlers for the same exception in the same +try/catch block, if your application contains catch(...) blocks in your POSIX +threads then you will need to replace the "catch(...)" with the macro +"PtW32Catch", eg. + + #ifdef PtW32Catch + PtW32Catch { + ... + } + #else + catch(...) { + ... + } + #endif + +Otherwise neither pthreads cancelation nor pthread_exit() will work +reliably when using versions of the library that use C++ exceptions +for cancelation and thread exit. + + +Library naming +-------------- + +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 + + +Other name changes +------------------ + +All snapshots prior to and including snapshot 2000-08-13 +used "_pthread_" as the prefix to library internal +functions, and "_PTHREAD_" to many library internal +macros. These have now been changed to "ptw32_" and "PTW32_" +respectively so as to not conflict with the ANSI standard's +reservation of identifiers beginning with "_" and "__" for +use by compiler implementations only. + +If you have written any applications and you are linking +statically with the pthreads-win32 library then you may have +included a call to _pthread_processInitialize. You will +now have to change that to ptw32_processInitialize. + + +A note on Cleanup code default style +------------------------------------ + +Previously, 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(). + +In this snapshot, unless the 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 as described at the top of this +section were being used. + +THIS NOW CHANGES, as has been explained above, but to try to make this +clearer here's an 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, or 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 locally +instantiated 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. + + +WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY? +Because no commercial Unix POSIX threads implementation allows you to +choose to have stack unwinding. Therefore, providing it in pthread-win32 +as a default is dangerous. We still provide the choice but unless +you consciously choose to do otherwise, your pthreads applications will +now run or crash in similar ways irrespective of the threads platform +you use. Or at least this is the hope. + + + +Building under VC++ using C++ EH, Structured EH, or just C +---------------------------------------------------------- + +From the source directory run one of the following: + +nmake clean VCE (builds the VC++ C++ EH version pthreadVCE.dll) + +or: + +nmake clean VSE (builds the VC++ structured EH version pthreadVSE.dll) + +or: + +nmake clean VC (builds the VC setjmp/longjmp version of pthreadVC.dll) + +You can run the testsuite by changing to the "tests" directory and +running the target corresponding to the DLL version you built: + +nmake clean VCE + +or: + +nmake clean VSE + +or: + +nmake clean VC + +or: + +nmake clean VCX (tests the VC version of the library with C++ (EH) + applications) + + +Building under Mingw32 +---------------------- + +The dll can be built with Mingw32 gcc-2.95.2-1 after you've +made the changes to Mingw32 desribed in Question 6 of the FAQ. + +From the source directory, run + +make clean GCE + +or: + +make clean GC + +You can run the testsuite by changing to the "tests" directory and +running + +make clean GCE + +or: + +make clean GC + +or: + +make clean GCX (tests the GC version of the library with C++ (EH) + applications) + + +Building the library under Cygwin +--------------------------------- + +Not tested by me although I think some people have done this. +Not sure how successfully though. + +Cygwin is implementing it's own POSIX threads routines and these +will be the ones to use if you develop using Cygwin. + + +Ready to run binaries +--------------------- + +For convenience, the following ready-to-run files can be downloaded +from the FTP site (see under "Availability" below): + + pthread.h + semaphore.h + sched.h + pthread.def + pthreadVCE.dll - built with MSVC++ compiler using C++ EH + pthreadVCE.lib + pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp + pthreadVC.lib + pthreadVSE.dll - built with MSVC compiler using SEH + pthreadVSE.lib + pthreadGCE.dll - built with Mingw32 G++ + pthreadGCE.a - derived from pthreadGCE.dll + pthreadGC.dll - built with Mingw32 GCC + pthreadGC.a - derived from pthreadGC.dll + gcc.dll - needed to build and run applications that use + pthreadGCE.dll. + + +Building applications with the library +-------------------------------------- + +Use the appropriate DLL and LIB files to match the exception handing +that you use in your application, or specifically, in your POSIX +threads. Don't mix them or neither thread cancelation nor +pthread_exit() will work reliably if at all. + +If in doubt use the C (no-exceptions) versions of the library. + + +Building applications with GNU compilers +---------------------------------------- + +If you're using pthreadGCE.dll: + +Use gcc-2.95.2-1 or later modified as per pthreads-win32 FAQ question 11. + +With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a +in the same directory as your application myapp.c, you could compile, +link and run myapp.c under Mingw32 as follows: + + gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE + myapp + +Or put pthreadGCE.dll and gcc.dll in an appropriate directory in +your PATH, put libpthreadGCE.a in MINGW_ROOT\i386-mingw32\lib, and +put the three header files in MINGW_ROOT\i386-mingw32\include, +then use: + + gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE + myapp + +If you're using pthreadGC.dll: + +With the three header files, pthreadGC.dll and libpthreadGC.a in the +same directory as your application myapp.c, you could compile, link +and run myapp.c under Mingw32 as follows: + + gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC + myapp + +Or put pthreadGC.dll in an appropriate directory in your PATH, +put libpthreadGC.a in MINGW_ROOT\i386-mingw32\lib, and +put the three header files in MINGW_ROOT\i386-mingw32\include, +then use: + + gcc -o myapp.exe myapp.c -lpthreadGC + myapp + + +Availability +------------ + +The complete source code in either unbundled, self-extracting +Zip file, or tar/gzipped format can be found at: + + ftp://sources.redhat.com/pub/pthreads-win32 + +The pre-built DLL, export libraries and matching pthread.h can +be found at: + + ftp://sources.redhat.com/pub/pthreads-win32/dll-latest + +Home page: + + http://sources.redhat.com/pthreads-win32/ + + +Mailing list +------------ + +There is a mailing list for discussing pthreads on Win32. +To join, send email to: + + pthreads-win32-subscribe@sources.redhat.com + +Unsubscribe by sending mail to: + + pthreads-win32-unsubscribe@sources.redhat.com + + +Acknowledgements +---------------- + +Pthreads-win32 is based substantially on a Win32 Pthreads +implementation contributed by John E. Bossom. +Many others have contributed important new code, +improvements and bug fixes. Thanks go to Alexander Terekhov +and Louis Thomas for their improvements to the implementation +of condition variables. + +See the 'CONTRIBUTORS' file for the list of contributors. + +As much as possible, the ChangeLog file also attributes +contributions and patches that have been incorporated +in the library. + +---- +Ross Johnson + + + + + + + + + diff --git a/TODO b/TODO index f0e11bf..f798e76 100644 --- a/TODO +++ b/TODO @@ -1,7 +1,7 @@ - Things that should be doable but aren't yet - ------------------------------------------- - -1. Implement PTHREAD_PROCESS_SHARED for semaphores, mutexes, - condition variables, read/write locks, barriers. - - + Things that aren't done yet + --------------------------- + +1. Implement PTHREAD_PROCESS_SHARED for semaphores, mutexes, + condition variables, read/write locks, barriers. + + diff --git a/tests/GNUmakefile b/tests/GNUmakefile index 9a0902e..cdae2d9 100644 --- a/tests/GNUmakefile +++ b/tests/GNUmakefile @@ -83,8 +83,7 @@ TESTS = loadfree \ priority1 priority2 inherit1 \ spin1 spin2 spin3 spin4 \ barrier1 barrier2 barrier3 barrier4 barrier5 \ - exception1 exception2 exception3 \ - exit4 + exception1 exception2 exception3 BENCHTESTS = \ benchtest1 benchtest2 benchtest3 benchtest4 benchtest5 @@ -177,7 +176,6 @@ exception3.pass: exception2.pass exit1.pass: exit2.pass: create1.pass exit3.pass: create1.pass -exit4.pass: exit3.pass eyal1.pass: tsd1.pass inherit1.pass: join1.pass join0.pass: create1.pass diff --git a/tests/Makefile b/tests/Makefile index f684f31..a3fa7f3 100644 --- a/tests/Makefile +++ b/tests/Makefile @@ -57,7 +57,7 @@ VCDLL = pthreadVC.dll # C++ Exceptions in application - using VC version of pthreads dll VCXFLAGS = /GX /TP /D__CLEANUP_C -CFLAGS= $(OPTIM) /W3 /WX /MT /nologo /Yd /Zi -D_WIN32_WINNT=0x400 +CFLAGS= $(OPTIM) /W3 /WX /MD /nologo /Yd /Zi -D_WIN32_WINNT=0x400 LFLAGS= /INCREMENTAL:NO INCLUDES=-I. BUILD_DIR=.. @@ -96,8 +96,7 @@ PASSES= loadfree.pass \ priority1.pass priority2.pass inherit1.pass \ spin1.pass spin2.pass spin3.pass spin4.pass \ barrier1.pass barrier2.pass barrier3.pass barrier4.pass barrier5.pass \ - exception1.pass exception2.pass exception3.pass \ - exit4 + exception1.pass exception2.pass exception3.pass BENCHRESULTS = \ benchtest1.bench benchtest2.bench benchtest3.bench benchtest4.bench benchtest5.bench @@ -243,7 +242,6 @@ exception3.pass: exception2.pass exit1.pass: exit2.pass: create1.pass exit3.pass: create1.pass -exit4.pass: exit3.pass eyal1.pass: tsd1.pass inherit1.pass: join1.pass join0.pass: create1.pass diff --git a/tests/exit4.c b/tests/exit4.c deleted file mode 100644 index 480fc2e..0000000 --- a/tests/exit4.c +++ /dev/null @@ -1,104 +0,0 @@ -/* - * Test for pthread_exit(). - * - * -------------------------------------------------------------------------- - * - * Pthreads-win32 - POSIX Threads Library for Win32 - * Copyright(C) 1998 John E. Bossom - * Copyright(C) 1999,2002 Pthreads-win32 contributors - * - * Contact Email: rpj@ise.canberra.edu.au - * - * The current list of contributors is contained - * in the file CONTRIBUTORS included with the source - * code distribution. The list can also be seen at the - * following World Wide Web location: - * http://sources.redhat.com/pthreads-win32/contributors.html - * - * This library is free software; you can redistribute it and/or - * modify it under the terms of the GNU Lesser General Public - * License as published by the Free Software Foundation; either - * version 2 of the License, or (at your option) any later version. - * - * This library is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this library in the file COPYING.LIB; - * if not, write to the Free Software Foundation, Inc., - * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA - * - * -------------------------------------------------------------------------- - * - * Depends on API functions: pthread_create(). - */ - -#include "test.h" - -#ifdef __CLEANUP_CXX - -#define USE_PTHREAD_EXIT -static const int init_counter_value = 3; -static void *ret_value = reinterpret_cast(1); -static int counter = init_counter_value; - -class Guard -{ - const char * const _str; - int &_ref; - Guard &operator=(const Guard&); - Guard(const Guard&); -public: - Guard(const char * const str, int &ref) : _str(str), _ref(ref) { - printf("Construct %s [%d->%d]\n", _str, _ref, _ref+++1); - }; - ~Guard() { - printf("~Destruct %s [%d->%d]\n", _str, _ref, _ref---1); - }; -}; - - -void * -func(void * arg) -{ - Guard g("func", counter); - -#ifdef USE_PTHREAD_EXIT - - pthread_exit(arg); - assert(0); //Never reached with pthread_exit - -#endif //USE_PTHREAD_EXIT - - return ret_value; -} - - -#endif /*__CLEANUP_CXX */ - -int -main() -{ -#ifndef __CLEANUP_CXX - - printf("Test requires C++ cleanup enabled. Skipped.\n"); - -#else - - { - void *ret = 0; - Guard g("main", counter); - pthread_t id; - assert(0 == pthread_create(&id, 0, func, ret_value)); - assert(0 == pthread_join(id, &ret)); - assert(ret == ret_value); - } - - assert(counter == init_counter_value); - -#endif /*__CLEANUP_CXX */ - - return 0; -} -- cgit v1.2.3