pth.pod

Linux下的中文输入法

just raises a signal via raise(3) or kill(2), its delivered to an arbitrary
thread which has this signal not blocked.  With pth_raise(3) one can send a
signal to a thread and its guarantees that only this thread gets the signal
delivered. But keep in mind that nevertheless the signals I<action> is still
configured I<process>-wide.  When I<sig> is 0 plain thread checking is
performed, i.e., `C<pth_raise(tid, 0)>' returns C<TRUE> when thread I<tid>
still exists in the B<PTH> system but doesn't send any signal to it.

=item int B<pth_yield>(pth_t I<tid>);

This explicitly yields back the execution control to the scheduler thread.
Usually the execution is implicitly transferred back to the scheduler when a
thread waits for an event. But when a thread has to do larger CPU bursts, it
can be reasonable to interrupt it explicitly by doing a few pth_yield(3) calls
to give other threads a chance to execute, too.  This obviously is the
cooperating part of B<Pth>.  A thread I<has not> to yield execution, of
course. But when you want to program a server application with good response
times the threads should be cooperative, i.e., when they should split their CPU
bursts into smaller units with this call.

Usually one specifies I<tid> as C<NULL> to indicate to the scheduler that it
can freely decide which thread to dispatch next.  But if one wants to indicate
to the scheduler that a particular thread should be favored on the next
dispatching step, one can specify this thread explicitly. This allows the
usage of the old concept of I<coroutines> where a thread/routine switches to a
particular cooperating thread. If I<tid> is not C<NULL> and points to a I<new>
or I<ready> thread, it is guaranteed that this thread receives execution
control on the next dispatching step. If I<tid> is in a different state (that
is, not in C<PTH_STATE_NEW> or C<PTH_STATE_READY>) an error is reported.

The function usually returns C<TRUE> for success and only C<FALSE> (with
C<errno> set to C<EINVAL>) if I<tid> specified an invalid or still not
new or ready thread.

=item int B<pth_nap>(pth_time_t I<naptime>);

This functions suspends the execution of the current thread until I<naptime>
is elapsed. I<naptime> is of type C<pth_time_t> and this way has theoretically
a resolution of one microsecond. In practice you should neither rely on this
nor that the thread is awakened exactly after I<naptime> has elapsed. It's
only guarantees that the thread will sleep at least I<naptime>. But because
of the non-preemptive nature of B<Pth> it can last longer (when another thread
kept the CPU for a long time). Additionally the resolution is dependent of the
implementation of timers by the operating system and these usually have only a
resolution of 10 microseconds or larger. But usually this isn't important for
an application unless it tries to use this facility for real time tasks.

=item int B<pth_wait>(pth_event_t I<ev>);

This is the link between the scheduler and the event facility (see below for
the various pth_event_xxx() functions). It's modeled like select(2), i.e., one
gives this function one or more events (in the event ring specified by I<ev>)
on which the current thread wants to wait. The scheduler awakes the
thread when one ore more of them occurred or failed after tagging
them as such. The I<ev> argument is a I<pointer> to an event ring
which isn't changed except for the tagging. pth_wait(3) returns the
number of occurred or failed events and the application can use
pth_event_status(3) to test which events occurred or failed.

=item int B<pth_cancel>(pth_t I<tid>);

This cancels a thread I<tid>. How the cancellation is done depends on the
cancellation state of I<tid> which the thread can configure itself. When its
state is C<PTH_CANCEL_DISABLE> a cancellation request is just made pending.
When it is C<PTH_CANCEL_ENABLE> it depends on the cancellation type what is
performed. When its C<PTH_CANCEL_DEFERRED> again the cancellation request is
just made pending. But when its C<PTH_CANCEL_ASYNCHRONOUS> the thread is
immediately canceled before pth_cancel(3) returns. The effect of a thread
cancellation is equal to implicitly forcing the thread to call
`C<pth_exit(PTH_CANCELED)>' at one of his cancellation points.  In B<Pth>
thread enter a cancellation point either explicitly via pth_cancel_point(3) or
implicitly by waiting for an event.

=item int B<pth_abort>(pth_t I<tid>);

This is the cruel way to cancel a thread I<tid>. When it's already dead and
waits to be joined it just joins it (via `C<pth_join(>I<tid>C<, NULL)>') and
this way kicks it out of the system.  Else it forces the thread to be not
joinable and to allow asynchronous cancellation and then cancels it via
`C<pth_cancel(>I<tid>C<)>'.

=item int B<pth_join>(pth_t I<tid>, void **I<value>);

This joins the current thread with the thread specified via I<tid>.
It first suspends the current thread until the I<tid> thread has
terminated. Then it is awakened and stores the value of I<tid>'s
pth_exit(3) call into *I<value> (if I<value> and not C<NULL>) and
returns to the caller. A thread can be joined only when it has the
attribute C<PTH_ATTR_JOINABLE> set to C<TRUE> (the default). A thread
can only be joined once, i.e., after the pth_join(3) call the thread
I<tid> is completely removed from the system.

=item void B<pth_exit>(void *I<value>);

This terminates the current thread. Whether it's immediately removed
from the system or inserted into the dead queue of the scheduler depends
on its join type which was specified at spawning time. If it has the
attribute C<PTH_ATTR_JOINABLE> set to C<FALSE>, it's immediately removed
and I<value> is ignored. Else the thread is inserted into the dead queue
and I<value> remembered for a subsequent pth_join(3) call by another
thread.

=back

=head2 Utilities

Utility functions.

=over 4

=item int B<pth_fdmode>(int I<fd>, int I<mode>);

This switches the non-blocking mode flag on file descriptor I<fd>.  The
argument I<mode> can be C<PTH_FDMODE_BLOCK> for switching I<fd> into blocking
I/O mode, C<PTH_FDMODE_NONBLOCK> for switching I<fd> into non-blocking I/O
mode or C<PTH_FDMODE_POLL> for just polling the current mode. The current mode
is returned (either C<PTH_FDMODE_BLOCK> or C<PTH_FDMODE_NONBLOCK>) or
C<PTH_FDMODE_ERROR> on error. Keep in mind that since B<Pth> 1.1 there is no
longer a requirement to manually switch a file descriptor into non-blocking
mode in order to use it. This is automatically done temporarily inside B<Pth>.
Instead when you now switch a file descriptor explicitly into non-blocking
mode, pth_read(3) or pth_write(3) will never block the current thread.

=item pth_time_t B<pth_time>(long I<sec>, long I<usec>);

This is a constructor for a C<pth_time_t> structure which is a convenient
function to avoid temporary structure values. It returns a I<pth_time_t>
structure which holds the absolute time value specified by I<sec> and I<usec>.

=item pth_time_t B<pth_timeout>(long I<sec>, long I<usec>);

This is a constructor for a C<pth_time_t> structure which is a convenient
function to avoid temporary structure values.  It returns a I<pth_time_t>
structure which holds the absolute time value calculated by adding I<sec> and
I<usec> to the current time.

=item Sfdisc_t *B<pth_sfiodisc>(void);

This functions is always available, but only reasonably usable when B<Pth>
was built with B<Sfio> support (C<--with-sfio> option) and C<PTH_EXT_SFIO> is
then defined by C<pth.h>. It is useful for applications which want to use the
comprehensive B<Sfio> I/O library with the B<Pth> threading library. Then this
function can be used to get an B<Sfio> discipline structure (C<Sfdisc_t>)
which can be pushed onto B<Sfio> streams (C<Sfio_t>) in order to let this
stream use pth_read(3)/pth_write(2) instead of read(2)/write(2). The benefit
is that this way I/O on the B<Sfio> stream does only block the current thread
instead of the whole process. The application has to free(3) the C<Sfdisc_t>
structure when it is no longer needed. The Sfio package can be found at
http://www.research.att.com/sw/tools/sfio/.

=back

=head2 Cancellation Management

B<Pth> supports POSIX style thread cancellation via pth_cancel(3) and the
following two related functions:

=over 4

=item void B<pth_cancel_state>(int I<newstate>, int *I<oldstate>);

This manages the cancellation state of the current thread.  When I<oldstate>
is not C<NULL> the function stores the old cancellation state under the
variable pointed to by I<oldstate>. When I<newstate> is not C<0> it sets the
new cancellation state. I<oldstate> is created before I<newstate> is set.  A
state is a combination of C<PTH_CANCEL_ENABLE> or C<PTH_CANCEL_DISABLE> and
C<PTH_CANCEL_DEFERRED> or C<PTH_CANCEL_ASYNCHRONOUS>.
C<PTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED> (or C<PTH_CANCEL_DEFAULT>) is the
default state where cancellation is possible but only at cancellation points.
Use C<PTH_CANCEL_DISABLE> to complete disable cancellation for a thread and
C<PTH_CANCEL_ASYNCHRONOUS> for allowing asynchronous cancellations, i.e.,
cancellations which can happen at any time.

=item void B<pth_cancel_point>(void);

This explicitly enter a cancellation point. When the current cancellation
state is C<PTH_CANCEL_DISABLE> or no cancellation request is pending, this has
no side-effect and returns immediately. Else it calls
`C<pth_exit(PTH_CANCELED)>'.

=back

=head2 Event Handling

B<Pth> has a very flexible event facility which is linked into the scheduler
through the pth_wait(3) function. The following functions provide the handling
of event rings.

=over 4

=item pth_event_t B<pth_event>(unsigned long I<spec>, ...);

This creates a new event ring consisting of a single initial event.  The type
of the generated event is specified by I<spec>. The following types are
available:

=over 4

=item C<PTH_EVENT_FD>

This is a file descriptor event. One or more of C<PTH_UNTIL_FD_READABLE>,
C<PTH_UNTIL_FD_WRITEABLE> or C<PTH_UNTIL_FD_EXCEPTION> have to be OR-ed into
I<spec> to specify on which state of the file descriptor you want to wait.  The
file descriptor itself has to be given as an additional argument.  Example:
`C<pth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)>'.

=item C<PTH_EVENT_SELECT>

This is a multiple file descriptor event modeled directly after the select(2)
call (actually it is also used to implement pth_select(3) internally).  It's a
convenient way to wait for a large set of file descriptors at once and at each
file descriptor for a different type of state. Additionally as a nice
side-effect one receives the number of file descriptors which causes the event
to be occurred (using BSD semantics, i.e., when a file descriptor occurred in
two sets it's counted twice). The arguments correspond directly to the
select(2) function arguments except that there is no timeout argument (because
timeouts already can be handled via C<PTH_EVENT_TIME> events).

Example: `C<pth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)>' where
C<rc> has to be of type `C<int *>', C<nfd> has to be of type `C<int>' and
C<rfds>, C<wfds> and C<efds> have to be of type `C<fd_set *>' (see
select(2)). The number of occurred file descriptors are stored in C<rc>.

=item C<PTH_EVENT_SIGS>

This is a signal set event. The two additional arguments have to be a pointer
to a signal set (type `C<sigset_t *>') and a pointer to a signal number
variable (type `C<int *>').  This event waits until one of the signals in
the signal set occurred.  As a result the occurred signal number is stored in
the second additional argument. Keep in mind that the B<Pth> scheduler doesn't
block signals automatically.  So when you want to wait for a signal with this
event you've to block it via sigprocmask(2) or it will be delivered without
your notice. Example: `C<sigemptyset(&set); sigaddset(&set, SIGINT);
pth_event(PTH_EVENT_SIG, &set, &sig);>'.

=item C<PTH_EVENT_TIME>

This is a time point event. The additional argument has to be of type
C<pth_time_t> (usually on-the-fly generated via pth_time(3)). This events
waits until the specified time point has elapsed. Keep in mind that the value
is an absolute time point and not an offset. When you want to wait for a
specified amount of time, you've to add the current time to the offset
(usually on-the-fly achieved via pth_timeout(3)).  Example:
`C<pth_event(PTH_EVENT_TIME, pth_timeout(2,0))>'.

=item C<PTH_EVENT_MSG>

This is a message port event. The additional argument has to be of type
C<pth_msgport_t>. This events waits until one or more messages were received
on the specified message port.  Example: `C<pth_event(PTH_EVENT_MSG, mp)>'.

=item C<PTH_EVENT_TID>

This is a thread event. The additional argument has to be of type C<pth_t>.
One of C<PTH_UNTIL_TID_NEW>, C<PTH_UNTIL_TID_READY>, C<PTH_UNTIL_TID_WAITING>
or C<PTH_UNTIL_TID_DEAD> has to be OR-ed into I<spec> to specify on which
state of the thread you want to wait.  Example:
`C<pth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)>'.

=item C<PTH_EVENT_FUNC>

This is a custom callback function event. Three additional arguments
have to be given with the following types: `C<int (*)(void *)>',
`C<void *>' and `C<pth_time_t>'. The first is a function pointer to
a check function and the second argument is a user-supplied context
value which is passed to this function. The scheduler calls this
function on a regular basis (on his own scheduler stack, so be very
careful!) and the thread is kept sleeping while the function returns
C<FALSE>. Once it returned C<TRUE> the thread will be awakened. The
check interval is defined by the third argument, i.e., the check
function is polled again not until this amount of time elapsed. Example:
`C<pth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))>'.

=back

=item unsigned long B<pth_event_typeof>(pth_event_t I<ev>);

This returns the type of event I<ev>. It's a combination of the describing
C<PTH_EVENT_XX> and C<PTH_UNTIL_XX> value. This is especially useful to know
which arguments have to be supplied to the pth_event_extract(3) function.

=item int B<pth_event_extract>(pth_event_t I<ev>, ...);

When pth_event(3) is treated like sprintf(3), then this function is
sscanf(3), i.e., it is the inverse operation of pth_event(3). This means that
it can be used to extract the ingredients of an event.  The ingredients are
stored into variables which are given as pointers on the variable argument
list.  Which pointers have to be present depends on the event type and has to
be determined by the caller before via pth_event_typeof(3).

To make it clear, when you constructed I<ev> via `C<ev =
pth_event(PTH_EVENT_FD, fd);>' you have to extract it via
`C<pth_event_extract(ev, &fd)>', etc. For multiple arguments of an event the
order of the pointer arguments is the same as for pth_event(3). But always
keep in mind that you have to always supply I<pointers> to I<variables> and
these variables have to be of the same type as the argument of pth_event(3)
required.

=item pth_event_t B<pth_event_concat>(pth_event_t I<ev>, ...);

This concatenates one or more additional event rings to the event ring I<ev>
and returns I<ev>. The end of the argument list has to be marked with a
C<NULL> argument. Use this function to create real events rings out of the
single-event rings created by pth_event(3).

=item pth_event_t B<pth_event_isolate>(pth_event_t I<ev>);

This isolates the event I<ev> from possibly appended events in the event ring.
When in I<ev> only one event exists, this returns C<NULL>. When remaining