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 (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 the list of supported and unsupported routines. Prerequisites ------------- MSVC or GNU C (MinGW32 MSys development kit) To build from source. QueueUserAPCEx by Panagiotis E. Hadjidoukas For true async cancelation of threads (including blocked threads). This is a DLL and Windows driver that provides pre-emptive APC by forcing threads into an alertable state when the APC is queued. Both the DLL and driver are provided with the pthreads-win32.exe self-unpacking ZIP, and on the pthreads-win32 FTP site (in source and pre-built forms). Currently this is a separate LGPL package to pthreads-win32. See the README in the QueueUserAPCEx folder for installation instructions. Pthreads-win32 will automatically detect if the QueueUserAPCEx DLL QuserEx.DLL is available and whether the driver AlertDrv.sys is loaded. If it is not available, pthreads-win32 will simulate async cancelation, which means that it cannot pre-empt blocked threads. 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 was to also name either the VC or GC version (it should be arbitrary) as pthread.dll, including pthread.lib and libpthread.a as appropriate. This is no longer likely to happen. Note 4: the compatibility number was added so that applications can differentiate between binary incompatible versions of the libs and dlls. In general: pthread[VG]{SE,CE,C}c.dll pthread[VG]{SE,CE,C}c.lib where: [VG] indicates the compiler V - MS VC, or G - GNU C {SE,CE,C} indicates the exception handling scheme SE - Structured EH, or CE - C++ EH, or C - no exceptions - uses setjmp/longjmp c - DLL compatibility number indicating ABI and API compatibility with applications built against any snapshot with the same compatibility number. See 'Version numbering' below. For example: pthreadVSE.dll (MSVC/SEH) pthreadGCE.dll (GNUC/C++ EH) pthreadGC.dll (GNUC/not dependent on exceptions) pthreadVC1.dll (MSVC/not dependent on exceptions - not binary compatible with pthreadVC.dll) The GNU library archive file names have correspondingly changed to: libpthreadGCEc.a libpthreadGCc.a Versioning numbering -------------------- Version numbering is separate from the snapshot dating system, and is the canonical version identification system embedded within the DLL using the Microsoft version resource system. The versioning system chosen follows the GNU Libtool system. See http://www.gnu.org/software/libtool/manual.html section 6.2. See the resource file 'version.rc'. Microsoft version numbers use 4 integers: 0.0.0.0 Pthreads-win32 uses the first 3 following the Libtool convention. The fourth is commonly used for the build number, but will be reserved for future use. current.revision.age.0 The numbers are changed as follows: 1. If the library source code has changed at all since the last update, then increment revision (`c:r:a' becomes `c:r+1:a'). 2. If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0. 3. If any interfaces have been added since the last public release, then increment age. 4. If any interfaces have been removed or changed since the last public release, then set age to 0. DLL compatibility numbering is an attempt to ensure that applications always load a compatible pthreads-win32 DLL by using a DLL naming system that is consistent with the version numbering system. It also allows older and newer DLLs to coexist in the same filesystem so that older applications can continue to be used. For pre .NET Windows systems, this inevitably requires incompatible versions of the same DLLs to have different names. Pthreads-win32 has adopted the Cygwin convention of appending a single integer number to the DLL name. The number used is based on the library version number and is computed as 'current' - 'age'. (See http://home.att.net/~perlspinr/libversioning.html for a nicely detailed explanation.) Using this method, DLL name/s will only change when the DLL's backwards compatibility changes. Note that the addition of new 'interfaces' will not of itself change the DLL's compatibility for older applications. Which of the several dll versions to use? ----------------------------------------- or, --- What are all these pthread*.dll and pthread*.lib files? ------------------------------------------------------- Simple, use either pthreadGCv.* if you use GCC, or pthreadVCv.* if you use MSVC - where 'v' is the DLL versioning (compatibility) number. 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 of the library that use exceptions as part of the thread 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 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 handlers to be invoked as the stack unwinds during thread exit, or not? There seems to be more opinion in favour of using the standard C version of the library (no EH) with C++ applications 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. Now you may be asking: then why have you kept the EH versions of the library? There are a couple of reasons: - there is division amongst the experts and so the code may be needed in the future. Yes, it's in the repository and we can get it out anytime in the future, but 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. Notes: [If you use either pthreadVCE or pthreadGCE] 1. [See also the discussion in the FAQ file - Q2, Q4, and Q5] If your application contains catch(...) blocks in your POSIX threads then you will need to replace the "catch(...)" with the macro "PtW32Catch", eg. #ifdef PtW32Catch PtW32Catch { ... } #else catch(...) { ... } #endif Otherwise neither pthreads cancelation nor pthread_exit() will work reliably when using versions of the library that use C++ exceptions for cancelation and thread exit. This is due to what is believed to be a C++ compliance error in VC++ whereby you may not have multiple handlers for the same exception in the same try/catch block. GNU G++ doesn't have this restriction. 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. Cleanup code default style -------------------------- Previously, if not defined, the cleanup style was determined automatically from the compiler used, and one of the following was defined accordingly: __CLEANUP_SEH MSVC only __CLEANUP_CXX C++, including MSVC++, GNU G++ __CLEANUP_C C, including GNU GCC, not MSVC These defines determine the style of cleanup (see pthread.h) and, most importantly, the way that cancelation and thread exit (via pthread_exit) is performed (see the routine ptw32_throw()). In short, the exceptions versions of the library throw an exception when a thread is canceled, or exits via pthread_exit(). This exception is caught by a handler in the thread startup routine, so that the the correct stack unwinding occurs regardless of where the thread is when it's canceled or exits via pthread_exit(). In this snapshot, unless the build explicitly defines (e.g. via a compiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then the build NOW always defaults to __CLEANUP_C style cleanup. This style uses setjmp/longjmp in the cancelation and pthread_exit implementations, and therefore won't do stack unwinding even when linked to applications that have it (e.g. C++ apps). This is for consistency with most/all commercial Unix POSIX threads implementations. Although it was not clearly documented before, it is still necessary to build your application using the same __CLEANUP_* define as was used for the version of the library that you link with, so that the correct parts of pthread.h are included. That is, the possible defines require the following library versions: __CLEANUP_SEH pthreadVSE.dll __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll __CLEANUP_C pthreadVC.dll or pthreadGC.dll It is recommended that you let pthread.h use it's default __CLEANUP_C for both library and application builds. That is, don't define any of the above, and then link with pthreadVC.lib (MSVC or MSVC++) and libpthreadGC.a (MinGW GCC or G++). The reason is explained below, but another reason is that the prebuilt pthreadVCE.dll is currently broken. Versions built with MSVC++ later than version 6 may not be broken, but I can't verify this yet. 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 pthreads platform you use. Or at least this is the hope. Building under VC++ using C++ EH, Structured EH, or just C ---------------------------------------------------------- From the source directory run one of the following: nmake clean VC-inlined (builds the VC setjmp/longjmp version of pthreadVC.dll) or: nmake clean VCE-inlined (builds the VC++ C++ EH version pthreadVCE.dll) or: nmake clean VSE-inlined (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 VC or: nmake clean VCE or: nmake clean VSE or: nmake clean VCX (tests the VC version of the library with C++ (EH) applications) Building under Mingw32 ---------------------- 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 GC-inlined or: make clean GCE-inlined You can run the testsuite by changing to the "tests" directory and running make clean GC or: make clean GCE or: make clean GCX (tests the GC version of the library with C++ (EH) applications) Building the library under Cygwin --------------------------------- 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 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 pthreadGC.dll - built with Mingw32 GCC 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. gcc.dll - needed to build and run applications that use pthreadGCE.dll. Building applications with GNU compilers ---------------------------------------- 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 your system lib directory, and put the three header files in your system include directory, then use: gcc -o myapp.exe myapp.c -lpthreadGC myapp 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, 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 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 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 ---------------- See the ANNOUNCE file for acknowledgements. See the 'CONTRIBUTORS' file for the list of contributors. As much as possible, the ChangeLog file attributes contributions and patches that have been incorporated 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