diff options
| author | rpj <rpj> | 2002-03-02 05:00:44 +0000 |
|---|---|---|
| committer | rpj <rpj> | 2002-03-02 05:00:44 +0000 |
| commit | d14156f2c1d4a9db64cfef0370883db8930e3a6b (patch) | |
| tree | 6bf37a058dd96f906c6422e48f23710ef532bc4e | |
| parent | 44c245b3ed9e82cc44a5ade4a941c99f63174021 (diff) | |
Changes to documentation and makefiles.
| -rw-r--r-- | ANNOUNCE | 490 | ||||
| -rw-r--r-- | FAQ | 785 | ||||
| -rw-r--r-- | NEWS | 482 | ||||
| -rw-r--r-- | PROGRESS | 8 | ||||
| -rw-r--r-- | README | 870 | ||||
| -rw-r--r-- | TODO | 14 | ||||
| -rw-r--r-- | tests/GNUmakefile | 4 | ||||
| -rw-r--r-- | tests/Makefile | 6 | ||||
| -rw-r--r-- | tests/exit4.c | 104 |
9 files changed, 1296 insertions, 1467 deletions
@@ -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 <rpj@ise.canberra.edu.au>
+ 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 <rpj@ise.canberra.edu.au>
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 <John.Bossom@cognos.com>.
-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 <scott@magruder.org>
-
-* Removed potential race condition in pthread_mutex_trylock and
-pthread_mutex_lock;
-- Alexander Terekhov <TEREKHOV@de.ibm.com>
-
-* 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 <tpfaff@gmx.net>
-
-* 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 <John.Bossom@cognos.com>.
-
-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!
@@ -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
+
+------------------------------------------------------------------------------
+
@@ -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 <scott@magruder.org>
+
+* Removed potential race condition in pthread_mutex_trylock and
+pthread_mutex_lock;
+- Alexander Terekhov <TEREKHOV@de.ibm.com>
+
+* 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 <tpfaff@gmx.net>
+
+* 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.
+
@@ -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
@@ -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 -<rpj@ise.canberra.edu.au> - - - - - - - - +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
+<rpj@ise.canberra.edu.au>
+
+
+
+
+
+
+
+
@@ -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<void *>(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; -} |