From d14156f2c1d4a9db64cfef0370883db8930e3a6b Mon Sep 17 00:00:00 2001 From: rpj Date: Sat, 2 Mar 2002 05:00:44 +0000 Subject: Changes to documentation and makefiles. --- ANNOUNCE | 490 ++++++++++----------------------------------------------------- 1 file changed, 75 insertions(+), 415 deletions(-) (limited to 'ANNOUNCE') diff --git a/ANNOUNCE b/ANNOUNCE index 7e47bd4..795eec0 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -1,8 +1,8 @@ - PTHREADS-WIN32 SNAPSHOT 2002-??-?? - ---------------------------------- - Web Site: http://sources.redhat.com/pthreads-win32/ - FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 - Coordinator: Ross Johnson + PTHREADS-WIN32 SNAPSHOT 2002-03-02 + ---------------------------------- + Web Site: http://sources.redhat.com/pthreads-win32/ + FTP Site: ftp://sources.redhat.com/pub/pthreads-win32 + Maintainer: Ross Johnson We are pleased to announce the availability of a new snapshot of @@ -23,366 +23,43 @@ Please see the 'Acknowledgements' section at the end of this announcement for the list of contributors. -------------------------------- -Changes since the last snapshot -------------------------------- +Acknowledgements +---------------- +This library is based substantially on a Win32 pthreads +implementation contributed by John Bossom . -Cleanup code default style. (IMPORTANT) ----------------------------------------------------------------------- -Previously, if not defined, the cleanup style was determined automatically -from the compiler/language, 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 private.c). - -In short, the exceptions versions of the library throw an exception -when a thread is canceled or exits (via pthread_exit()), which 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 and future snapshots, 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 -current commercial Unix POSIX threads implementations. Compaq's TRU64 -may be an exception (no pun intended) and possible future trend. - -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 - -E.g. regardless of whether your app is C or C++, if you link with -pthreadVC.lib or libpthreadGC.a, then you must define __CLEANUP_C. - - -THE POINT OF ALL THIS IS: if you have not been defining one of these -explicitly, then the defaults as described at the top of this -section were being used. - -THIS NOW CHANGES, as has been explained above, but to try to make this -clearer here's an example: - -If you were building your application with MSVC++ i.e. using C++ -exceptions and not explicitly defining one of __CLEANUP_*, then -__CLEANUP_C++ was automatically defined for you in pthread.h. -You should have been linking with pthreadVCE.dll, which does -stack unwinding. - -If you now build your application as you had before, pthread.h will now -automatically set __CLEANUP_C as the default style, and you will need to -link with pthreadVC.dll. Stack unwinding will now NOT occur when a thread -is canceled, or the thread calls pthread_exit(). - -Your application will now most likely behave differently to previous -versions, and in non-obvious ways. Most likely is that locally -instantiated objects may not be destroyed or cleaned up after a thread -is canceled. - -If you want the same behaviour as before, then you must now define -__CLEANUP_C++ explicitly using a compiler option and link with -pthreadVCE.dll as you did before. - - -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 threads platform -you use. Or at least this is the hope. - - -WHY NOT REMOVE THE EXCEPTIONS VERSIONS OF THE LIBRARY ALTOGETHER? -There are a few reasons: -- because there are well respected POSIX threads people who believe - that POSIX threads implementations should be exceptions aware and - do the expected thing in that context. (There are equally respected - people who believe it should not be easily accessible, if it's there - at all, for unconditional conformity to other implementations.) -- because pthreads-win32 is one of the few implementations that has - the choice, perhaps the only freely available one, and so offers - a laboratory to people who may want to explore the effects; -- although the code will always be around somewhere for anyone who - wants it, once it's removed from the current version it will not be - nearly as visible to people who may have a use for it. - - -Source module splitting ------------------------ -In order to enable smaller image sizes to be generated -for applications that link statically with the library, -most routines have been separated out into individual -source code files. - -This is being done in such a way as to be backward compatible. -The old source files are reused to congregate the individual -routine files into larger translation units (via a bunch of -# includes) so that the compiler can still optimise wherever -possible, e.g. through inlining, which can only be done -within the same translation unit. - -It is also possible to build the entire library by compiling -the single file named "pthread.c", which just #includes all -the secondary congregation source files. The compiler -may be able to use this to do more inlining of routines. - -Although the GNU compiler is able to produce libraries with -the necessary separation (the -ffunction-segments switch), -AFAIK, the MSVC and other compilers don't have this feature. - -Finally, since I use makefiles and command-line compilation, -I don't know what havoc this reorganisation may wreak amongst -IDE project file users. You should be able to continue -using your existing project files without modification. - - -New non-portable function -------------------------- -pthread_num_processors_np(): Returns the number of processors -in the system that are available to the process, as determined -from the processor affinity mask. - - -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. - - -New standard routines ---------------------- -For source code portability only - rwlocks cannot be process shared yet. - - pthread_rwlockattr_init() - pthread_rwlockattr_destroy() - pthread_rwlockattr_setpshared() - pthread_rwlockattr_getpshared() - -As defined in the new POSIX standard, and the Single Unix Spec version 3: - - sem_timedwait() - pthread_mutex_timedlock() - Alexander Terekhov and Thomas Pfaff - pthread_rwlock_timedrdlock() - adapted from pthread_rwlock_rdlock() - pthread_rwlock_timedwrlock() - adapted from pthread_rwlock_wrlock() - - -New non-portable routine ------------------------- -To improve tolerance against operator or time service initiated -system clock changes, the following routine is provided: - - pthread_timechange_handler_np() - -This routine can be called by an application when it -receives a WM_TIMECHANGE message from the system. At present -it broadcasts all condition variables so that waiting threads -can wake up and re-evaluate their conditions and restart -their timed waits if required. -- Suggested by Alexander Terekhov - - -pthread.h no longer includes windows.h --------------------------------------- -[Not yet for G++] - -This was done to prevent conflicts. - -HANDLE, DWORD, and NULL are temporarily defined within pthread.h if -they are not already. - - -pthread.h, sched.h and semaphore.h now use dllexport/dllimport --------------------------------------------------------------- -Not only to avoid the need for the pthread.def file, but to -improve performance. Apparently, declaring functions with dllimport -generates a direct call to the function and avoids the overhead -of a stub function call. - -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 - -* Found a fix for the library and workaround for applications for -the known bug #2, i.e. where __CLEANUP_CXX or __CLEANUP_SEH is defined. -See the "Known Bugs in this snapshot" section below. - -This could be made transparent to applications by replacing the macros that -define the current C++ and SEH versions of pthread_cleanup_push/pop -with the C version, but AFAIK cleanup handlers would not then run in the -correct sequence with destructors and exception cleanup handlers when -an exception occurs. - -* Cancelation once started in a thread cannot now be inadvertantly -double canceled. That is, once a thread begins it's cancelation run, -cancelation is disabled and a subsequent cancel request will -return an error (ESRCH). - - ---------------------------- -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. - - Notes from the MSVC++ manual: - 1) A term_func() should call exit(), otherwise - abort() will be called on return to the caller. - A call to abort() raises SIGABRT and the default signal handler - for all signals terminates the calling program with - exit code 3. - 2) A term_func() must not throw an exception. Therefore - term_func() should not call pthread_exit(), which - works by throwing an exception (pthreadVCE or pthreadVSE) - or by calling longjmp (pthreadVC). - - Workaround: avoid using pthread_exit() in C++ applications. Exit - threads by dropping through the end of the thread routine. - -2. Cancellation problems in optimised code - - Milan Gardian +The implementation of Condition Variables uses algorithms developed +by Alexander Terekhov and Louis Thomas. - Workaround [rpj - 2 Feb 2002] - ----------------------------- - The problem disappears when /Ob0 is used, i.e. /O2 /Ob0 works OK, - but if you want to use inlining optimisation you can be much more - specific about where it's switched off and on by using a pragma. - - So the inlining optimisation is interfering with the way that cleanup - handlers are run. It appears to relate to auto-inlining of class methods - since this is the only auto inlining that is performed at /O1 optimisation - (functions with the "inline" qualifier are also inlined, but the problem - doesn't appear to involve any such functions in the library or testsuite). - - In order to confirm the inlining culprit, the following use of pragmas - eliminate the problem but I don't know how to make it transparent, putting - it in, say, pthread.h where pthread_cleanup_push defined as a macro. - - #pragma inline_depth(0) - pthread_cleanup_push(handlerFunc, (void *) &arg); - - /* ... */ - - pthread_cleanup_pop(0); - #pragma inline_depth() - - Note the empty () pragma value after the pop macro. This resets depth to the - default. Or you can specify a non-zero depth here. - - The pragma is also needed (and now used) within the library itself wherever - cleanup handlers are used (condvar.c and rwlock.c). - - Use of these pragmas allows compiler optimisations /O1 and /O2 to be - used for either or both the library and applications. - - Experimenting further, I found that wrapping the actual cleanup handler - function with #pragma auto_inline(off|on) does NOT work. - - MSVC6.0 doesn't appear to support the C99 standard's _Pragma directive, - however, later versions may. This form is embeddable inside #define - macros, which would be ideal because it would mean that it could be added - to the push/pop macro definitions in pthread.h and hidden from the - application programmer. - - [/rpj] - - Original problem description - ---------------------------- - - 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) +The implementation of POSIX mutexes has been improved by Thomas Pfaff. - 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. +The implementation of Spinlocks and Barriers was contributed +by Ross Johnson. -3. errno - - Under MSVC, errno isn't working. +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 crutial +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. -Special notes -------------- - -1. [See also the discussion in the FAQ file - Q2, Q4, and Q5] -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, if your application contains catch(...) blocks in your POSIX -threads then you will need to replace the "catch(...)" with the macro -"PtW32Catch", eg. +Changes since the last snapshot +------------------------------- +These are now documented in the NEWS file. +See the ChangeLog file also. - #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. +Known Bugs +---------- +These are now documented in the BUGS file. Level of standards conformance @@ -436,7 +113,7 @@ The following functions are implemented: pthread_setcancelstate pthread_setcanceltype pthread_testcancel - + --------------------------- Thread Specific Data --------------------------- @@ -444,7 +121,7 @@ The following functions are implemented: pthread_key_delete pthread_setspecific pthread_getspecific - + --------------------------- Mutexes --------------------------- @@ -454,9 +131,9 @@ The following functions are implemented: pthread_mutexattr_setpshared pthread_mutexattr_gettype pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT - PTHREAD_MUTEX_NORMAL - PTHREAD_MUTEX_ERRORCHECK - PTHREAD_MUTEX_RECURSIVE ) + PTHREAD_MUTEX_NORMAL + PTHREAD_MUTEX_ERRORCHECK + PTHREAD_MUTEX_RECURSIVE ) pthread_mutex_init pthread_mutex_destroy pthread_mutex_lock @@ -525,10 +202,10 @@ The following functions are implemented: sem_wait sem_trywait sem_timedwait - sem_open (returns an error ENOSYS) - sem_close (returns an error ENOSYS) - sem_unlink (returns an error ENOSYS) - sem_getvalue (returns an error ENOSYS) + 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 @@ -564,16 +241,16 @@ The following functions are implemented: pthread_timechange_handler_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_MUTEX_ADAPTIVE_NP, - PTHREAD_MUTEX_TIMED_NP) + pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP, + PTHREAD_MUTEX_ERRORCHECK_NP, + PTHREAD_MUTEX_RECURSIVE_NP, + PTHREAD_MUTEX_ADAPTIVE_NP, + PTHREAD_MUTEX_TIMED_NP) pthread_num_processors_np - pthread_win32_process_attach_np (Required when statically linking the library) - pthread_win32_process_detach_np (Required when statically linking the library) - pthread_win32_thread_attach_np (Required when statically linking the library) - pthread_win32_thread_detach_np (Required when statically linking the library) + pthread_win32_process_attach_np (Required when statically linking the library) + pthread_win32_process_detach_np (Required when statically linking the library) + pthread_win32_thread_attach_np (Required when statically linking the library) + pthread_win32_thread_detach_np (Required when statically linking the library) --------------------------- Static Initializers @@ -606,7 +283,7 @@ The following functions are not implemented: pthread_mutex_attr_getprotocol pthread_mutex_attr_setprioceiling pthread_mutex_attr_setprotocol - + --------------------------- Fork Handlers --------------------------- @@ -619,7 +296,7 @@ The following functions are not implemented: ftrylockfile funlockfile getc_unlocked - getchar_unlocked + getchar_unlocked putc_unlocked putchar_unlocked @@ -675,7 +352,7 @@ Mailing List There is a mailing list for discussing pthreads on Win32. To join, send email to: - pthreads-win32-subscribe@sourceware.cygnus.com + pthreads-win32-subscribe@sourceware.cygnus.com Application Development Environments @@ -690,7 +367,7 @@ MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your applicatio Mingw32: -See FAQ Questions 6 and 10. +See the FAQ, Questions 6 and 10. Mingw using C++ EH works. Distribute pthreadGCE.dll with your application. Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application. @@ -712,7 +389,7 @@ For convenience, the following pre-built files are available on the FTP site pthread.h - for POSIX 1c threads semaphore.h - for POSIX 1b semaphores - sched.h - for POSIX 1b scheduling + 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 @@ -721,62 +398,45 @@ For convenience, the following pre-built files are available on the FTP site 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 + libpthreadGCE.a - derived from pthreadGCE.dll libpthreadGC.a - derived from pthreadGC.dll - gcc.dll - needed if distributing applications that use pthreadGCE.dll + gcc.dll - needed if distributing applications that use + pthreadGCE.dll (but see the FAQ Q 10 for the latest + related information) 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 the authoritative reference, see the online POSIX +standard reference: + + http://www.UNIX-systems.org/version3/ieee_std.html For POSIX Thread API programming, several reference books are -available: +available: - Programming with POSIX Threads - David R. Butenhof - Addison-Wesley (pub) + Programming with POSIX Threads + David R. Butenhof + Addison-Wesley (pub) - Pthreads Programming - By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell - O'Reilly (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. + http://sources.redhat.com/pthreads-win32/ -There is also a separate CONTRIBUTORS file. This file and others are -on the web site: + Currently, there is no documentation included in the package apart + from the copious comments in the source code. - http://sources.redhat.com/pthreads-win32 -As much as possible, the ChangeLog file acknowledges contributions to the -code base in more detail. Enjoy! -- cgit v1.2.3