pth.pod

Linux下的中文输入法

`C<pth_kill(); exit(0)>' (which immediately kills the threading system and
terminates the process). The pth_kill() return immediately with a return
code of C<FALSE> if it is not called from within the main thread. Else it
kills the threading system and returns C<TRUE>.

=item long B<pth_ctrl>(unsigned long I<query>, ...);

This is a generalized query/control function for the B<Pth> library.  The
argument I<query> is a bitmask formed out of one or more C<PTH_CTRL_>I<XXXX>
queries. Currently the following queries are supported:

=over 4

=item C<PTH_CTRL_GETTHREADS>

This returns the total number of threads currently in existence.  This query
actually is formed out of the combination of queries for threads in a
particular state, i.e., the C<PTH_CTRL_GETTHREADS> query is equal to the
OR-combination of all the following specialized queries:

C<PTH_CTRL_GETTHREADS_NEW> for the number of threads in the
new queue (threads created via pth_spawn(3) but still not
scheduled once), C<PTH_CTRL_GETTHREADS_READY> for the number of
threads in the ready queue (threads who want to do CPU bursts),
C<PTH_CTRL_GETTHREADS_RUNNING> for the number of running threads
(always just one thread!), C<PTH_CTRL_GETTHREADS_WAITING> for
the number of threads in the waiting queue (threads waiting for
events), C<PTH_CTRL_GETTHREADS_SUSPENDED> for the number of
threads in the suspended queue (threads waiting to be resumed) and
C<PTH_CTRL_GETTHREADS_DEAD> for the number of threads in the new queue
(terminated threads waiting for a join).

=item C<PTH_CTRL_GETAVLOAD>

This requires a second argument of type `C<float *>' (pointer to a floating
point variable).  It stores a floating point value describing the exponential
averaged load of the scheduler in this variable. The load is a function from
the number of threads in the ready queue of the schedulers dispatching unit.
So a load around 1.0 means there is only one ready thread (the standard
situation when the application has no high load). A higher load value means
there a more threads ready who want to do CPU bursts. The average load value
updates once per second only. The return value for this query is always 0.

=item C<PTH_CTRL_GETPRIO>

This requires a second argument of type `C<pth_t>' which identifies a
thread.  It returns the priority (ranging from C<PTH_PRIO_MIN> to
C<PTH_PRIO_MAX>) of the given thread.

=item C<PTH_CTRL_GETNAME>

This requires a second argument of type `C<pth_t>' which identifies a
thread. It returns the name of the given thread, i.e., the return value of
pth_ctrl(3) should be casted to a `C<char *>'.

=item C<PTH_CTRL_DUMPSTATE>

This requires a second argument of type `C<FILE *>' to which a summary
of the internal B<Pth> library state is written to. The main information
which is currently written out is the current state of the thread pool.

=item C<PTH_CTRL_FAVOURNEW>

This requires a second argument of type `C<int>' which specified whether
the B<GNU Pth> scheduler favours new threads on startup, i.e., whether
they are moved from the new queue to the top (argument is C<TRUE>) or
middle (argument is C<FALSE>) of the ready queue. The default is to
favour new threads to make sure they do not starve already at startup,
although this slightly violates the strict priority based scheduling.

=back

The function returns C<-1> on error.

=item long B<pth_version>(void);

This function returns a hex-value `0xI<V>I<RR>I<T>I<LL>' which describes the
current B<Pth> library version. I<V> is the version, I<RR> the revisions,
I<LL> the level and I<T> the type of the level (alphalevel=0, betalevel=1,
patchlevel=2, etc). For instance B<Pth> version 1.0b1 is encoded as 0x100101.
The reason for this unusual mapping is that this way the version number is
steadily I<increasing>. The same value is also available under compile time as
C<PTH_VERSION>.

=back

=head2 Thread Attribute Handling

Attribute objects are used in B<Pth> for two things: First stand-alone/unbound
attribute objects are used to store attributes for to be spawned threads.
Bounded attribute objects are used to modify attributes of already existing
threads. The following attribute fields exists in attribute objects:

=over 4

=item C<PTH_ATTR_PRIO> (read-write) [C<int>]

Thread Priority between C<PTH_PRIO_MIN> and C<PTH_PRIO_MAX>.
The default is C<PTH_PRIO_STD>.

=item C<PTH_ATTR_NAME> (read-write) [C<char *>]

Name of thread (up to 40 characters are stored only), mainly for debugging
purposes.

=item C<PTH_ATTR_DISPATCHES> (read-write) [C<int>]

In bounded attribute objects, this field is incremented every time the
context is switched to the associated thread.

=item C<PTH_ATTR_JOINABLE> (read-write> [C<int>]

The thread detachment type, C<TRUE> indicates a joinable thread,
C<FALSE> indicates a detached thread. When a thread is detached,
after termination it is immediately kicked out of the system instead of
inserted into the dead queue.

=item C<PTH_ATTR_CANCEL_STATE> (read-write) [C<unsigned int>]

The thread cancellation state, i.e., a combination of C<PTH_CANCEL_ENABLE> or
C<PTH_CANCEL_DISABLE> and C<PTH_CANCEL_DEFERRED> or
C<PTH_CANCEL_ASYNCHRONOUS>.

=item C<PTH_ATTR_STACK_SIZE> (read-write) [C<unsigned int>]

The thread stack size in bytes. Use lower values than 64 KB with great care!

=item C<PTH_ATTR_STACK_ADDR> (read-write) [C<char *>]

A pointer to the lower address of a chunk of malloc(3)'ed memory for the
stack.

=item C<PTH_ATTR_TIME_SPAWN> (read-only) [C<pth_time_t>]

The time when the thread was spawned.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_TIME_LAST> (read-only) [C<pth_time_t>]

The time when the thread was last dispatched.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_TIME_RAN> (read-only) [C<pth_time_t>]

The total time the thread was running.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_START_FUNC> (read-only) [C<void *(*)(void *)>]

The thread start function.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_START_ARG> (read-only) [C<void *>]

The thread start argument.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_STATE> (read-only) [C<pth_state_t>]

The scheduling state of the thread, i.e., either C<PTH_STATE_NEW>,
C<PTH_STATE_READY>, C<PTH_STATE_WAITING>, or C<PTH_STATE_DEAD>
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_EVENTS> (read-only) [C<pth_event_t>]

The event ring the thread is waiting for.
This can be queried only when the attribute object is bound to a thread.

=item C<PTH_ATTR_BOUND> (read-only) [C<int>]

Whether the attribute object is bound (C<TRUE>) to a thread or not (C<FALSE>).

=back

The following API functions can be used to handle the attribute objects:

=over 4

=item pth_attr_t B<pth_attr_of>(pth_t I<tid>);

This returns a new attribute object I<bound> to thread I<tid>.  Any queries on
this object directly fetch attributes from I<tid>. And attribute modifications
directly change I<tid>. Use such attribute objects to modify existing threads.

=item pth_attr_t B<pth_attr_new>(void);

This returns a new I<unbound> attribute object. An implicit pth_attr_init() is
done on it. Any queries on this object just fetch stored attributes from it.
And attribute modifications just change the stored attributes.  Use such
attribute objects to pre-configure attributes for to be spawned threads.

=item int B<pth_attr_init>(pth_attr_t I<attr>);

This initializes an attribute object I<attr> to the default values:
C<PTH_ATTR_PRIO> := C<PTH_PRIO_STD>, C<PTH_ATTR_NAME> := `C<unknown>',
C<PTH_ATTR_DISPATCHES> := C<0>, C<PTH_ATTR_JOINABLE> := C<TRUE>,
C<PTH_ATTR_CANCELSTATE> := C<PTH_CANCEL_DEFAULT>,
C<PTH_ATTR_STACK_SIZE> := 64*1024 and
C<PTH_ATTR_STACK_ADDR> := C<NULL>. All other C<PTH_ATTR_*> attributes are
read-only attributes and don't receive default values in I<attr>, because they
exists only for bounded attribute objects.

=item int B<pth_attr_set>(pth_attr_t I<attr>, int I<field>, ...);

This sets the attribute field I<field> in I<attr> to a value
specified as an additional argument on the variable argument
list. The following attribute I<fields> and argument pairs can
be used:

 PTH_ATTR_PRIO           int
 PTH_ATTR_NAME           char *
 PTH_ATTR_DISPATCHES     int
 PTH_ATTR_JOINABLE       int
 PTH_ATTR_CANCEL_STATE   unsigned int
 PTH_ATTR_STACK_SIZE     unsigned int
 PTH_ATTR_STACK_ADDR     char *

=item int B<pth_attr_get>(pth_attr_t I<attr>, int I<field>, ...);

This retrieves the attribute field I<field> in I<attr> and stores its
value in the variable specified through a pointer in an additional
argument on the variable argument list. The following I<fields> and
argument pairs can be used:

 PTH_ATTR_PRIO           int *
 PTH_ATTR_NAME           char **
 PTH_ATTR_DISPATCHES     int *
 PTH_ATTR_JOINABLE       int *
 PTH_ATTR_CANCEL_STATE   unsigned int *
 PTH_ATTR_STACK_SIZE     unsigned int *
 PTH_ATTR_STACK_ADDR     char **
 PTH_ATTR_TIME_SPAWN     pth_time_t *
 PTH_ATTR_TIME_LAST      pth_time_t *
 PTH_ATTR_TIME_RAN       pth_time_t *
 PTH_ATTR_START_FUNC     void *(**)(void *)
 PTH_ATTR_START_ARG      void **
 PTH_ATTR_STATE          pth_state_t *
 PTH_ATTR_EVENTS         pth_event_t *
 PTH_ATTR_BOUND          int *

=item int B<pth_attr_destroy>(pth_attr_t I<attr>);

This destroys a attribute object I<attr>. After this I<attr> is no
longer a valid attribute object.

=back

=head2 Thread Control

The following functions control the threading itself and make up the main API
of the B<Pth> library.

=over 4

=item pth_t B<pth_spawn>(pth_attr_t I<attr>, void *(*I<entry>)(void *), void *I<arg>);

This spawns a new thread with the attributes given in I<attr> (or
C<PTH_ATTR_DEFAULT> for default attributes - which means that thread priority,
joinability and cancel state are inherited from the current thread) with the
starting point at routine I<entry>; the dispatch count is not inherited from
the current thread if I<attr> is not specified - rather, it is initialized
to zero.  This entry routine is called as `pth_exit(I<entry>(I<arg>))' inside
the new thread unit, i.e., I<entry>'s return value is fed to an implicit
pth_exit(3). So the thread can also exit by just returning. Nevertheless
the thread can also exit explicitly at any time by calling pth_exit(3). But
keep in mind that calling the POSIX function exit(3) still terminates the
complete process and not just the current thread.

There is no B<Pth>-internal limit on the number of threads one can spawn,
except the limit implied by the available virtual memory. B<Pth> internally
keeps track of thread in dynamic data structures. The function returns
C<NULL> on error.

=item int B<pth_once>(pth_once_t *I<ctrlvar>, void (*I<func>)(void *), void *I<arg>);

This is a convenience function which uses a control variable of type
C<pth_once_t> to make sure a constructor function I<func> is called only once
as `I<func>(I<arg>)' in the system. In other words: Only the first call to
pth_once(3) by any thread in the system succeeds. The variable referenced via
I<ctrlvar> should be declared as `C<pth_once_t> I<variable-name> =
C<PTH_ONCE_INIT>;' before calling this function.

=item pth_t B<pth_self>(void);

This just returns the unique thread handle of the currently running thread.
This handle itself has to be treated as an opaque entity by the application.
It's usually used as an argument to other functions who require an argument of
type C<pth_t>.

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

This suspends a thread I<tid> until it is manually resumed again via
pth_resume(3). For this, the thread is moved to the B<SUSPENDED> queue
and this way is completely out of the scheduler's event handling and
thread dispatching scope. Suspending the current thread is not allowed.
The function returns C<TRUE> on success and C<FALSE> on errors.

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

This function resumes a previously suspended thread I<tid>, i.e. I<tid>
has to stay on the B<SUSPENDED> queue. The thread is moved to the
B<NEW>, B<READY> or B<WAITING> queue (dependent on what its state was
when the pth_suspend(3) call were made) and this way again enters the
event handling and thread dispatching scope of the scheduler. The
function returns C<TRUE> on success and C<FALSE> on errors.

=item int B<pth_raise>(pth_t I<tid>, int I<sig>)

This function raises a signal for delivery to thread I<tid> only.  When one