path: root/ANNOUNCE

                 PTHREADS-WIN32 SNAPSHOT 2000-12-29
                 ----------------------------------
       Web Site: http://sources.redhat.com/pthreads-win32/
      FTP Site: ftp://sources.redhat.com/pub/pthreads-win32
        Coordinator: Ross Johnson <rpj@ise.canberra.edu.au>


We are pleased to announce the availability of a new snapshot of
Pthreads-win32, 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.

Pthreads-win32 is free software, distributed under the GNU Library
General Public License (LGPL).

Please see the 'Acknowledgements' section at the end of this
announcement for the list of contributors.


Change Summary (since the last snapshot)
----------------------------------------

(See the ChangeLog file for details.)

New:
-	New non-portable functions for use when statically linking the library
	(see the README file):
		pthread_delay_np
		pthread_win32_process_attach_np
		pthread_win32_process_detach_np
		pthread_win32_thread_attach_np
		pthread_win32_thread_detach_np
	Also, the start of support within the library for statically
	linked applications, but this has not been tested by statically
	linking yet.
-	A fully working MinGW32 g++ compiled version of the library
	is now supplied. To use with g++ compiled applications
	please see the FAQ "How do I generate pthreadGCE.dll and
	libpthreadw32.a for use with Mingw32", which you need to do
	before compiling and linking applications as well.
-	Unhandled exceptions, whether SEH or C++, are no longer
	silently caught and ignored but are passed out of threads for
	the system to deal with. C++ applications can override
	the default termination handler via set_terminate().
	set_terminate() works fine for MinGW32 g++ but not yet with MS VC++
	(see known bugs (2)) even though it's the same code. See
	tests/exception3.c for an example of using set_terminate().

Bugs fixed:
-	Pthread_mutex_unlock() now returns EPERM if the unlocking
	thread does not currently hold the thread.
-	Args in the ctime_r macro in pthread.h are fixed.
-	Made semaphore.h independent of config.h when building
	applications. Don't know how this went unnoticed for so long
	- the default defines must have been correct for my test
	environment.

Some new tests have been added.


Known bugs in this snapshot
---------------------------

1. Asynchronous cancelation only works on Intel X86 machines.

2. 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() -
   makes an explicit call to terminate() which works as expected
   under MinGW32 g++ doesn't appear to run the term_func under
   MC VC++ 6.0.

3. This is an interim snapshot as there are still some additional
   patches to go in, eg. to fix problems with errno support under
   some circumstances. Some people are seeing compile warnings
   to do with _errno.

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 1995 options are defined:

      _POSIX_THREADS
      _POSIX_THREAD_SAFE_FUNCTIONS
      _POSIX_THREAD_ATTR_STACKSIZE


The following POSIX 1003.1c 1995 options are not defined:

      _POSIX_THREAD_ATTR_STACKADDR
      _POSIX_THREAD_PRIORITY_SCHEDULING
      _POSIX_THREAD_PRIO_INHERIT
      _POSIX_THREAD_PRIO_PROTECT
      _POSIX_THREAD_PROCESS_SHARED

The following POSIX 1003.1b option is defined:

      _POSIX_SEMAPHORES

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_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:
      ---------------------------
      pthread_rwlock_init
      pthread_rwlock_destroy
      pthread_rwlock_tryrdlock
      pthread_rwlock_trywrlock
      pthread_rwlock_rdlock
      pthread_rwlock_rwlock
      pthread_rwlock_unlock

      ---------------------------
      Semaphores
      ---------------------------
      sem_init               (POSIX 1b)
      sem_destroy            (POSIX 1b)
      sem_post               (POSIX 1b)
      sem_wait               (POSIX 1b)
      sem_trywait            (POSIX 1b)
      sem_open               (POSIX 1b - returns an error ENOSYS)
      sem_close              (POSIX 1b - returns an error ENOSYS)
      sem_unlink             (POSIX 1b - returns an error ENOSYS)
      sem_getvalue           (POSIX 1b - returns an error ENOSYS)

      ---------------------------
      RealTime Scheduling
      ---------------------------
      pthread_attr_getschedparam  
      pthread_attr_setschedparam  
      pthread_getschedparam
      pthread_setschedparam
      sched_get_priority_max (POSIX 1b)
      sched_get_priority_min (POSIX 1b)
      sched_yield            (POSIX 1b)

      ---------------------------
      Signals
      ---------------------------
      pthread_sigmask

      ---------------------------
      Non-portable routines (see the README file for usage)
      ---------------------------
      pthread_mutexattr_setforcecs_np
      pthread_getw32threadhandle_np
	pthread_delay_np
	pthread_win32_process_attach_np
	pthread_win32_process_detach_np
	pthread_win32_thread_attach_np
	pthread_win32_thread_detach_np

      ---------------------------
      Static Initializers (macros)
      ---------------------------
      PTHREAD_ONCE_INIT
      PTHREAD_MUTEX_INITIALIZER
      PTHREAD_COND_INITIALIZER
      PTHREAD_RWLOCK_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_attr_getinheritsched
      pthread_attr_getschedpolicy
      pthread_attr_getscope
      pthread_attr_setinheritsched
      pthread_attr_setschedpolicy
      pthread_attr_setscope
      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
------------------------------------
      
MSVC:
MSVC using SEH works.
MSVC using C++ EH works.

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

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
	pthreadVSE.dll	- built with MSVC compiler using SEH
	pthreadVSE.lib
	pthreadGCE.dll	- built with Mingw32 G++
	libpthreadw32.a	- derived from 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.


Building the library with MSVC from source
------------------------------------------

A simple makefile for building the library with MSVC is available. Just
run nmake in a command shell in the pthreads source directory for targets
to make either the VSE or VCE version of the library. Eg:

	cd <PTHREADS_ROOT>\pthreads
	nmake clean VSE
or
	nmake clean VCE

There are currently no nmake targets to make statically linked
versions of the library.

Building the library with MinGW32 from source
---------------------------------------------

Run make in the pthreads source directory. Ie:

	cd <PTHREADS_ROOT>\pthreads
	make clean
	make

The GNU make utility will find the GNUmakefile in the pthreads source
directory.


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)
      

Acknowledgements
----------------
      
This library is based substantially on a Win32 pthreads
implementation contributed by John Bossom <John.Bossom@cognos.com>.
      
The implementation of condition variables is derived from the work
of Douglas Schmidt et al
(http://www.cs.wustl.edu/~schmidt/win32-cv-1.html).

There is also a separate CONTRIBUTORS file. This file and others are
on the web site:

        http://sources.redhat.com/pthreads-win32

Enjoy!

Ross Johnson