Cleanup and fixes to thread priority management. Other minor changes.snap-2003-09-18

1 files changed, 125 insertions, 127 deletions

diff --git a/README b/README
index b669f81..fc7c2f6 100644
--- a/README
+++ b/README
@@ -11,15 +11,68 @@ 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.

+Threads component of the POSIX 1003.1c 1995 Standard (or later)

+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,

+plus some common and pthreads-win32 specific non-portable

+routines (see README.NONPORTABLE).

 

 See the file "ANNOUNCE" for more information including standards

-conformance details and list of supported routines.

+conformance details and the list of supported and unsupported

+routines.

+

+

+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

 

 

 Which of the several dll versions to use?

@@ -35,15 +88,15 @@ use MSVC.
 Otherwise, you need to choose carefully and know WHY.

 

 The most important choice you need to make is whether to use a

-version that uses exceptions internally, or not (there are versions

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

+cancelation and exit implementation. The default version uses

+setjmp/longjmp.

 

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

+with languages that use exceptions, 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

@@ -52,8 +105,8 @@ 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

+for the reason that 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 differently when linked with other pthreads libraries.

@@ -63,19 +116,14 @@ 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 ...)

+  be needed in the future. Yes, it's in the repository and we

+  can get it out anytime in the future, but it would be difficult

+  to find.

 - 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 be 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]

@@ -105,56 +153,6 @@ whereby you may not have multiple handlers for the same exception in
 the same try/catch block. GNU G++ doesn't have this restriction.

 

 

-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

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

 

@@ -253,28 +251,28 @@ 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)

+nmake clean VC	(builds the VC setjmp/longjmp version of pthreadVC.dll)

 

 or:

 

-nmake clean VSE (builds the VC++ structured EH version pthreadVSE.dll)

+nmake clean VCE (builds the VC++ C++ EH version pthreadVCE.dll)

 

 or:

 

-nmake clean VC	(builds the VC setjmp/longjmp version of pthreadVC.dll)

+nmake clean VSE (builds the VC++ structured EH version pthreadVSE.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

+nmake clean VC

 

 or:

 

-nmake clean VSE

+nmake clean VCE

 

 or:

 

-nmake clean VC

+nmake clean VSE

 

 or:

 

@@ -285,25 +283,26 @@ nmake clean VCX (tests the VC version of the library with C++ (EH)
 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.

+The dll can be built easily with recent versions of Mingw32.

+(The distributed versions are built using Mingw32 and MsysDTK

+from www.mingw32.org.)

 

 From the source directory, run

 

-make clean GCE

+make clean GC

 

 or:

 

-make clean GC

+make clean GCE

 

 You can run the testsuite by changing to the "tests" directory and

 running

 

-make clean GCE

+make clean GC

 

 or:

 

-make clean GC

+make clean GCE

 

 or:

 

@@ -331,41 +330,47 @@ from the FTP site (see under "Availability" below):
 	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

+	pthreadVCE.dll	- built with MSVC++ compiler using C++ EH

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

+	libpthreadGC.a	- derived from pthreadGC.dll

+	pthreadGCE.dll	- built with Mingw32 G++

+	libpthreadGCE.a	- derived from pthreadGCE.dll

+

+As of August 2003 pthreads-win32 pthreadG* versions are built and tested

+using the MinGW + MsysDTK environment current as of that date or later.

+The following file MAY be needed for older MinGW environments.

 

-As of August 2003 pthreads-win32 is built and tested using the MinGW + MsysDTK

-environment current as of that date or later. The following file MAY be needed

-for older MinGW environments.

 	gcc.dll 	- needed to build and run applications that use

 			  pthreadGCE.dll.

 

 

-Building applications with the library

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

+Building applications with GNU compilers

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

 

-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 you're using pthreadGC.dll:

 

-If in doubt use the C (no-exceptions) versions of the library.

+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

 

-Building applications with GNU compilers

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

+Or put pthreadGC.dll in an appropriate directory in your PATH,

+put libpthreadGC.a in your system lib directory, and

+put the three header files in your system include directory,

+then use:

 

-If you're using pthreadGCE.dll:

+	gcc -o myapp.exe myapp.c -lpthreadGC

+	myapp

 

-Use gcc-2.95.2-1 or later modified as per pthreads-win32 FAQ question 11.

+

+If you're using pthreadGCE.dll:

 

 With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a

 in the same directory as your application myapp.c, you could compile,

@@ -375,30 +380,13 @@ link and run myapp.c under Mingw32 as follows:
 	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,

+your PATH, put libpthreadGCE.a in your system lib directory, and

+put the three header files in your system include directory,

 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

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

@@ -436,20 +424,30 @@ 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.

+and Louis Thomas for their implementation of condition variables

+(see README.CV).

+

+Thanks also to the authors of the following paper, which served as

+the first CV design, and which identifies the important issues:

+"Strategies for Implementing POSIX Condition Variables on Win32"

+- http://www.cs.wustl.edu/~schmidt/win32-cv-1.html

 

 See the 'CONTRIBUTORS' file for the list of contributors.

 

-As much as possible, the ChangeLog file also attributes

+As much as possible, the ChangeLog file attributes

 contributions and patches that have been incorporated

-in the library.

+in the library to the individuals responsible.

+

+Finally, thanks to all those who work on and contribute to the

+POSIX and Single Unix Specification standards. The maturity of an

+industry can be measured by it's open standards.

 

 ----

 Ross Johnson

-<rpj@ise.canberra.edu.au>

+<rpj@callisto.canberra.edu.au>