Splitting files. See ChangeLog file for details.

1 files changed, 730 insertions, 730 deletions

diff --git a/ANNOUNCE b/ANNOUNCE
index 6141400..4a238d8 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -1,730 +1,730 @@
-                 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>

-

-

-We are pleased to announce the availability of a new snapshot of

-Pthreads-win32, 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.

-

-Parts of the implementation also comply with the Open Group's

-Single Unix specification for compatibility with major Unix

-implementations and Linux.

-

-Pthreads-win32 is free software, distributed under the GNU Lesser

-General Public License (LGPL).

-

-Please see the 'Acknowledgements' section at the end of this

-announcement for the list of contributors.

-

-

--------------------------------

-Changes since the last snapshot

--------------------------------

-

-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 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()

-

-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.

-

-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

-   for some reason. The code in private.c ptw32_threadStart()

-   retrieves and calls the user supplied terminate routine, which

-   works as expected under MinGW32 g++, but doesn't run under

-   MS VC++ 6.0, presumably because set_terminate() returns NULL.

-

-2. Cancellation problems in optimised code

-   - Milan Gardian

-

-   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 () 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)

-

-   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.

-

-

-Caveats

--------

-

-1. Due to what is believed to be a C++ compliance error in VC++,

-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.

-

-

-Level of standards conformance

-------------------------------

-

-The following POSIX 1003.1c/1b/1j options are defined:

-

-      _POSIX_THREADS

-      _POSIX_THREAD_SAFE_FUNCTIONS

-      _POSIX_THREAD_ATTR_STACKSIZE

-      _POSIX_THREAD_PRIORITY_SCHEDULING

-      _POSIX_SEMAPHORES

-      _POSIX_READER_WRITER_LOCKS

-      _POSIX_SPIN_LOCKS

-      _POSIX_BARRIERS

-

-

-The following POSIX 1003.1c options are not defined:

-

-      _POSIX_THREAD_ATTR_STACKADDR

-      _POSIX_THREAD_PRIO_INHERIT

-      _POSIX_THREAD_PRIO_PROTECT

-      _POSIX_THREAD_PROCESS_SHARED

-

-

-The following functions are implemented:

-

-      ---------------------------

-      PThreads

-      ---------------------------

-      pthread_attr_init

-      pthread_attr_destroy

-      pthread_attr_getdetachstate

-      pthread_attr_getstackaddr

-      pthread_attr_getstacksize

-      pthread_attr_setdetachstate

-      pthread_attr_setstackaddr

-      pthread_attr_setstacksize

-

-      pthread_create

-      pthread_detach

-      pthread_equal

-      pthread_exit

-      pthread_join

-      pthread_once

-      pthread_self

-

-      pthread_cancel

-      pthread_cleanup_pop

-      pthread_cleanup_push

-      pthread_setcancelstate

-      pthread_setcanceltype

-      pthread_testcancel

-          

-      ---------------------------

-      Thread Specific Data   

-      ---------------------------

-      pthread_key_create

-      pthread_key_delete

-      pthread_setspecific

-      pthread_getspecific

-                

-      ---------------------------

-      Mutexes

-      ---------------------------

-      pthread_mutexattr_init

-      pthread_mutexattr_destroy

-      pthread_mutexattr_getpshared

-      pthread_mutexattr_setpshared

-      pthread_mutexattr_gettype

-      pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT

-                                        PTHREAD_MUTEX_NORMAL

-                                        PTHREAD_MUTEX_ERRORCHECK

-                                        PTHREAD_MUTEX_RECURSIVE  )

-      pthread_mutex_init

-      pthread_mutex_destroy

-      pthread_mutex_lock

-      pthread_mutex_trylock

-      pthread_mutex_timedlock

-      pthread_mutex_unlock

-

-      ---------------------------

-      Condition Variables

-      ---------------------------

-      pthread_condattr_init

-      pthread_condattr_destroy

-      pthread_condattr_getpshared

-      pthread_condattr_setpshared

-

-      pthread_cond_init

-      pthread_cond_destroy

-      pthread_cond_wait

-      pthread_cond_timedwait

-      pthread_cond_signal

-      pthread_cond_broadcast  

-

-      ---------------------------

-      Read/Write Locks - POSIX 1j

-      ---------------------------

-      pthread_rwlock_init

-      pthread_rwlock_destroy

-      pthread_rwlock_tryrdlock

-      pthread_rwlock_trywrlock

-      pthread_rwlock_rdlock

-      pthread_rwlock_rwlock

-      pthread_rwlock_unlock

-      pthread_rwlockattr_init

-      pthread_rwlockattr_destroy

-      pthread_rwlockattr_getpshared

-      pthread_rwlockattr_setpshared

-

-      ---------------------------

-      Spin Locks - POSIX 1j

-      ---------------------------

-      pthread_spin_init

-      pthread_spin_destroy

-      pthread_spin_lock

-      pthread_spin_unlock

-      pthread_spin_trylock

-

-      ---------------------------

-      Barriers - POSIX 1j

-      ---------------------------

-      pthread_barrier_init

-      pthread_barrier_destroy

-      pthread_barrier_wait

-      pthread_barrierattr_init

-      pthread_barrierattr_destroy

-      pthread_barrierattr_getpshared

-      pthread_barrierattr_setpshared

-

-      ---------------------------

-      Semaphores - POSIX 1b

-      ---------------------------

-      sem_init

-      sem_destroy

-      sem_post

-      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)

-

-      ---------------------------

-      RealTime Scheduling

-      ---------------------------

-      pthread_attr_getschedparam  

-      pthread_attr_setschedparam  

-      pthread_attr_getinheritsched

-      pthread_attr_setinheritsched

-      pthread_attr_getschedpolicy (only supports SCHED_OTHER)

-      pthread_attr_setschedpolicy (only supports SCHED_OTHER)

-      pthread_getschedparam

-      pthread_setschedparam

-      pthread_getconcurrency

-      pthread_setconcurrency

-      pthread_attr_getscope

-      pthread_attr_setscope  (only supports PTHREAD_SCOPE_SYSTEM)

-      sched_get_priority_max (POSIX 1b)

-      sched_get_priority_min (POSIX 1b)

-      sched_rr_get_interval  (POSIX 1b  - returns an error ENOTSUP)

-      sched_setscheduler     (POSIX 1b  - only supports SCHED_OTHER)

-      sched_getscheduler     (POSIX 1b  - only supports SCHED_OTHER)

-      sched_yield            (POSIX 1b)

-

-      ---------------------------

-      Signals

-      ---------------------------

-      pthread_sigmask

-

-      ---------------------------

-      Non-portable routines (see the README.NONPORTABLE file for usage)

-      ---------------------------

-      pthread_getw32threadhandle_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_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)

-

-      ---------------------------

-      Static Initializers

-      ---------------------------

-      PTHREAD_ONCE_INIT

-      PTHREAD_MUTEX_INITIALIZER

-      PTHREAD_COND_INITIALIZER

-      PTHREAD_RWLOCK_INITIALIZER

-      PTHREAD_SPINLOCK_INITIALIZER

-

-      ---------------------------

-      Thread-Safe C Runtime Library (macros)

-      ---------------------------

-      strtok_r

-      asctime_r

-      ctime_r

-      gmtime_r

-      localtime_r

-      rand_r

-

-

-The following functions are not implemented:

-      

-      ---------------------------

-      RealTime Scheduling

-      ---------------------------

-      pthread_mutex_getprioceiling

-      pthread_mutex_setprioceiling

-      pthread_mutex_attr_getprioceiling

-      pthread_mutex_attr_getprotocol

-      pthread_mutex_attr_setprioceiling

-      pthread_mutex_attr_setprotocol

-      

-      ---------------------------

-      Fork Handlers

-      ---------------------------

-      pthread_atfork

-

-      ---------------------------

-      Stdio

-      --------------------------- 

-      flockfile

-      ftrylockfile

-      funlockfile

-      getc_unlocked

-      getchar_unlocked  

-      putc_unlocked

-      putchar_unlocked

-

-      ---------------------------

-      Thread-Safe C Runtime Library

-      ---------------------------

-      readdir_r

-      getgrgid_r

-      getgrnam_r

-      getpwuid_r

-      getpwnam_r

-      

-      ---------------------------

-      Signals

-      ---------------------------

-      pthread_kill

-      sigtimedwait

-      sigwait

-      sigwaitinfo

-      

-      

-The library includes two non-API functions for creating cancellation

-points in applications and libraries:

-      

-      pthreadCancelableWait

-      pthreadCancelableTimedWait

-

-      

-Availability

------------- 

-

-The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header

-files (pthread.h, semaphore.h, sched.h) are available along with the

-complete source code.

-

-The source code can be found at:

-

-	ftp://sources.redhat.com/pub/pthreads-win32

-

-and as individual source code files at

-

-	ftp://sources.redhat.com/pub/pthreads-win32/source

-

-The pre-built DLL, export libraries and include files can be found at:

-

-	ftp://sources.redhat.com/pub/pthreads-win32/dll-latest

-

-

-      

-Mailing List 

-------------  

-      

-There is a mailing list for discussing pthreads on Win32. To join,

-send email to:

-

-        pthreads-win32-subscribe@sourceware.cygnus.com

-      

-

-Application Development Environments

-------------------------------------

-

-See the README file for more information.

-      

-MSVC:

-MSVC using SEH works. Distribute pthreadVSE.dll with your application.

-MSVC using C++ EH works. Distribute pthreadVCE.dll with your application.

-MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application.

-

-

-Mingw32:

-See 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.

-

-

-Cygwin: (http://sourceware.cygnus.com/cygwin/)

-Developers using Cygwin will not need pthreads-win32 since it has POSIX threads

-support. Refer to its documentation for details and extent.

-

-

-UWIN:

-UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32

-doesn't currently support UWIN (and vice versa), but that may change in the

-future.

-

-Generally:

-For convenience, the following pre-built files are available on the FTP site

-(see Availability above):

-

-	pthread.h	- for POSIX 1c threads

-	semaphore.h	- for POSIX 1b semaphores

-	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

-	pthreadVC.lib

-	pthreadVSE.dll	- built with MSVC compiler using SEH

-	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

-	libpthreadGC.a	- derived from pthreadGC.dll

-        gcc.dll         - needed if distributing applications that use pthreadGCE.dll

-

-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 POSIX Thread API programming, several reference books are

-available:  

-

-        Programming with POSIX Threads

-        David R. Butenhof

-        Addison-Wesley (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.

-

-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.

-

-Enjoy!

-

-Ross Johnson

+                 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>
+
+
+We are pleased to announce the availability of a new snapshot of
+Pthreads-win32, 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.
+
+Parts of the implementation also comply with the Open Group's
+Single Unix specification for compatibility with major Unix
+implementations and Linux.
+
+Pthreads-win32 is free software, distributed under the GNU Lesser
+General Public License (LGPL).
+
+Please see the 'Acknowledgements' section at the end of this
+announcement for the list of contributors.
+
+
+-------------------------------
+Changes since the last snapshot
+-------------------------------
+
+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 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()
+
+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.
+
+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
+   for some reason. The code in private.c ptw32_threadStart()
+   retrieves and calls the user supplied terminate routine, which
+   works as expected under MinGW32 g++, but doesn't run under
+   MS VC++ 6.0, presumably because set_terminate() returns NULL.
+
+2. Cancellation problems in optimised code
+   - Milan Gardian
+
+   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 () 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)
+
+   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.
+
+
+Caveats
+-------
+
+1. Due to what is believed to be a C++ compliance error in VC++,
+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.
+
+
+Level of standards conformance
+------------------------------
+
+The following POSIX 1003.1c/1b/1j options are defined:
+
+      _POSIX_THREADS
+      _POSIX_THREAD_SAFE_FUNCTIONS
+      _POSIX_THREAD_ATTR_STACKSIZE
+      _POSIX_THREAD_PRIORITY_SCHEDULING
+      _POSIX_SEMAPHORES
+      _POSIX_READER_WRITER_LOCKS
+      _POSIX_SPIN_LOCKS
+      _POSIX_BARRIERS
+
+
+The following POSIX 1003.1c options are not defined:
+
+      _POSIX_THREAD_ATTR_STACKADDR
+      _POSIX_THREAD_PRIO_INHERIT
+      _POSIX_THREAD_PRIO_PROTECT
+      _POSIX_THREAD_PROCESS_SHARED
+
+
+The following functions are implemented:
+
+      ---------------------------
+      PThreads
+      ---------------------------
+      pthread_attr_init
+      pthread_attr_destroy
+      pthread_attr_getdetachstate
+      pthread_attr_getstackaddr
+      pthread_attr_getstacksize
+      pthread_attr_setdetachstate
+      pthread_attr_setstackaddr
+      pthread_attr_setstacksize
+
+      pthread_create
+      pthread_detach
+      pthread_equal
+      pthread_exit
+      pthread_join
+      pthread_once
+      pthread_self
+
+      pthread_cancel
+      pthread_cleanup_pop
+      pthread_cleanup_push
+      pthread_setcancelstate
+      pthread_setcanceltype
+      pthread_testcancel
+          
+      ---------------------------
+      Thread Specific Data   
+      ---------------------------
+      pthread_key_create
+      pthread_key_delete
+      pthread_setspecific
+      pthread_getspecific
+                
+      ---------------------------
+      Mutexes
+      ---------------------------
+      pthread_mutexattr_init
+      pthread_mutexattr_destroy
+      pthread_mutexattr_getpshared
+      pthread_mutexattr_setpshared
+      pthread_mutexattr_gettype
+      pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT
+                                        PTHREAD_MUTEX_NORMAL
+                                        PTHREAD_MUTEX_ERRORCHECK
+                                        PTHREAD_MUTEX_RECURSIVE  )
+      pthread_mutex_init
+      pthread_mutex_destroy
+      pthread_mutex_lock
+      pthread_mutex_trylock
+      pthread_mutex_timedlock
+      pthread_mutex_unlock
+
+      ---------------------------
+      Condition Variables
+      ---------------------------
+      pthread_condattr_init
+      pthread_condattr_destroy
+      pthread_condattr_getpshared
+      pthread_condattr_setpshared
+
+      pthread_cond_init
+      pthread_cond_destroy
+      pthread_cond_wait
+      pthread_cond_timedwait
+      pthread_cond_signal
+      pthread_cond_broadcast  
+
+      ---------------------------
+      Read/Write Locks - POSIX 1j
+      ---------------------------
+      pthread_rwlock_init
+      pthread_rwlock_destroy
+      pthread_rwlock_tryrdlock
+      pthread_rwlock_trywrlock
+      pthread_rwlock_rdlock
+      pthread_rwlock_rwlock
+      pthread_rwlock_unlock
+      pthread_rwlockattr_init
+      pthread_rwlockattr_destroy
+      pthread_rwlockattr_getpshared
+      pthread_rwlockattr_setpshared
+
+      ---------------------------
+      Spin Locks - POSIX 1j
+      ---------------------------
+      pthread_spin_init
+      pthread_spin_destroy
+      pthread_spin_lock
+      pthread_spin_unlock
+      pthread_spin_trylock
+
+      ---------------------------
+      Barriers - POSIX 1j
+      ---------------------------
+      pthread_barrier_init
+      pthread_barrier_destroy
+      pthread_barrier_wait
+      pthread_barrierattr_init
+      pthread_barrierattr_destroy
+      pthread_barrierattr_getpshared
+      pthread_barrierattr_setpshared
+
+      ---------------------------
+      Semaphores - POSIX 1b
+      ---------------------------
+      sem_init
+      sem_destroy
+      sem_post
+      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)
+
+      ---------------------------
+      RealTime Scheduling
+      ---------------------------
+      pthread_attr_getschedparam  
+      pthread_attr_setschedparam  
+      pthread_attr_getinheritsched
+      pthread_attr_setinheritsched
+      pthread_attr_getschedpolicy (only supports SCHED_OTHER)
+      pthread_attr_setschedpolicy (only supports SCHED_OTHER)
+      pthread_getschedparam
+      pthread_setschedparam
+      pthread_getconcurrency
+      pthread_setconcurrency
+      pthread_attr_getscope
+      pthread_attr_setscope  (only supports PTHREAD_SCOPE_SYSTEM)
+      sched_get_priority_max (POSIX 1b)
+      sched_get_priority_min (POSIX 1b)
+      sched_rr_get_interval  (POSIX 1b  - returns an error ENOTSUP)
+      sched_setscheduler     (POSIX 1b  - only supports SCHED_OTHER)
+      sched_getscheduler     (POSIX 1b  - only supports SCHED_OTHER)
+      sched_yield            (POSIX 1b)
+
+      ---------------------------
+      Signals
+      ---------------------------
+      pthread_sigmask
+
+      ---------------------------
+      Non-portable routines (see the README.NONPORTABLE file for usage)
+      ---------------------------
+      pthread_getw32threadhandle_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_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)
+
+      ---------------------------
+      Static Initializers
+      ---------------------------
+      PTHREAD_ONCE_INIT
+      PTHREAD_MUTEX_INITIALIZER
+      PTHREAD_COND_INITIALIZER
+      PTHREAD_RWLOCK_INITIALIZER
+      PTHREAD_SPINLOCK_INITIALIZER
+
+      ---------------------------
+      Thread-Safe C Runtime Library (macros)
+      ---------------------------
+      strtok_r
+      asctime_r
+      ctime_r
+      gmtime_r
+      localtime_r
+      rand_r
+
+
+The following functions are not implemented:
+      
+      ---------------------------
+      RealTime Scheduling
+      ---------------------------
+      pthread_mutex_getprioceiling
+      pthread_mutex_setprioceiling
+      pthread_mutex_attr_getprioceiling
+      pthread_mutex_attr_getprotocol
+      pthread_mutex_attr_setprioceiling
+      pthread_mutex_attr_setprotocol
+      
+      ---------------------------
+      Fork Handlers
+      ---------------------------
+      pthread_atfork
+
+      ---------------------------
+      Stdio
+      --------------------------- 
+      flockfile
+      ftrylockfile
+      funlockfile
+      getc_unlocked
+      getchar_unlocked  
+      putc_unlocked
+      putchar_unlocked
+
+      ---------------------------
+      Thread-Safe C Runtime Library
+      ---------------------------
+      readdir_r
+      getgrgid_r
+      getgrnam_r
+      getpwuid_r
+      getpwnam_r
+      
+      ---------------------------
+      Signals
+      ---------------------------
+      pthread_kill
+      sigtimedwait
+      sigwait
+      sigwaitinfo
+      
+      
+The library includes two non-API functions for creating cancellation
+points in applications and libraries:
+      
+      pthreadCancelableWait
+      pthreadCancelableTimedWait
+
+      
+Availability
+------------ 
+
+The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header
+files (pthread.h, semaphore.h, sched.h) are available along with the
+complete source code.
+
+The source code can be found at:
+
+	ftp://sources.redhat.com/pub/pthreads-win32
+
+and as individual source code files at
+
+	ftp://sources.redhat.com/pub/pthreads-win32/source
+
+The pre-built DLL, export libraries and include files can be found at:
+
+	ftp://sources.redhat.com/pub/pthreads-win32/dll-latest
+
+
+      
+Mailing List 
+------------  
+      
+There is a mailing list for discussing pthreads on Win32. To join,
+send email to:
+
+        pthreads-win32-subscribe@sourceware.cygnus.com
+      
+
+Application Development Environments
+------------------------------------
+
+See the README file for more information.
+      
+MSVC:
+MSVC using SEH works. Distribute pthreadVSE.dll with your application.
+MSVC using C++ EH works. Distribute pthreadVCE.dll with your application.
+MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application.
+
+
+Mingw32:
+See 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.
+
+
+Cygwin: (http://sourceware.cygnus.com/cygwin/)
+Developers using Cygwin will not need pthreads-win32 since it has POSIX threads
+support. Refer to its documentation for details and extent.
+
+
+UWIN:
+UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32
+doesn't currently support UWIN (and vice versa), but that may change in the
+future.
+
+Generally:
+For convenience, the following pre-built files are available on the FTP site
+(see Availability above):
+
+	pthread.h	- for POSIX 1c threads
+	semaphore.h	- for POSIX 1b semaphores
+	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
+	pthreadVC.lib
+	pthreadVSE.dll	- built with MSVC compiler using SEH
+	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
+	libpthreadGC.a	- derived from pthreadGC.dll
+        gcc.dll         - needed if distributing applications that use pthreadGCE.dll
+
+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 POSIX Thread API programming, several reference books are
+available:  
+
+        Programming with POSIX Threads
+        David R. Butenhof
+        Addison-Wesley (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.
+
+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.
+
+Enjoy!
+
+Ross Johnson