[1.7] ITP: pth

[Charles Wilson <cygwin at cwilson dot fastmail dot fm>]

Pth is a very portable POSIX/ANSI-C based library for Unix platforms
which provides non-preemptive priority-based scheduling for multiple
threads of execution (aka `multithreading') inside event-driven
applications. All threads run in the same address space of the server
application, but each thread has its own individual program-counter,
run-time stack, signal mask and errno variable.

That is, GNU Pth is a user-mode threading library.

At present, pth on cygwin does not allow the use of fork() in client
applications, so it has been disabled:
  pth_fork() always returns -1 with errno=ENOSYS
  fork() is redirected by pth.h to call pth_fork()
See fork-bug/README (attached) for more information.

pth is a prerequisite for (unmodified) GnuPG2 and libassuan.  This build
passes all internal self-tests, but has one known cygwin-specific
deficiency as mentioned above. The distribution includes a test case in
/usr/share/doc/pth/fork-bug/.  If you don't use fork(), pth works fine
and is generally quite a bit faster (and supposedly more secure) than
native threads such as pthreads.

pth is included in debian stable and testing:
http://packages.debian.org/search?keywords=pth
and Fedora 11
https://admin.fedoraproject.org/pkgdb/packages/name/pth?#Fedora11


http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/libpth-devel/libpth-devel-2.0.7-2.tar.bz2
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/libpth-devel/setup.hint
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/libpth20/libpth20-2.0.7-2.tar.bz2
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/libpth20/setup.hint
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/pth-2.0.7-2-src.tar.bz2
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/pth-2.0.7-2.tar.bz2
http://cygutils.fruitbat.org/ITP-gnupg2/release/pth/setup.hint


====== pth setup.hint =====
requires: libpth20
category: Doc
sdesc: "GNU Pth - The GNU Portable Threads (doc)"
ldesc: "Pth is a very portable POSIX/ANSI-C based library for
Unix platforms which provides non-preemptive priority-based
scheduling for multiple threads of execution (aka multithreading)
inside event-driven applications. It is a user-mode threading
library."

====== libpth20 setup.hint =====
requires: libgcc1
category: Libs
external-source: pth
sdesc: "GNU Pth - The GNU Portable Threads (runtime)"
ldesc: "Pth is a very portable POSIX/ANSI-C based library for
Unix platforms which provides non-preemptive priority-based
scheduling for multiple threads of execution (aka multithreading)
inside event-driven applications. It is a user-mode threading
library."

====== libpth-devel setup.hint =====
requires: libpth20
category: Devel Libs
external-source: pth
sdesc: "GNU Pth - The GNU Portable Threads (devel)"
ldesc: "Pth is a very portable POSIX/ANSI-C based library for
Unix platforms which provides non-preemptive priority-based
scheduling for multiple threads of execution (aka multithreading)
inside event-driven applications. It is a user-mode threading
library."

OK?

--
Chuck

At present, using pth on cygwin, with fork(), does not work.
This is because pth manually modifies the stack in each "thread"
after a fork -- which stomps all over the modifications that
cygwin itself does when managing the fork process.

The two sample programs in this directory demonstrate the problem:
pthreads-fork works as expected:

  $ pthreads-fork
  FORKPARENT: mypid=7132 childpid=7352
  FORKCHILD: mypid=7352
  $

However, pth-fork does not (when using an unmodified pth library):

  $ pth-fork
  FORKPARENT: mypid=7132 childpid=7352
  $

The parent 'thinks' that the fork succeeded and the child pid is
as returned by the fork() call. However, the child has actually
died precisely as it returned from fork() in its process context,
thanks to the nasty things Pth did to the stack of the forkee.

Therefore, this version of pth disables fork() as follows:
  pth_fork() always returns -1 with errno=ENOSYS
  fork() is redirected by pth.h to call pth_fork()

With the modified library, the behavior of pth-fork is:

  $ pth-fork
  FORKFAILED

Which makes a little more sense. It's not going to work, so we
might as well tell the user right away, rather than letting the
parent /think/ the child actually exists. If you'd like to re-
enable pth_fork -- to try and debug/fix Pth itself (please do!) --
there are a few things you should know.  See below.




This "disable fork()" behavior is not foolproof, because files within
the application that do not #include pth.h could still call the system
fork() directly, which will probably lead to hard-to-diagnose errors.
If you must use fork(), and you're SURE you're only going to do so
before initializing or using Pth, AND the file in which you are going
to call fork must #include pth, then you can force the use of system
fork by:
  1) #undef PTH_SYSCALL_SOFT before #including pth.h
  2) or use something like this:
        #if defined(__CYGWIN__) && defined(PTH_H) && defined(fork)
        #  undef fork
        #  define pth_fork_redir
        #endif
           pid = fork();
        #if defined(__CYGWIN__) && defined(PTH_H) && defined(pth_fork_redir)
        # undef pth_fork_redir
        # define fork pth_fork
        #endif
For more information, see
  http://cygwin.com/ml/cygwin/2009-10/msg00466.html
and the preceding thread
  http://cygwin.com/ml/cygwin/2009-10/threads.html#00420


TURNING FORK() BACK ON
=========================================================================
If you'd like to try and fix Pth+fork, you'll need to recompile Pth with
   CPPFLAGS="-DPTH_DISABLE_FORK=0 -ggdb3 -O0"
(you are going to debug it, right? How else can you fix it?).  You should
install the new version of the library, to ensure that the build procedure
for the pth-fork example finds the new version of the library.

Note that the Right Way To Fix Pth is for cygwin itself to implement
the sigstack() and sigaltstack() system calls.  This has been promised
for sometime after cygwin-1.7.1 is released.  At that time, then it
should simply be a matter of modifying the configure.ac file so that
Pth detects and uses that functionality on cygwin.  That is, you should
see

   decision on mctx implementation... sjlj/*/sas

where * is one of {ssjlj sjlj usjlj}.  Currently, we see:

   decision on mctx implementation... sjlj/sjljw32/none

However, until then, the only way to "fix" Pth is to add a brand new
sjljcygwin type, and muck around with pth_mctx_set() in pth_mctx.c
to "fiddle with the jmp_buf" correctly -- on cygwin by adding a sixth
machine context variant.