pth.pod

Linux下的中文输入法

events exists, they form a new event ring which is returned.

=item pth_event_t B<pth_event_walk>(pth_event_t I<ev>, int I<direction>);

This walks to the next (when I<direction> is C<PTH_WALK_NEXT>) or previews
(when I<direction> is C<PTH_WALK_PREV>) event in the event ring I<ev> and
returns this new reached event. Additionally C<PTH_UNTIL_OCCURRED> can be
OR-ed into I<direction> to walk to the next/previous occurred event in the
ring I<ev>.

=item pth_status_t B<pth_event_status>(pth_event_t I<ev>);

This returns the status of event I<ev>. This is a fast operation
because only a tag on I<ev> is checked which was either set or still
not set by the scheduler. In other words: This doesn't check the
event itself, it just checks the last knowledge of the scheduler. The
possible returned status codes are: C<PTH_STATUS_PENDING> (event is
still pending), C<PTH_STATUS_OCCURRED> (event successfully occurred),
C<PTH_STATUS_FAILED> (event failed).

=item int B<pth_event_free>(pth_event_t I<ev>, int I<mode>);

This deallocates the event I<ev> (when I<mode> is C<PTH_FREE_THIS>) or all
events appended to the event ring under I<ev> (when I<mode> is
C<PTH_FREE_ALL>).

=back

=head2 Key-Based Storage

The following functions provide thread-local storage through unique keys
similar to the POSIX B<Pthread> API. Use this for thread specific global data.

=over 4

=item int B<pth_key_create>(pth_key_t *I<key>, void (*I<func>)(void *));

This created a new unique key and stores it in I<key>.  Additionally I<func>
can specify a destructor function which is called on the current threads
termination with the I<key>.

=item int B<pth_key_delete>(pth_key_t I<key>);

This explicitly destroys a key I<key>.

=item int B<pth_key_setdata>(pth_key_t I<key>, const void *I<value>);

This stores I<value> under I<key>.

=item void *B<pth_key_getdata>(pth_key_t I<key>);

This retrieves the value under I<key>.

=back

=head2 Message Port Communication

The following functions provide message ports which can be used for efficient
and flexible inter-thread communication.

=over 4

=item pth_msgport_t B<pth_msgport_create>(const char *I<name>);

This returns a pointer to a new message port. If name I<name>
is not C<NULL>, the I<name> can be used by other threads via
pth_msgport_find(3) to find the message port in case they do not know
directly the pointer to the message port.

=item void B<pth_msgport_destroy>(pth_msgport_t I<mp>);

This destroys a message port I<mp>. Before all pending messages on it are
replied to their origin message port.

=item pth_msgport_t B<pth_msgport_find>(const char *I<name>);

This finds a message port in the system by I<name> and returns the pointer to
it.

=item int B<pth_msgport_pending>(pth_msgport_t I<mp>);

This returns the number of pending messages on message port I<mp>.

=item int B<pth_msgport_put>(pth_msgport_t I<mp>, pth_message_t *I<m>);

This puts (or sends) a message I<m> to message port I<mp>.

=item pth_message_t *B<pth_msgport_get>(pth_msgport_t I<mp>);

This gets (or receives) the top message from message port I<mp>.  Incoming
messages are always kept in a queue, so there can be more pending messages, of
course.

=item int B<pth_msgport_reply>(pth_message_t *I<m>);

This replies a message I<m> to the message port of the sender.

=back

=head2 Thread Cleanups

Per-thread cleanup functions.

=over 4

=item int B<pth_cleanup_push>(void (*I<handler>)(void *), void *I<arg>);

This pushes the routine I<handler> onto the stack of cleanup routines for the
current thread.  These routines are called in LIFO order when the thread
terminates.

=item int B<pth_cleanup_pop>(int I<execute>);

This pops the top-most routine from the stack of cleanup routines for the
current thread. When I<execute> is C<TRUE> the routine is additionally called.

=back

=head2 Process Forking

The following functions provide some special support for process forking
situations inside the threading environment.

=over 4

=item int B<pth_atfork_push>(void (*I<prepare>)(void *), void (*)(void *I<parent>), void (*)(void *I<child>), void *I<arg>);

This function declares forking handlers to be called before and after
pth_fork(3), in the context of the thread that called pth_fork(3). The
I<prepare> handler is called before fork(2) processing commences. The
I<parent> handler is called   after fork(2) processing completes in the parent
process.  The I<child> handler is called after fork(2) processing completed in
the child process. If no handling is desired at one or more of these three
points, the corresponding handler can be given as C<NULL>.  Each handler is
called with I<arg> as the argument.

The order of calls to pth_atfork_push(3) is significant. The I<parent> and
I<child> handlers are called in the order in which they were established by
calls to pth_atfork_push(3), i.e., FIFO. The I<prepare> fork handlers are
called in the opposite order, i.e., LIFO.

=item int B<pth_atfork_pop>(void);

This removes the top-most handlers on the forking handler stack which were
established with the last pth_atfork_push(3) call. It returns C<FALSE> when no
more handlers couldn't be removed from the stack.

=item pid_t B<pth_fork>(void);

This is a variant of fork(2) with the difference that the current thread only
is forked into a separate process, i.e., in the parent process nothing changes
while in the child process all threads are gone except for the scheduler and
the calling thread. When you really want to duplicate all threads in the
current process you should use fork(2) directly. But this is usually not
reasonable. Additionally this function takes care of forking handlers as
established by pth_fork_push(3).

=back

=head2 Synchronization

The following functions provide synchronization support via mutual exclusion
locks (B<mutex>), read-write locks (B<rwlock>), condition variables (B<cond>)
and barriers (B<barrier>). Keep in mind that in a non-preemptive threading
system like B<Pth> this might sound unnecessary at the first look, because a
thread isn't interrupted by the system. Actually when you have a critical code
section which doesn't contain any pth_xxx() functions, you don't need any
mutex to protect it, of course.

But when your critical code section contains any pth_xxx() function the chance
is high that these temporarily switch to the scheduler. And this way other
threads can make progress and enter your critical code section, too.  This is
especially true for critical code sections which implicitly or explicitly use
the event mechanism.

=over 4

=item int B<pth_mutex_init>(pth_mutex_t *I<mutex>);

This dynamically initializes a mutex variable of type `C<pth_mutex_t>'.
Alternatively one can also use static initialization via `C<pth_mutex_t
mutex = PTH_MUTEX_INIT>'.

=item int B<pth_mutex_acquire>(pth_mutex_t *I<mutex>, int I<try>, pth_event_t I<ev>);

This acquires a mutex I<mutex>.  If the mutex is already locked by another
thread, the current threads execution is suspended until the mutex is unlocked
again or additionally the extra events in I<ev> occurred (when I<ev> is not
C<NULL>).  Recursive locking is explicitly supported, i.e., a thread is allowed
to acquire a mutex more than once before its released. But it then also has be
released the same number of times until the mutex is again lockable by others.
When I<try> is C<TRUE> this function never suspends execution. Instead it
returns C<FALSE> with C<errno> set to C<EBUSY>.

=item int B<pth_mutex_release>(pth_mutex_t *I<mutex>);

This decrements the recursion locking count on I<mutex> and when it is zero it
releases the mutex I<mutex>.

=item int B<pth_rwlock_init>(pth_rwlock_t *I<rwlock>);

This dynamically initializes a read-write lock variable of type
`C<pth_rwlock_t>'.  Alternatively one can also use static initialization
via `C<pth_rwlock_t rwlock = PTH_RWLOCK_INIT>'.

=item int B<pth_rwlock_acquire>(pth_rwlock_t *I<rwlock>, int I<op>, int I<try>, pth_event_t I<ev>);

This acquires a read-only (when I<op> is C<PTH_RWLOCK_RD>) or a read-write
(when I<op> is C<PTH_RWLOCK_RW>) lock I<rwlock>. When the lock is only locked
by other threads in read-only mode, the lock succeeds.  But when one thread
holds a read-write lock, all locking attempts suspend the current thread until
this lock is released again. Additionally in I<ev> events can be given to let
the locking timeout, etc. When I<try> is C<TRUE> this function never suspends
execution. Instead it returns C<FALSE> with C<errno> set to C<EBUSY>.

=item int B<pth_rwlock_release>(pth_rwlock_t *I<rwlock>);

This releases a previously acquired (read-only or read-write) lock.

=item int B<pth_cond_init>(pth_cond_t *I<cond>);

This dynamically initializes a condition variable variable of type
`C<pth_cond_t>'.  Alternatively one can also use static initialization via
`C<pth_cond_t cond = PTH_COND_INIT>'.

=item int B<pth_cond_await>(pth_cond_t *I<cond>, pth_mutex_t *I<mutex>, pth_event_t I<ev>);

This awaits a condition situation. The caller has to follow the semantics of
the POSIX condition variables: I<mutex> has to be acquired before this
function is called. The execution of the current thread is then suspended
either until the events in I<ev> occurred (when I<ev> is not C<NULL>) or
I<cond> was notified by another thread via pth_cond_notify(3).  While the
thread is waiting, I<mutex> is released. Before it returns I<mutex> is
reacquired.

=item int B<pth_cond_notify>(pth_cond_t *I<cond>, int I<broadcast>);

This notified one or all threads which are waiting on I<cond>.  When
I<broadcast> is C<TRUE> all thread are notified, else only a single
(unspecified) one.

=item int B<pth_barrier_init>(pth_barrier_t *I<barrier>, int I<threshold>);

This dynamically initializes a barrier variable of type `C<pth_barrier_t>'.
Alternatively one can also use static initialization via `C<pth_barrier_t
barrier = PTH_BARRIER_INIT(>I<threadhold>C<)>'.

=item int B<pth_barrier_reach>(pth_barrier_t *I<barrier>);

This function reaches a barrier I<barrier>. If this is the last thread (as
specified by I<threshold> on init of I<barrier>) all threads are awakened.
Else the current thread is suspended until the last thread reached the barrier
and this way awakes all threads. The function returns (beside C<FALSE> on
error) the value C<TRUE> for any thread which neither reached the barrier as
the first nor the last thread; C<PTH_BARRIER_HEADLIGHT> for the thread which
reached the barrier as the first thread and C<PTH_BARRIER_TAILLIGHT> for the
thread which reached the barrier as the last thread.

=back

=head2 User-Space Context

The following functions provide a stand-alone sub-API for user-space
context switching. It internally is based on the same underlying machine
context switching mechanism the threads in B<GNU Pth> are based on.
Hence these functions you can use for implementing your own simple
user-space threads. The C<pth_uctx_t> context is somewhat modeled after
POSIX ucontext(3).

The time required to create (via pth_uctx_make(3)) a user-space context
can range from just a few microseconds up to a more dramatical time
(depending on the machine context switching method which is available on
the platform). On the other hand, the raw performance in switching the
user-space contexts is always very good (nearly independent of the used
machine context switching method). For instance, on an Intel Pentium-III
CPU with 800Mhz running under FreeBSD 4 one usually achieves about
260,000 user-space context switches (via pth_uctx_switch(3)) per second.

=over 4

=item int B<pth_uctx_create>(pth_uctx_t *I<uctx>);

This function creates a user-space context and stores it into I<uctx>.
There is still no underlying user-space context configured. You still
have to do this with pth_uctx_make(3). On success, this function returns
C<TRUE>, else C<FALSE>.

=item int B<pth_uctx_make>(pth_uctx_t I<uctx>, char *I<sk_addr>, size_t I<sk_size>, const sigset_t *I<sigmask>, void (*I<start_func>)(void *), void *I<start_arg>, pth_uctx_t I<uctx_after>);

This function makes a new user-space context in I<uctx> which will
operate on the run-time stack I<sk_addr> (which is of maximum
size I<sk_size>), with the signals in I<sigmask> blocked (if
I<sigmask> is not C<NULL>) and starting to execute with the call
I<start_func>(I<start_arg>). If I<sk_addr> is C<NULL>, a stack
is dynamically allocated. The stack size I<sk_size> has to be at
least 16384 (16KB). If the start function I<start_func> returns and
I<uctx_after> is not C<NULL>, an implicit user-space context switch
to this context is performed. Else (if I<uctx_after> is C<NULL>) the
process is terminated with exit(3). This function is somewhat modeled
after POSIX makecontext(3). On success, this function returns C<TRUE>,
else C<FALSE>.

=item int B<pth_uctx_switch>(pth_uctx_t I<uctx_from>, pth_uctx_t I<uctx_to>);

This function saves the current user-space context in I<uctx_from> for
later restoring by another call to pth_uctx_s