pth.pod

Linux下的中文输入法

##
##  GNU Pth - The GNU Portable Threads
##  Copyright (c) 1999-2004 Ralf S. Engelschall <[e-mail]>
##
##  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 Lesser General Public
##  License as published by the Free Software Foundation; either
##  version 2.1 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
##  Lesser General Public License for more details.
##
##  You should have received a copy of the GNU Lesser 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 <[e-mail]>.
##
##  pth.pod: Pth manual page
##

#                            ``Real programmers don't document.
#                              Documentation is for wimps who can't
#                              read the listings of the object deck.''

=pod

=head1 NAME

B<pth> - GNU Portable Threads

=head1 VERSION

GNU Pth PTH_VERSION_STR

=head1 SYNOPSIS

=over 4

=item B<Global Library Management>

pth_init,
pth_kill,
pth_ctrl,
pth_version.

=item B<Thread Attribute Handling>

pth_attr_of,
pth_attr_new,
pth_attr_init,
pth_attr_set,
pth_attr_get,
pth_attr_destroy.

=item B<Thread Control>

pth_spawn,
pth_once,
pth_self,
pth_suspend,
pth_resume,
pth_yield,
pth_nap,
pth_wait,
pth_cancel,
pth_abort,
pth_raise,
pth_join,
pth_exit.

=item B<Utilities>

pth_fdmode,
pth_time,
pth_timeout,
pth_sfiodisc.

=item B<Cancellation Management>

pth_cancel_point,
pth_cancel_state.

=item B<Event Handling>

pth_event,
pth_event_typeof,
pth_event_extract,
pth_event_concat,
pth_event_isolate,
pth_event_walk,
pth_event_status,
pth_event_free.

=item B<Key-Based Storage>

pth_key_create,
pth_key_delete,
pth_key_setdata,
pth_key_getdata.

=item B<Message Port Communication>

pth_msgport_create,
pth_msgport_destroy,
pth_msgport_find,
pth_msgport_pending,
pth_msgport_put,
pth_msgport_get,
pth_msgport_reply.

=item B<Thread Cleanups>

pth_cleanup_push,
pth_cleanup_pop.

=item B<Process Forking>

pth_atfork_push,
pth_atfork_pop,
pth_fork.

=item B<Synchronization>

pth_mutex_init,
pth_mutex_acquire,
pth_mutex_release,
pth_rwlock_init,
pth_rwlock_acquire,
pth_rwlock_release,
pth_cond_init,
pth_cond_await,
pth_cond_notify,
pth_barrier_init,
pth_barrier_reach.

=item B<User-Space Context>

pth_uctx_create,
pth_uctx_make,
pth_uctx_switch,
pth_uctx_destroy.

=item B<Generalized POSIX Replacement API>

pth_sigwait_ev,
pth_accept_ev,
pth_connect_ev,
pth_select_ev,
pth_poll_ev,
pth_read_ev,
pth_readv_ev,
pth_write_ev,
pth_writev_ev,
pth_recv_ev,
pth_recvfrom_ev,
pth_send_ev,
pth_sendto_ev.

=item B<Standard POSIX Replacement API>

pth_nanosleep,
pth_usleep,
pth_sleep,
pth_waitpid,
pth_system,
pth_sigmask,
pth_sigwait,
pth_accept,
pth_connect,
pth_select,
pth_pselect,
pth_poll,
pth_read,
pth_readv,
pth_write,
pth_writev,
pth_pread,
pth_pwrite,
pth_recv,
pth_recvfrom,
pth_send,
pth_sendto.

=back

=head1 DESCRIPTION

  ____  _   _
 |  _ \| |_| |__
 | |_) | __| '_ \         ``Only those who attempt
 |  __/| |_| | | |          the absurd can achieve
 |_|    \__|_| |_|          the impossible.''

B<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 application process, but each thread has
its own individual program counter, run-time stack, signal mask and C<errno>
variable.

The thread scheduling itself is done in a cooperative way, i.e., the threads
are managed and dispatched by a priority- and event-driven non-preemptive
scheduler. The intention is that this way both better portability and run-time
performance is achieved than with preemptive scheduling. The event facility
allows threads to wait until various types of internal and external events
occur, including pending I/O on file descriptors, asynchronous signals,
elapsed timers, pending I/O on message ports, thread and process termination,
and even results of customized callback functions.

B<Pth> also provides an optional emulation API for POSIX.1c threads
(`Pthreads') which can be used for backward compatibility to existing
multithreaded applications. See B<Pth>'s pthread(3) manual page for
details.

=head2 Threading Background

When programming event-driven applications, usually servers, lots of
regular jobs and one-shot requests have to be processed in parallel.
To efficiently simulate this parallel processing on uniprocessor
machines, we use `multitasking' -- that is, we have the application
ask the operating system to spawn multiple instances of itself. On
Unix, typically the kernel implements multitasking in a preemptive and
priority-based way through heavy-weight processes spawned with fork(2).
These processes usually do I<not> share a common address space. Instead
they are clearly separated from each other, and are created by direct
cloning a process address space (although modern kernels use memory
segment mapping and copy-on-write semantics to avoid unnecessary copying
of physical memory).

The drawbacks are obvious: Sharing data between the processes is
complicated, and can usually only be done efficiently through shared
memory (but which itself is not very portable). Synchronization is
complicated because of the preemptive nature of the Unix scheduler
(one has to use I<atomic> locks, etc). The machine's resources can be
exhausted very quickly when the server application has to serve too many
long-running requests (heavy-weight processes cost memory). And when
each request spawns a sub-process to handle it, the server performance
and responsiveness is horrible (heavy-weight processes cost time to
spawn). Finally, the server application doesn't scale very well with the
load because of these resource problems. In practice, lots of tricks
are usually used to overcome these problems - ranging from pre-forked
sub-process pools to semi-serialized processing, etc.

One of the most elegant ways to solve these resource- and data-sharing
problems is to have multiple I<light-weight> threads of execution
inside a single (heavy-weight) process, i.e., to use I<multithreading>.
Those I<threads> usually improve responsiveness and performance of the
application, often improve and simplify the internal program structure,
and most important, require less system resources than heavy-weight
processes. Threads are neither the optimal run-time facility for all
types of applications, nor can all applications benefit from them. But
at least event-driven server applications usually benefit greatly from
using threads.

=head2 The World of Threading

Even though lots of documents exists which describe and define the world
of threading, to understand B<Pth>, you need only basic knowledge about
threading. The following definitions of thread-related terms should at
least help you understand thread programming enough to allow you to use
B<Pth>.

=over 2

=item B<o> B<process> vs. B<thread>

A process on Unix systems consists of at least the following fundamental
ingredients: I<virtual memory table>, I<program code>, I<program
counter>, I<heap memory>, I<stack memory>, I<stack pointer>, I<file
descriptor set>, I<signal table>. On every process switch, the kernel
saves and restores these ingredients for the individual processes. On
the other hand, a thread consists of only a private program counter,
stack memory, stack pointer and signal table. All other ingredients, in
particular the virtual memory, it shares with the other threads of the
same process.

=item B<o> B<kernel-space> vs. B<user-space> threading

Threads on a Unix platform traditionally can be implemented either
inside kernel-space or user-space. When threads are implemented by the
kernel, the thread context switches are performed by the kernel without
the application's knowledge. Similarly, when threads are implemented in
user-space, the thread context switches are performed by an application
library, without the kernel's knowledge. There also are hybrid threading
approaches where, typically, a user-space library binds one or more
user-space threads to one or more kernel-space threads (there usually
called light-weight processes - or in short LWPs).

User-space threads are usually more portable and can perform faster
and cheaper context switches (for instance via swapcontext(2) or
setjmp(3)/longjmp(3)) than kernel based threads. On the other hand,
kernel-space threads can take advantage of multiprocessor machines and
don't have any inherent I/O blocking problems. Kernel-space threads are
usually scheduled in preemptive way side-by-side with the underlying
processes. User-space threads on the other hand use either preemptive or
non-preemptive scheduling.

=item B<o> B<preemptive> vs. B<non-preemptive> thread scheduling

In preemptive scheduling, the scheduler lets a thread execute until a
blocking situation occurs (usually a function call which would block)
or the assigned timeslice elapses. Then it detracts control from the
thread without a chance for the thread to object. This is usually
realized by interrupting the thread through a hardware interrupt