Changes to documentation and makefiles.

1 files changed, 364 insertions, 118 deletions

diff --git a/NEWS b/NEWS
index 0ba7e58..d4cd9c0 100644
--- a/NEWS
+++ b/NEWS
@@ -1,118 +1,364 @@
-SNAPSHOT 2000-08-13
--------------------
-
-New:
--       Renamed DLL and LIB files:
-                pthreadVSE.dll  (MS VC++/Structured EH)
-                pthreadVSE.lib
-                pthreadVCE.dll  (MS VC++/C++ EH)
-                pthreadVCE.lib
-                pthreadGCE.dll  (GNU G++/C++ EH)
-                libpthreadw32.a
-
-        Both your application and the pthread dll should use the
-        same exception handling scheme.
-
-Bugs fixed:
--       MSVC++ C++ exception handling.
-
-Some new tests have been added.
-
-
-SNAPSHOT 2000-08-10
--------------------
-
-New:
--       asynchronous cancelation on X86 (Jason Nye)
--       Makefile compatible with MS nmake to replace
-        buildlib.bat
--       GNUmakefile for Mingw32
--       tests/Makefile for MS nmake replaces runall.bat
--       tests/GNUmakefile for Mingw32
-
-Bugs fixed:
--       kernel32 load/free problem
--       attempt to hide internel exceptions from application
-        exception handlers (__try/__except and try/catch blocks)
--       Win32 thread handle leakage bug
-        (David Baggett/Paul Redondo/Eyal Lebedinsky)
-
-Some new tests have been added.
-
-
-SNAPSHOT 1999-11-02
--------------------
-
-Bugs fixed:
--       ctime_r macro had an incorrect argument (Erik Hensema),
--       threads were not being created 
-        PTHREAD_CANCEL_DEFERRED. This should have
-        had little effect as deferred is the only
-        supported type. (Ross Johnson).
-
-Some compatibility improvements added, eg.
--       pthread_setcancelstate accepts NULL pointer
-        for the previous value argument. Ditto for
-        pthread_setcanceltype. This is compatible
-        with Solaris but should not affect
-        standard applications (Erik Hensema)
-
-Some new tests have been added.
-
-
-SNAPSHOT 1999-10-17
--------------------
-
-Bug fix - Cancelation of threads waiting on condition variables
-now works properly (Lorin Hochstein and Peter Slacik)
-
-
-SNAPSHOT 1999-08-12
--------------------
-
-Fixed exception stack cleanup if calling pthread_exit()
-- (Lorin Hochstein and John Bossom).
-
-Fixed bugs in condition variables - (Peter Slacik):
-        - additional contention checks
-        - properly adjust number of waiting threads after timed
-          condvar timeout.
-
-
-SNAPSHOT 1999-05-30
--------------------
-
-Some minor bugs have been fixed. See the ChangeLog file for details.
-
-Some more POSIX 1b functions are now included but ony return an
-error (ENOSYS) if called. They are:
-
-        sem_open
-        sem_close
-        sem_unlink
-        sem_getvalue
-
-
-SNAPSHOT 1999-04-07
--------------------
-
-Some POSIX 1b functions which were internally supported are now
-available as exported functions:
-
-        sem_init
-        sem_destroy
-        sem_wait
-        sem_trywait
-        sem_post
-        sched_yield
-        sched_get_priority_min
-        sched_get_priority_max
-
-Some minor bugs have been fixed. See the ChangeLog file for details.
-
-
-SNAPSHOT 1999-03-16
--------------------
-
-Initial release.
-
+SNAPSHOT 2002-03-02

+-------------------

+

+Cleanup code default style. (IMPORTANT)

+----------------------------------------------------------------------

+Previously, if not defined, the cleanup style was determined automatically

+from the compiler/language, and one of the following was defined accordingly:

+

+        __CLEANUP_SEH   MSVC only

+        __CLEANUP_CXX   C++, including MSVC++, GNU G++

+        __CLEANUP_C             C, including GNU GCC, not MSVC

+

+These defines determine the style of cleanup (see pthread.h) and,

+most importantly, the way that cancelation and thread exit (via

+pthread_exit) is performed (see the routine ptw32_throw() in private.c).

+

+In short, the exceptions versions of the library throw an exception

+when a thread is canceled or exits (via pthread_exit()), which is

+caught by a handler in the thread startup routine, so that the

+the correct stack unwinding occurs regardless of where the thread

+is when it's canceled or exits via pthread_exit().

+

+In this and future snapshots, unless the build explicitly defines (e.g.

+via a compiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then

+the build NOW always defaults to __CLEANUP_C style cleanup. This style

+uses setjmp/longjmp in the cancelation and pthread_exit implementations,

+and therefore won't do stack unwinding even when linked to applications

+that have it (e.g. C++ apps). This is for consistency with most

+current commercial Unix POSIX threads implementations. Compaq's TRU64

+may be an exception (no pun intended) and possible future trend.

+

+Although it was not clearly documented before, it is still necessary to

+build your application using the same __CLEANUP_* define as was

+used for the version of the library that you link with, so that the

+correct parts of pthread.h are included. That is, the possible

+defines require the following library versions:

+

+        __CLEANUP_SEH   pthreadVSE.dll

+        __CLEANUP_CXX   pthreadVCE.dll or pthreadGCE.dll

+        __CLEANUP_C     pthreadVC.dll or pthreadGC.dll

+

+E.g. regardless of whether your app is C or C++, if you link with

+pthreadVC.lib or libpthreadGC.a, then you must define __CLEANUP_C.

+

+

+THE POINT OF ALL THIS IS: if you have not been defining one of these

+explicitly, then the defaults as described at the top of this

+section were being used.

+

+THIS NOW CHANGES, as has been explained above, but to try to make this

+clearer here's an example:

+

+If you were building your application with MSVC++ i.e. using C++

+exceptions and not explicitly defining one of __CLEANUP_*, then

+__CLEANUP_C++ was automatically defined for you in pthread.h.

+You should have been linking with pthreadVCE.dll, which does

+stack unwinding.

+

+If you now build your application as you had before, pthread.h will now

+automatically set __CLEANUP_C as the default style, and you will need to

+link with pthreadVC.dll. Stack unwinding will now NOT occur when a thread

+is canceled, or the thread calls pthread_exit().

+

+Your application will now most likely behave differently to previous

+versions, and in non-obvious ways. Most likely is that locally

+instantiated objects may not be destroyed or cleaned up after a thread

+is canceled.

+

+If you want the same behaviour as before, then you must now define

+__CLEANUP_C++ explicitly using a compiler option and link with

+pthreadVCE.dll as you did before.

+

+

+WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY?

+Because no commercial Unix POSIX threads implementation allows you to

+choose to have stack unwinding. Therefore, providing it in pthread-win32

+as a default is dangerous. We still provide the choice but unless

+you consciously choose to do otherwise, your pthreads applications will

+now run or crash in similar ways irrespective of the threads platform

+you use. Or at least this is the hope.

+

+

+WHY NOT REMOVE THE EXCEPTIONS VERSIONS OF THE LIBRARY ALTOGETHER?

+There are a few reasons:

+- because there are well respected POSIX threads people who believe

+  that POSIX threads implementations should be exceptions aware and

+  do the expected thing in that context. (There are equally respected

+  people who believe it should not be easily accessible, if it's there

+  at all, for unconditional conformity to other implementations.)

+- because pthreads-win32 is one of the few implementations that has

+  the choice, perhaps the only freely available one, and so offers

+  a laboratory to people who may want to explore the effects;

+- although the code will always be around somewhere for anyone who

+  wants it, once it's removed from the current version it will not be

+  nearly as visible to people who may have a use for it.

+

+

+Source module splitting

+-----------------------

+In order to enable smaller image sizes to be generated

+for applications that link statically with the library,

+most routines have been separated out into individual

+source code files.

+

+This is being done in such a way as to be backward compatible.

+The old source files are reused to congregate the individual

+routine files into larger translation units (via a bunch of

+# includes) so that the compiler can still optimise wherever

+possible, e.g. through inlining, which can only be done

+within the same translation unit.

+

+It is also possible to build the entire library by compiling

+the single file named "pthread.c", which just #includes all

+the secondary congregation source files. The compiler

+may be able to use this to do more inlining of routines.

+

+Although the GNU compiler is able to produce libraries with

+the necessary separation (the -ffunction-segments switch),

+AFAIK, the MSVC and other compilers don't have this feature.

+

+Finally, since I use makefiles and command-line compilation,

+I don't know what havoc this reorganisation may wreak amongst

+IDE project file users. You should be able to continue

+using your existing project files without modification.

+

+

+New non-portable functions

+--------------------------

+pthread_num_processors_np():

+  Returns the number of processors in the system that are

+  available to the process, as determined from the processor

+  affinity mask.

+

+pthread_timechange_handler_np():

+  To improve tolerance against operator or time service initiated

+  system clock changes.

+

+  This routine can be called by an application when it

+  receives a WM_TIMECHANGE message from the system. At present

+  it broadcasts all condition variables so that waiting threads

+  can wake up and re-evaluate their conditions and restart

+  their timed waits if required.

+  - Suggested by Alexander Terekhov

+

+

+Platform dependence

+-------------------

+As Win95 doesn't provide one, the library now contains

+it's own InterlockedCompareExchange() routine, which is used

+whenever Windows doesn't provide it. InterlockedCompareExchange()

+is used to implement spinlocks and barriers, and also in mutexes.

+This routine relies on the CMPXCHG machine instruction which

+is not available on i386 CPUs. This library (from snapshot

+20010712 onwards) is therefore no longer supported on i386

+processor platforms.

+

+

+New standard routines

+---------------------

+For source code portability only - rwlocks cannot be process shared yet.

+

+        pthread_rwlockattr_init()

+        pthread_rwlockattr_destroy()

+        pthread_rwlockattr_setpshared()

+        pthread_rwlockattr_getpshared()

+

+As defined in the new POSIX standard, and the Single Unix Spec version 3:

+

+        sem_timedwait()

+        pthread_mutex_timedlock()    - Alexander Terekhov and Thomas Pfaff

+        pthread_rwlock_timedrdlock() - adapted from pthread_rwlock_rdlock()

+        pthread_rwlock_timedwrlock() - adapted from pthread_rwlock_wrlock()

+

+

+pthread.h no longer includes windows.h

+--------------------------------------

+[Not yet for G++]

+

+This was done to prevent conflicts.

+

+HANDLE, DWORD, and NULL are temporarily defined within pthread.h if

+they are not already.

+

+

+pthread.h, sched.h and semaphore.h now use dllexport/dllimport

+--------------------------------------------------------------

+Not only to avoid the need for the pthread.def file, but to

+improve performance. Apparently, declaring functions with dllimport

+generates a direct call to the function and avoids the overhead

+of a stub function call.

+

+Bug fixes

+---------

+* Fixed potential NULL pointer dereferences in pthread_mutexattr_init,

+pthread_mutexattr_getpshared, pthread_barrierattr_init,

+pthread_barrierattr_getpshared, and pthread_condattr_getpshared.

+- Scott McCaskill <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.

+