path: root/README

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 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 a, say,
C++ application cause object destructors and C++ exception
handlers to be invoked as the stack unwinds during thread
exit, or not?

Your choice will depend primarily on whether your application
is intended to be cross-platform or not, and how the POSIX threads
implementations on the target platforms handle this issue. That is,
you'll want consistent behaviour.

If you can't choose now, it's probably best to use the
standard C version of the library, even if your application
is being written in C++. You will need to handle the
potentially adverse effects of thread cancelation in your
code, but at least you will have the best chance of
consistency of behaviour across platforms. If you later
decide to use an exception handling version of the library
then you will hopefully have fewer, if any, changes to make.


Library naming
--------------

Because the library is being built using various exception
handling schemes and compilers - and because the library
will not work reliably if these are mixed in an application,
each different version of the library has it's own name.

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.


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


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


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

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>