PTHREADS-WIN32 SNAPSHOT 2001-??-?? ---------------------------------- Web Site: http://sources.redhat.com/pthreads-win32/ FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 Coordinator: Ross Johnson We are pleased to announce the availability of a new snapshot of Pthreads-win32, 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. Parts of the implementation also comply with the Open Group's Single Unix specification for compatibility with major Unix implementations and Linux. Pthreads-win32 is free software, distributed under the GNU Lesser General Public License (LGPL). Please see the 'Acknowledgements' section at the end of this announcement for the list of contributors. ------------------------------- Changes since the last snapshot ------------------------------- 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. rwlocks ------- Restored pthread_rwlock_wrlock() as a cancelation point as permitted by POSIX 1003.1j. (Was prematurely disabled in the last snapshot.) 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 Removed potential race condition in pthread_mutex_trylock and pthread_mutex_lock; - Alexander Terekhov 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 --------------------------- Known bugs in this snapshot --------------------------- 1. Under MS VC++ (only tested with version 6.0), a term_func set via the standard C++ set_terminate() function is not called for some reason. The code in private.c ptw32_threadStart() retrieves and calls the user supplied terminate routine, which works as expected under MinGW32 g++, but doesn't run under MS VC++ 6.0, presumably because set_terminate() returns NULL. 2. Cancellation problems in optimised code - Milan Gardian The cancellation (actually, cleanup-after-cancel) tests fail when using VC (professional) optimisation switches (/O1 or /O2) in pthreads library. I have not investigated which concrete optimisation technique causes this problem (/Og, /Oi, /Ot, /Oy, /Ob1, /Gs, /Gf, /Gy, etc.), but here is a summary of builds and corresponding failures: * pthreads VSE (optimised tests): OK * pthreads VCE (optimised tests): Failed "cleanup1" test (runtime) * pthreads VSE (DLL in CRT, optimised tests): OK * pthreads VCE (DLL in CRT, optimised tests): Failed "cleanup1" test (runtime) Please note that while in VSE version of the pthreads library the optimisation does not really have any impact on the tests (they pass OK), in VCE version addition of optimisation (/O2 in this case) causes the tests to fail uniformly - either in "cleanup0" or "cleanup1" test cases. Please note that all the tests above use default pthreads DLL (no optimisations, linked with either static or DLL CRT, based on test type). Therefore the problem lies not within the pthreads DLL but within the compiled client code (the application using pthreads -> involvement of "pthread.h"). I think the message of this section is that usage of VCE version of pthreads in applications relying on cancellation/cleanup AND using optimisations for creation of production code is highly unreliable for the current version of the pthreads library. Caveats ------- 1. Due to what is believed to be a 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. Level of standards conformance ------------------------------ The following POSIX 1003.1c/1b/1j options are defined: _POSIX_THREADS _POSIX_THREAD_SAFE_FUNCTIONS _POSIX_THREAD_ATTR_STACKSIZE _POSIX_THREAD_PRIORITY_SCHEDULING _POSIX_SEMAPHORES _POSIX_READER_WRITER_LOCKS _POSIX_SPIN_LOCKS _POSIX_BARRIERS The following POSIX 1003.1c options are not defined: _POSIX_THREAD_ATTR_STACKADDR _POSIX_THREAD_PRIO_INHERIT _POSIX_THREAD_PRIO_PROTECT _POSIX_THREAD_PROCESS_SHARED The following functions are implemented: --------------------------- PThreads --------------------------- pthread_attr_init pthread_attr_destroy pthread_attr_getdetachstate pthread_attr_getstackaddr pthread_attr_getstacksize pthread_attr_setdetachstate pthread_attr_setstackaddr pthread_attr_setstacksize pthread_create pthread_detach pthread_equal pthread_exit pthread_join pthread_once pthread_self pthread_cancel pthread_cleanup_pop pthread_cleanup_push pthread_setcancelstate pthread_setcanceltype pthread_testcancel --------------------------- Thread Specific Data --------------------------- pthread_key_create pthread_key_delete pthread_setspecific pthread_getspecific --------------------------- Mutexes --------------------------- pthread_mutexattr_init pthread_mutexattr_destroy pthread_mutexattr_getpshared pthread_mutexattr_setpshared pthread_mutexattr_gettype pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_NORMAL PTHREAD_MUTEX_ERRORCHECK PTHREAD_MUTEX_RECURSIVE ) pthread_mutex_init pthread_mutex_destroy pthread_mutex_lock pthread_mutex_trylock pthread_mutex_unlock --------------------------- Condition Variables --------------------------- pthread_condattr_init pthread_condattr_destroy pthread_condattr_getpshared pthread_condattr_setpshared pthread_cond_init pthread_cond_destroy pthread_cond_wait pthread_cond_timedwait pthread_cond_signal pthread_cond_broadcast --------------------------- Read/Write Locks - POSIX 1j --------------------------- pthread_rwlock_init pthread_rwlock_destroy pthread_rwlock_tryrdlock pthread_rwlock_trywrlock pthread_rwlock_rdlock pthread_rwlock_rwlock pthread_rwlock_unlock --------------------------- Spin Locks - POSIX 1j --------------------------- pthread_spin_init pthread_spin_destroy pthread_spin_lock pthread_spin_unlock pthread_spin_trylock --------------------------- Barriers - POSIX 1j --------------------------- pthread_barrier_init pthread_barrier_destroy pthread_barrier_wait pthread_barrierattr_init pthread_barrierattr_destroy pthread_barrierattr_getpshared pthread_barrierattr_setpshared --------------------------- Semaphores - POSIX 1b --------------------------- sem_init sem_destroy sem_post sem_wait sem_trywait sem_open (returns an error ENOSYS) sem_close (returns an error ENOSYS) sem_unlink (returns an error ENOSYS) sem_getvalue (returns an error ENOSYS) --------------------------- RealTime Scheduling --------------------------- pthread_attr_getschedparam pthread_attr_setschedparam pthread_attr_getinheritsched pthread_attr_setinheritsched pthread_attr_getschedpolicy (only supports SCHED_OTHER) pthread_attr_setschedpolicy (only supports SCHED_OTHER) pthread_getschedparam pthread_setschedparam pthread_getconcurrency pthread_setconcurrency pthread_attr_getscope pthread_attr_setscope (only supports PTHREAD_SCOPE_SYSTEM) sched_get_priority_max (POSIX 1b) sched_get_priority_min (POSIX 1b) sched_rr_get_interval (POSIX 1b - returns an error ENOTSUP) sched_setscheduler (POSIX 1b - only supports SCHED_OTHER) sched_getscheduler (POSIX 1b - only supports SCHED_OTHER) sched_yield (POSIX 1b) --------------------------- Signals --------------------------- pthread_sigmask --------------------------- Non-portable routines (see the README.NONPORTABLE file for usage) --------------------------- pthread_getw32threadhandle_np pthread_delay_np pthread_mutexattr_getkind_np pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP, PTHREAD_MUTEX_ERRORCHECK_NP, PTHREAD_MUTEX_RECURSIVE_NP) pthread_win32_process_attach_np pthread_win32_process_detach_np pthread_win32_thread_attach_np pthread_win32_thread_detach_np --------------------------- Static Initializers --------------------------- PTHREAD_ONCE_INIT PTHREAD_MUTEX_INITIALIZER PTHREAD_COND_INITIALIZER PTHREAD_RWLOCK_INITIALIZER PTHREAD_SPINLOCK_INITIALIZER --------------------------- Thread-Safe C Runtime Library (macros) --------------------------- strtok_r asctime_r ctime_r gmtime_r localtime_r rand_r The following functions are not implemented: --------------------------- RealTime Scheduling --------------------------- pthread_mutex_getprioceiling pthread_mutex_setprioceiling pthread_mutex_attr_getprioceiling pthread_mutex_attr_getprotocol pthread_mutex_attr_setprioceiling pthread_mutex_attr_setprotocol --------------------------- Fork Handlers --------------------------- pthread_atfork --------------------------- Stdio --------------------------- flockfile ftrylockfile funlockfile getc_unlocked getchar_unlocked putc_unlocked putchar_unlocked --------------------------- Thread-Safe C Runtime Library --------------------------- readdir_r getgrgid_r getgrnam_r getpwuid_r getpwnam_r --------------------------- Signals --------------------------- pthread_kill sigtimedwait sigwait sigwaitinfo The library includes two non-API functions for creating cancellation points in applications and libraries: pthreadCancelableWait pthreadCancelableTimedWait Availability ------------ The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header files (pthread.h, semaphore.h, sched.h) are available along with the complete source code. The source code can be found at: ftp://sources.redhat.com/pub/pthreads-win32 and as individual source code files at ftp://sources.redhat.com/pub/pthreads-win32/source The pre-built DLL, export libraries and include files can be found at: ftp://sources.redhat.com/pub/pthreads-win32/dll-latest Mailing List ------------ There is a mailing list for discussing pthreads on Win32. To join, send email to: pthreads-win32-subscribe@sourceware.cygnus.com Application Development Environments ------------------------------------ See the README file for more information. MSVC: MSVC using SEH works. Distribute pthreadVSE.dll with your application. MSVC using C++ EH works. Distribute pthreadVCE.dll with your application. MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application. Mingw32: You need gcc-2.95.2-1 modified as per pthreads-win32 FAQ answer (6), with binutils-19990818-1 and msvcrt runtime-2000-03-27. Mingw32 must use the thread-safe MSVCRT library (see the FAQ). You need to distribute the gcc.dll DLL from Mingw32 with your application. Mingw using C++ EH works. Distribute pthreadGCE.dll with your application. Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application. Cygwin: (http://sourceware.cygnus.com/cygwin/) Cygwin aims to provide a complete POSIX environment on top of Win32, including threads. When this is complete, developers using Cygwin will not need pthreads-win32. At this time, Cygwin has preliminary support for multithreaded development, however, this is not turned on by default. We have not tested pthreads-win32 against Cygwin. UWIN: UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32 doesn't currently support UWIN (and vice versa), but that may change in the future. Generally: For convenience, the following pre-built files are available on the FTP site (see Availability above): pthread.h - for POSIX 1c threads semaphore.h - for POSIX 1b semaphores sched.h - for POSIX 1b scheduling 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++ 2.95.2-1 pthreadGC.dll - built with Mingw32 GCC 2.95.2-1 using setjmp/longjmp libpthreadGCE.a - derived from pthreadGCE.dll libpthreadGC.a - derived from pthreadGC.dll gcc.dll - needed if distributing applications that use pthreadGCE.dll These are the only files you need in order to build POSIX threads applications for Win32 using either MSVC or Mingw32. See the FAQ file in the source tree for additional information. Documentation ------------- Currently, there is no documentation included in the package apart from the copious comments in the source code. For POSIX Thread API programming, several reference books are available: Programming with POSIX Threads David R. Butenhof Addison-Wesley (pub) Pthreads Programming By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell O'Reilly (pub) On the web: see the links at the bottom of the pthreads-win32 site: http://sources.redhat.com/pthreads-win32/ Acknowledgements ---------------- This library is based substantially on a Win32 pthreads implementation contributed by John Bossom . The implementation of Condition Variables uses algorithms developed by Alexander Terekhov and Louis Thomas. The implementation of POSIX mutexes has been improved by Thomas Pfaff. The implementation of read/write locks was contributed by Aurelio Medina and improved by Alexander Terekhov. Many others have contributed significant time and effort to solve critical problems in order to make the library workable, robust and reliable. There is also a separate CONTRIBUTORS file. This file and others are on the web site: http://sources.redhat.com/pthreads-win32 As much as possible, the ChangeLog file acknowledges contributions to the code base in more detail. Enjoy! Ross Johnson