mingw32 pthreads-w32
========================================================================
This project seeks to provide a freely available and high-quality
implementation of pthreads for Windows. Pthreads is an API for writing
multithreaded applications following the POSIX standard.

Two versions are supplied:
  1. pthreadGC2.dll    (C cleanup code)
  2. pthreadGCE2.dll   (C++ cleanup code)
The first version is used by default. To use the C++ version, link
with -lpthreadGCE2 rather than -lpthreadGC or -lpthread.  Note that most
platforms' pthread implementations, even when used with C++, follow
the C cleanup model. Read the pthreads-win32 documentation before
experimenting with the C++ version.

The preferred way to link to this library is by using the -lpthread link
flag.

Runtime requirements:
  None
  QueueUserAPCEx-install.exe (optional [*])
  
Build requirements:
  MinGW Compiler
    binutils-2.21-1-mingw32-bin.tar.gz
    gcc-core-4.5.2-1-mingw32-bin.tar.lzma
    gcc-c++-4.5.2-1-mingw32-bin.tar.lzma
    libgcc-4.5.2-1-mingw32-dll-1.tar.lzma
    libstdc++-4.5.2-1-mingw32-dll-6.tar.lzma
    libgomp-4.5.2-1-mingw32-dll-1.tar.lzma
    gmp-5.0.1-1-mingw32-dev.tar.lzma
    libgmp-5.0.1-1-mingw32-dll-10.tar.lzma
    libmpfr-2.4.1-1-mingw32-dll-1.tar.lzma
    mingwrt-3.18-mingw32-dev.tar.gz
    mingwrt-3.18-mingw32-dll.tar.gz
    w32api-3.17-mingw32-dev.tar.gz

  MSYS Environment
    msys-bash-bin
    msys-coreutils-bin
    msys-diffutils-bin
    msys-findutils-bin
    msys-patch-bin
    msys-gawk-bin
    msys-grep-bin
    msys-gzip-bin
    msys-liblzma-dll
    msys-lndir-bin
    msys-make-bin
    msys-core-bin
    msys-sed-bin
    msys-tar-bin
    msys-xz-bin
    msys-perl-bin

[*] QueueUserAPCEx-install.exe -- this package installs the
    alertdrv.sys driver and starts it.  This kernel mode driver is
    used by pthreads-win32, if available, to work around some issues
    related to canceling pthreads during "non interruptible" win32
    calls.  Supposedly this improves the behavior of the GCE
    implementation, but the difference is slight -- see Test Results
    below.

    For more information, see
      http://www.codeproject.com/KB/threads/QueueUserAPCEx_v2.aspx
    and the release notes accompanying QueueUserAPCEx-install.exe
    which is available at mingw.org.


Canonical homepage:
  http://sourceware.org/pthreads-win32/

Canonical download:
  ftp://sourceware.org/pub/pthreads-win32
  cvs -d:pserver:anoncvs@sourceware.org:/cvs/pthreads-win32 co -D 2011-03-12 pthreads

License:
  LGPLv2.1

Language:
  C

========================================================================

Build instructions:
  unpack pthreads-w32-$VER-$REL-mingw32-src.tar.lzma
  <path-to-source>/pkgbuild
See <path-to-source>/pkgbuild -h for further options.

This will create:
  pthreads-w32-$VER-$REL-mingw32-dev.tar.lzma
  libpthreadgc-$VER-$REL-mingw32-dll-2.tar.lzma
  libpthreadgce-$VER-$REL-mingw32-dll-2.tar.lzma
  libquserex-$VER-$REL-mingw32-dll.tar.lzma
  pthreads-w32-$VER-$REL-mingw32-doc.tar.lzma
  pthreads-w32-$VER-$REL-mingw32-lic.tar.lzma

========================================================================

Test suite results (GC, both with and without alertdrv):
------------------------------------------------------------
TEST SUMMARY: 135 tests passed, and 0 tests failed or were skipped


  
Test suite results (GCX, both with and without alertdrv):
------------------------------------------------------------
Note that the 'GCX' test uses the GC pthreads library (that is, C-style
cleanup code), in conjunction C++ clients that throw exceptions.  Good
performance on this test demonstrates that the GCE library is not stricly
necessary for C++ applications.

TEST SUMMARY: 135 tests passed, and 0 tests failed or were skipped



Test suite results (GCE, without alertdrv):
------------------------------------------------------------

TEST SUMMARY: 120 tests passed, and 15 tests failed or were skipped
FAILED TESTS: condvar7 condvar8 condvar9 cancel3 cancel4 cancel5
              cancel6a cancel6d cleanup0 cleanup1 cleanup2 cleanup3
	      exception1 exception2 exception3

However, some of these tests WOULD have passed, if they hadn't been
skipped due to failures of earlier tests.  Here's the breakdown:

REAL FAILS:      cancel3 cancel5 cancel6a cleanup1 exception1 exception3
SKIPS THAT PASS: condvar7 condvar8 condvar9 cancel4 cancel6d cleanup0
                 cleanup2 cleanup3 exception2
TEST SUMMARY: 129 tests passed, and 6 tests failed.



Test suite results (GCE, with alertdrv):
------------------------------------------------------------

TEST SUMMARY: 119 tests passed, and 16 tests failed or were skipped
FAILED TESTS: condvar7 condvar8 condvar9 cancel3 cancel4 cancel5
              cancel6a cancel6d cleanup0 cleanup1 cleanup2 cleanup3
              exception1 exception2 exception3 cancel9

As before, some of these tests WOULD have passed, if they hadn't been
skipped due failures of earlier tests. However, cancel9 is a "new"
failure.  Reason is: if alertdrv is not running:
	$ ./cancel9
	Alertable async cancel not available.
And the test "passes".  If alertdrv IS running:
	$ ./cancel9
	Cancel sleeping thread.
	terminate called after throwing an instance of 'ptw32_exception_cancel'

	This application has requested the Runtime to terminate it in an unusual way.
	Please contact the application's support team for more information.

Breakdown below:

REAL FAILS:      cancel3 cancel5 cancel6a cleanup1 exception1 exception3 cancel9
SKIPS THAT PASS: condvar7 condvar8 condvar9 cancel4 cancel6d cleanup0
                 cleanup2 cleanup3 exception2
TEST SUMMARY: 128 tests passed, and 7 tests failed.

The errors seem to be due, in most cases, to uncaught ptw32_exception_cancel
exceptions (like the cancel9 case above)
    terminate called after throwing an instance of 'ptw32_exception_cancel'
    This application has requested the Runtime to terminate it in an unusual way.
    Please contact the application's support team for more information.
Not sure why...needs more debugging.


There are a few things worth noting, with regards to the GCE library:

First, MOST things work -- but its compliance is definitely inferior to
the GC library, *even* when the GC library is used by C++ clients.

Second, the alertdrv appears not to have ANY beneficial effect AT ALL.
Now, we know that the alertdrv, when properly installed and started, CAN
be communicated with -- the difference in the output of cancel9.exe, when
linked with GCE demonstrates that:
   with alertdrv:    throws an unhandled exception
   without alertdrv: reports 'Alertable async cancel not available.'
cancel9 determines this by querying the pthread library -- which will only
return true when (a) the quserex.dll library was successfully loaded,
(b) the appropriate symbols FROM that library were located, and (c)
calling the initialization function IN that library returned success --
and THAT function will only return success if it was able to open a
handle to the driver.  So, we KNOW that cancel9.exe was able to verify
that the driver was installed and started...but it appears that it doesn't
actually solve any of the problems GCE has!

The same tests that failed, in GCE w/o alertdrv, continue to fail; the
ones that pass continue to pass -- with the exception of cancel9 itself,
because it "skips" the meat of the test when alertdrv is not present (and,
apparently, when alertdrv IS present...the meat of the test fails.)

Not good.

I'd suspect that alertdrv was broken, except that its own test program
passes, on the same machine.  Unless you really enjoy debugging kernel-
mode drivers, then I suggest sticking with the GC library...

FYI -- quserex-test.exe results (without alertdrv.sys):

	$ ./quserex_test.exe
	QueueUserAPCEx_Init failed: Can't get a handle to the ALERT driver
	XXX [Thread 6196] Starting
	[Thread 6196] Sending an APC to myself
	[Thread 6196] Inside APC routine with argument (33)
	[Thread 4944] Calling Sleep...
	[Thread 6196] Sending an APC to the thread that called Sleep
	QueueUserAPCEx failed!

...and it hangs, so you have to CTRL-C it.  However, the results with
alertdrv.sys are as expected:

	$ ./quserex_test.exe
	XXX [Thread 3768] Starting
	[Thread 3768] Sending an APC to myself
	[Thread 3768] Inside APC routine with argument (33)
	[Thread 6984] Calling Sleep...
	[Thread 3768] Sending an APC to the thread that called Sleep
	[Thread 6984] Inside APC routine with argument (44)
	[Thread 6984] Exiting!
	[Thread 7864] Calling WaitForSingleObject...
	[Thread 3768] Sending an APC to the thread that called WaitForSingleObject
	[Thread 7864] Inside APC routine with argument (55)
	[Thread 7864] WaitForSingleObject returned 192
	[Thread 7864] Exiting!
	[Thread 3768] Exiting
 
========================================================================
Change History
----------  pthreads-w32-2.9.0-*-pre-20110507-2 -- 2011 May 20 -----------
* Copy pthreadGC's import library to both libpthread.dll.a AND to
  libpthread.a, so that -lpthread works as expected even when gcc's
  -static option is used.

----------  pthreads-w32-2.9.0-*-pre-20110507-1 -- 2011 May 10 -----------
* Update to more recent snapshot (after upstream merge of 'robust mutexes')
* Rework versioning structure in package name for mingw-get harmony
* Test also pthreadGC2 (C cleanup) with C++ clients.
* Expand documentation
* Add quserex-test.exe application

----------  pthreads-w32-20110312-1 (unpublished)-- 2011 May 06 -----------
* Rename DLL to same as upstream (pthreadGC2.dll)
* Also ship GCE version

----------  pthreads-w32-2.8.0-3 -- 2010 Feb 17 -----------
* Adopt the literal upstream project name as the package id.
* Add self-test option and report tests results.
* To create the build environment, use lndir instead of recursive copy.

----------  pthreads_w32-2.8.0-2 -- 2010 Feb 16 -----------
* Enable the "inlined" option.

----------  pthreads_w32-2.8.0-1 -- 2010 Feb 15 -----------
* First release.
