PTHREADS-WIN32 ============== Pthreads-win32 is free software, distributed under the GNU Library General Public License (LGPL). See the file 'COPYING.LIB' for terms and conditions. What is it? ----------- Pthreads-win32 is an Open Source Software (OSS) 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. See the file "ANNOUNCE" for more information including standards conformance details and list of supported routines. 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][SC]E.dll pthread[VG][SC]E.lib where: [VG] indicates the compiler V - MS VC++ G - GNU G++ [SC] indicates the exception handling scheme S - Structured EH C - C++ EH For example: pthreadVSE.dll (VC++/SEH) pthreadGCE.dll (G++/C++ EH) The GNU library archive file name has changed to: libpthreadw32.a (the "32" is now "w32") 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. Known bugs in this snapshot --------------------------- 1. Asynchronous cancelation only works on Intel X86 machines. Caveats ------- 1. Due to what is believed to be 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. Non-portable functions included in the library ---------------------------------------------- void pthread_mutexattr_setforcecs_np(pthread_mutexattr_t *attr, int forcecs); Allows an application to force the library to use critical sections rather than win32 mutexes as the basis for any mutex that uses "attr". Critical sections are significantly faster than mutexes. Values for "forcecs" are: PTHREAD_MUTEX_AUTO_CS_NP - allow the library to decide based on availability of tryEnterCriticalSection(). The library determines this at runtime and will use critical sections whenever tryEnterCriticalSection() is available. PTHREAD_MUTEX_FORCE_CS_NP - force use of critical sections even if tryEnterCriticalSection() isn't provided by the system, but you'd better not try to use pthread_mutex_trylock() on any mutex that uses "attr" if you want your application to work on all versions of Windows. HANDLE pthread_getw32threadhandle_np(pthread_t thread); Returns the win32 thread handle that the POSIX thread "thread" is running as. Applications can use the win32 handle to set win32 specific attributes of the thread. int pthread_delay_np (const struct timespec *interval); This routine causes a thread to delay execution for a specific period of time. This period ends at the current time plus the specified interval. The routine will not return before the end of the period is reached, but may return an arbitrary amount of time after the period has gone by. This can be due to system load, thread priorities, and system timer granularity. Specifying an interval of zero (0) seconds and zero (0) nanoseconds is allowed and can be used to force the thread to give up the processor or to deliver a pending cancelation request. This routine is a cancelation point. The timespec structure contains the following two fields: tv_sec is an integer number of seconds. tv_nsec is an integer number of nanoseconds. Return Values If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: 0 Successful completion. [EINVAL] The value specified by interval is invalid. BOOL pthread_win32_process_attach_np (void); BOOL pthread_win32_process_detach_np (void); BOOL pthread_win32_thread_attach_np (void); BOOL pthread_win32_thread_detach_np (void); These functions contain the code normally run via dllMain when the library is used as a dll but which need to be called explicitly by an application when the library is statically linked. You will need to call pthread_win32_process_attach_np() before you can call any pthread routines when statically linking. You should call pthread_win32_process_detach_np() before exiting your application to clean up. pthread_win32_thread_attach_np() is currently a no-op, but pthread_win32_thread_detach_np() is needed to clean up after Win32 threads that have called pthreads routines have exited. These functions invariably return TRUE except for pthread_win32_process_attach_np() which will return FALSE if pthreads-win32 initialisation fails. int pthreadCancelableWait (HANDLE waitHandle); int pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout); These two functions provide hooks into the pthread_cancel mechanism that will allow you to wait on a Windows handle and make it a cancellation point. Both functions block until either the given w32 handle is signaled, or pthread_cancel has been called. It is implemented using WaitForMultipleObjects on 'waitHandle' and a manually reset w32 event used to implement pthread_cancel. Building under VC++ using either C++ EH or Structured EH -------------------------------------------------------- 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) 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 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. Hopefully versions after gcc-2.95.2-1 won't require the fix. Run "make" in the source directory (uses GNUmakefile). This builds pthreadGCE.dll and libpthreadw32.a. You can run the testsuite by changing to the "tests" directory and running "make clean" and then "make". 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 pthreadVSE.dll - built with MSVC compiler using SEH pthreadVSE.lib pthreadGCE.dll - built with Mingw32 G++ libpthreadw32.a - derived from 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. Building applications with GNU compilers ---------------------------------------- Use gcc-2.95.2-1 or later modified as per pthreads-win32 FAQ question 6. With pthreadGCE.dll and libpthreadw32.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. -lpthreadw32 myapp Or put pthreadGCE.dll in an appropriate directory in your PATH, put libpthread32.a in MINGW_ROOT\i386-mingw32\lib, and put pthread.h in MINGW_ROOT\i386-mingw32\include, then use: gcc -x c++ -o myapp.exe myapp.c -lpthreadw32 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 and bug fixes. See the 'CONTRIBUTORS' file for the list of contributors. ---- Ross Johnson