##
##  pthread.pod -- POSIX.1c Threads ("pthreads") manual page for Pth
##
##  Copyright (c) 1999 Ralf S. Engelschall <rse@engelschall.com>
##
##  This file is part of GNU Pth, a non-preemptive thread scheduling
##  library which can be found at http://www.gnu.org/software/pth/.
##
##  This library is free software; you can redistribute it and/or
##  modify it under the terms of the GNU Library General Public
##  License as published by the Free Software Foundation; either
##  version 2 of the License, or (at your option) any later version.
##
##  This library is distributed in the hope that it will be useful,
##  but WITHOUT ANY WARRANTY; without even the implied warranty of
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
##  Library General Public License for more details.
##
##  You should have received a copy of the GNU Library General Public
##  License along with this library; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
##  USA, or contact Ralf S. Engelschall <rse@engelschall.com>.
##

=pod

=head1 NAME

B<pthread> - POSIX.1c Threading API of GNU Pth

=head1 VERSION

GNU Pth PTH_VERSION_STR

=head1 SYNOPSIS

B<Application Makefile>

 #   manually
 CFLAGS=-I/path/to/pth/include
 LDFLAGS=-L/path/to/pth/lib
 LIBS=-lpthread

 #   automatically
 CFLAGS=`pthread-config --cflags`
 LDFLAGS=`pthread-config --ldflags`
 LIBS=`pthread-config --libs`

B<All(!) application sources>

 #include <pthread.h>

=head1 DESCRIPTION

=head2 Overview

This is the IEEE Std. 1003.1c ("POSIX.1c") conforming threading API of GNU
Portable Threads (B<Pth>). This API is commonly known as ``I<POSIX threads>''
or in short ``I<pthreads>''. It is provided by B<Pth> with the intention of
backward compatibility to existing multithreaded applications.  It is
implemented by mapping the various pthread API functions to the corresponding
B<Pth> API functions.

=head2 Notes

A few notes which you should keep in mind when working with the B<Pth> pthread
API.

=over 4

=item B<Non-Preemptive Scheduling>

First you've to always remember when working with this pthread library that it
uses non-preeptive scheduling, because it's directly based on B<Pth> (B<Pth> for
portability reasons is a pure non-preemptive thread scheduling system).  So
there is no implicit yielding of execution control and you cannot expect great
concurrency in your application, of course.  Nevertheless the responsiveness
and concurrency of an event driven application is increased greatly.

=item B<No System Call Wrappers>

The underlaying B<Pth> library is an I<explicit> API which (mainly for
portability reasons) does not perform any magic to prevent blocking system
calls from blocking the whole process (instead of just the thread). In B<Pth> one
explicitly has to use non-blocking filedescriptors and pth_read() instead of
read(), etc. So expect a blocking system call to block your whole process
unless you use it in non-blocking mode or you have C<pthread.h> included in
all(!) your source files.  This way you get some ``C<#define>''s which map
some important system functions to the B<Pth> equivalents.

=item B<Conflicts with Vendor Implementation>

There can be a conflict between the B<Pth> pthread.h and a possibly existing
vendor pthread.h header which was implicitly included by some standard vendor
headers. When this occurs try to ``#define'' header-dependent values which
prevent the inclusion of the vendor header.

=back

=head2 Further Reading

First there is a small document included in the B<Pth> source tree, C<pthread.ps>
from Sun Microsystems Inc, which is a very concise summary of the pthread API.
Use this for a quick reference. 

Then there is ``I<The Single UNIX Specification, Version 2 - Threads>'', from
I<The Open Group> of 1997 under http://www.opengroup.org/onlinepubs
/007908799/xsh/threads.html.  This is a very complete publically available
description of the pthread API. Use this when you need details for free. 

Third, you can also buy the official standard from IEEE. It's IEEE POSIX
1003.1c-1995 standard (also known as ISO/IEC 9945-1:1996), which is available
as part of the ANSI/IEEE 1003.1, 1996 edition, standard. 

Finally you can look at the files C<pthread.c> and C<pthread.h> in the B<Pth>
source tree for details of the implementation.  

=head1 SEE ALSO

pthread-config(1), pth(3).

=head1 AUTHOR

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut

