pth.3

Linux下的中文输入法

.IP "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);" 4
.IX Item "int pth_nap(pth_time_t naptime);"
This functions suspends the execution of the current thread until \fInaptime\fR
is elapsed. \fInaptime\fR is of type \f(CW\*(C`pth_time_t\*(C'\fR 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 \fInaptime\fR has elapsed. It's
only guarantees that the thread will sleep at least \fInaptime\fR. But because
of the non-preemptive nature of \fBPth\fR it can last longer (when another thread
kept the \s-1CPU\s0 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.
.IP "int \fBpth_wait\fR(pth_event_t \fIev\fR);" 4
.IX Item "int pth_wait(pth_event_t ev);"
This is the link between the scheduler and the event facility (see below for
the various \fIpth_event_xxx()\fR functions). It's modeled like \fIselect\fR\|(2), i.e., one
gives this function one or more events (in the event ring specified by \fIev\fR)
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 \fIev\fR argument is a \fIpointer\fR to an event ring
which isn't changed except for the tagging. \fIpth_wait\fR\|(3) returns the
number of occurred or failed events and the application can use
\&\fIpth_event_status\fR\|(3) to test which events occurred or failed.
.IP "int \fBpth_cancel\fR(pth_t \fItid\fR);" 4
.IX Item "int pth_cancel(pth_t tid);"
This cancels a thread \fItid\fR. How the cancellation is done depends on the
cancellation state of \fItid\fR which the thread can configure itself. When its
state is \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR a cancellation request is just made pending.
When it is \f(CW\*(C`PTH_CANCEL_ENABLE\*(C'\fR it depends on the cancellation type what is
performed. When its \f(CW\*(C`PTH_CANCEL_DEFERRED\*(C'\fR again the cancellation request is
just made pending. But when its \f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR the thread is
immediately canceled before \fIpth_cancel\fR\|(3) returns. The effect of a thread
cancellation is equal to implicitly forcing the thread to call
`\f(CW\*(C`pth_exit(PTH_CANCELED)\*(C'\fR' at one of his cancellation points.  In \fBPth\fR
thread enter a cancellation point either explicitly via \fIpth_cancel_point\fR\|(3) or
implicitly by waiting for an event.
.IP "int \fBpth_abort\fR(pth_t \fItid\fR);" 4
.IX Item "int pth_abort(pth_t tid);"
This is the cruel way to cancel a thread \fItid\fR. When it's already dead and
waits to be joined it just joins it (via `\f(CW\*(C`pth_join(\*(C'\fR\fItid\fR\f(CW\*(C`, NULL)\*(C'\fR') 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
`\f(CW\*(C`pth_cancel(\*(C'\fR\fItid\fR\f(CW\*(C`)\*(C'\fR'.
.IP "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);" 4
.IX Item "int pth_join(pth_t tid, void **value);"
This joins the current thread with the thread specified via \fItid\fR.
It first suspends the current thread until the \fItid\fR thread has
terminated. Then it is awakened and stores the value of \fItid\fR's
\&\fIpth_exit\fR\|(3) call into *\fIvalue\fR (if \fIvalue\fR and not \f(CW\*(C`NULL\*(C'\fR) and
returns to the caller. A thread can be joined only when it has the
attribute \f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR set to \f(CW\*(C`TRUE\*(C'\fR (the default). A thread
can only be joined once, i.e., after the \fIpth_join\fR\|(3) call the thread
\&\fItid\fR is completely removed from the system.
.IP "void \fBpth_exit\fR(void *\fIvalue\fR);" 4
.IX Item "void pth_exit(void *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 \f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR set to \f(CW\*(C`FALSE\*(C'\fR, it's immediately removed
and \fIvalue\fR is ignored. Else the thread is inserted into the dead queue
and \fIvalue\fR remembered for a subsequent \fIpth_join\fR\|(3) call by another
thread.
.Sh "Utilities"
.IX Subsection "Utilities"
Utility functions.
.IP "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);" 4
.IX Item "int pth_fdmode(int fd, int mode);"
This switches the non-blocking mode flag on file descriptor \fIfd\fR.  The
argument \fImode\fR can be \f(CW\*(C`PTH_FDMODE_BLOCK\*(C'\fR for switching \fIfd\fR into blocking
I/O mode, \f(CW\*(C`PTH_FDMODE_NONBLOCK\*(C'\fR for switching \fIfd\fR into non-blocking I/O
mode or \f(CW\*(C`PTH_FDMODE_POLL\*(C'\fR for just polling the current mode. The current mode
is returned (either \f(CW\*(C`PTH_FDMODE_BLOCK\*(C'\fR or \f(CW\*(C`PTH_FDMODE_NONBLOCK\*(C'\fR) or
\&\f(CW\*(C`PTH_FDMODE_ERROR\*(C'\fR on error. Keep in mind that since \fBPth\fR 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 \fBPth\fR.
Instead when you now switch a file descriptor explicitly into non-blocking
mode, \fIpth_read\fR\|(3) or \fIpth_write\fR\|(3) will never block the current thread.
.IP "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);" 4
.IX Item "pth_time_t pth_time(long sec, long usec);"
This is a constructor for a \f(CW\*(C`pth_time_t\*(C'\fR structure which is a convenient
function to avoid temporary structure values. It returns a \fIpth_time_t\fR
structure which holds the absolute time value specified by \fIsec\fR and \fIusec\fR.
.IP "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);" 4
.IX Item "pth_time_t pth_timeout(long sec, long usec);"
This is a constructor for a \f(CW\*(C`pth_time_t\*(C'\fR structure which is a convenient
function to avoid temporary structure values.  It returns a \fIpth_time_t\fR
structure which holds the absolute time value calculated by adding \fIsec\fR and
\&\fIusec\fR to the current time.
.IP "Sfdisc_t *\fBpth_sfiodisc\fR(void);" 4
.IX Item "Sfdisc_t *pth_sfiodisc(void);"
This functions is always available, but only reasonably usable when \fBPth\fR
was built with \fBSfio\fR support (\f(CW\*(C`\-\-with\-sfio\*(C'\fR option) and \f(CW\*(C`PTH_EXT_SFIO\*(C'\fR is
then defined by \f(CW\*(C`pth.h\*(C'\fR. It is useful for applications which want to use the
comprehensive \fBSfio\fR I/O library with the \fBPth\fR threading library. Then this
function can be used to get an \fBSfio\fR discipline structure (\f(CW\*(C`Sfdisc_t\*(C'\fR)
which can be pushed onto \fBSfio\fR streams (\f(CW\*(C`Sfio_t\*(C'\fR) in order to let this
stream use \fIpth_read\fR\|(3)/\fIpth_write\fR\|(2) instead of \fIread\fR\|(2)/\fIwrite\fR\|(2). The benefit
is that this way I/O on the \fBSfio\fR stream does only block the current thread
instead of the whole process. The application has to \fIfree\fR\|(3) the \f(CW\*(C`Sfdisc_t\*(C'\fR
structure when it is no longer needed. The Sfio package can be found at
http://www.research.att.com/sw/tools/sfio/.
.Sh "Cancellation Management"
.IX Subsection "Cancellation Management"
\&\fBPth\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the
following two related functions:
.IP "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);" 4
.IX Item "void pth_cancel_state(int newstate, int *oldstate);"
This manages the cancellation state of the current thread.  When \fIoldstate\fR
is not \f(CW\*(C`NULL\*(C'\fR the function stores the old cancellation state under the
variable pointed to by \fIoldstate\fR. When \fInewstate\fR is not \f(CW0\fR it sets the
new cancellation state. \fIoldstate\fR is created before \fInewstate\fR is set.  A
state is a combination of \f(CW\*(C`PTH_CANCEL_ENABLE\*(C'\fR or \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR and
\&\f(CW\*(C`PTH_CANCEL_DEFERRED\*(C'\fR or \f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR.
\&\f(CW\*(C`PTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED\*(C'\fR (or \f(CW\*(C`PTH_CANCEL_DEFAULT\*(C'\fR) is the
default state where cancellation is possible but only at cancellation points.
Use \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR to complete disable cancellation for a thread and
\&\f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR for allowing asynchronous cancellations, i.e.,
cancellations which can happen at any time.
.IP "void \fBpth_cancel_point\fR(void);" 4
.IX Item "void pth_cancel_point(void);"
This explicitly enter a cancellation point. When the current cancellation
state is \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR or no cancellation request is pending, this has
no side-effect and returns immediately. Else it calls
`\f(CW\*(C`pth_exit(PTH_CANCELED)\*(C'\fR'.
.Sh "Event Handling"
.IX Subsection "Event Handling"
\&\fBPth\fR has a very flexible event facility which is linked into the scheduler
through the \fIpth_wait\fR\|(3) function. The following functions provide the handling
of event rings.
.IP "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);" 4
.IX Item "pth_event_t pth_event(unsigned long spec, ...);"
This creates a new event ring consisting of a single initial event.  The type
of the generated event is specified by \fIspec\fR. The following types are
available:
.RS 4
.ie n .IP """PTH_EVENT_FD""" 4
.el .IP "\f(CWPTH_EVENT_FD\fR" 4
.IX Item "PTH_EVENT_FD"
This is a file descriptor event. One or more of \f(CW\*(C`PTH_UNTIL_FD_READABLE\*(C'\fR,
\&\f(CW\*(C`PTH_UNTIL_FD_WRITEABLE\*(C'\fR or \f(CW\*(C`PTH_UNTIL_FD_EXCEPTION\*(C'\fR have to be OR-ed into
\&\fIspec\fR 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:
`\f(CW\*(C`pth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\*(C'\fR'.
.ie n .IP """PTH_EVENT_SELECT""" 4
.el .IP "\f(CWPTH_EVENT_SELECT\fR" 4
.IX Item "PTH_EVENT_SELECT"
This is a multiple file descriptor event modeled directly after the \fIselect\fR\|(2)
call (actually it is also used to implement \fIpth_select\fR\|(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 \s-1BSD\s0 semantics, i.e., when a file descriptor occurred in
two sets it's counted twice). The arguments correspond directly to the
\&\fIselect\fR\|(2) function arguments except that there is no timeout argument (because
timeouts already can be handled via \f(CW\*(C`PTH_EVENT_TIME\*(C'\fR events).
.Sp
Example: `\f(CW\*(C`pth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\*(C'\fR' where
\&\f(CW\*(C`rc\*(C'\fR has to be of type `\f(CW\*(C`int *\*(C'\fR', \f(CW\*(C`nfd\*(C'\fR has to be of type `\f(CW\*(C`int\*(C'\fR' and
\&\f(CW\*(C`rfds\*(C'\fR, \f(CW\*(C`wfds\*(C'\fR and \f(CW\*(C`efds\*(C'\fR have to be of type `\f(CW\*(C`fd_set *\*(C'\fR' (see
\&\fIselect\fR\|(2)). The number of occurred file descriptors are stored in \f(CW\*(C`rc\*(C'\fR.
.ie n .IP """PTH_EVENT_SIGS""" 4
.el .IP "\f(CWPTH_EVENT_SIGS\fR" 4
.IX Item "PTH_EVENT_SIGS"
This is a signal set event. The two additional arguments have to be a pointer
to a signal set (type `\f(CW\*(C`sigset_t *\*(C'\fR') and a pointer to a signal number
variable (type `\f(CW\*(C`int *\*(C'\fR').  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 \fBPth\fR scheduler doesn't
block signals automatically.  So when you want to wait for a signal with this
event you've to block it via \fIsigprocmask\fR\|(2) or it will be delivered without
your notice. Example: `\f(CW\*(C`sigemptyset(&set); sigaddset(&set, SIGINT);
pth_event(PTH_EVENT_SIG, &set, &sig);\*(C'\fR'.
.ie n .IP """PTH_EVENT_TIME""" 4
.el .IP "\f(CWPTH_EVENT_TIME\fR" 4
.IX Item "PTH_EVENT_TIME"
This is a time point event. The additional argument has to be of type
\&\f(CW\*(C`pth_time_t\*(C'\fR (usually on-the-fly generated via \fIpth_time\fR\|(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 \fIpth_timeout\fR\|(3)).  Example:
`\f(CW\*(C`pth_event(PTH_EVENT_TIME, pth_timeout(2,0))\*(C'\fR'.
.ie n .IP """PTH_EVENT_MSG""" 4
.el .IP "\f(CWPTH_EVENT_MSG\fR" 4
.IX Item "PTH_EVENT_MSG"
This is a message port event. The additional argument has to be of type
\&\f(CW\*(C`pth_msgport_t\*(C'\fR. This events waits until one or more messages were received
on the specified message port.  Example: `\f(CW\*(C`pth_event(PTH_EVENT_MSG, mp)\*(C'\fR'.
.ie n .IP """PTH_EVENT_TID""" 4
.el .IP "\f(CWPTH_EVENT_TID\fR" 4
.IX Item "PTH_EVENT_TID"
This is a thread event. The additional argument has to be of type \f(CW\*(C`pth_t\*(C'\fR.
One of \f(CW\*(C`PTH_UNTIL_TID_NEW\*(C'\fR, \f(CW\*(C`PTH_UNTIL_TID_READY\*(C'\fR, \f(CW\*(C`PTH_UNTIL_TID_WAITING\*(C'\fR
or \f(CW\*(C`PTH_UNTIL_TID_DEAD\*(C'\fR has to be OR-ed into \fIspec\fR to specify on which
state of the thread you want to wait.  Example:
`\f(CW\*(C`pth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\*(C'\fR'.
.ie n .IP """PTH_EVENT_FUNC""" 4
.el .IP "\f(CWPTH_EVENT_FUNC\fR" 4
.IX Item "PTH_EVENT_FUNC"
This is a custom callback function event. Three additional arguments
have to be given with the following types: `\f(CW\*(C`int (*)(void *)\*(C'\fR',
`\f(CW\*(C`void *\*(C'\fR' and `\f(CW\*(C`pth_time_t\*(C'\fR'. 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
\&\f(CW\*(C`FALSE\*(C'\fR. Once it returned \f(CW\*(C`TRUE\*(C'\fR 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:
`\f(CW\*(C`pth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\*(C'\fR'.
.RE
.RS 4
.RE
.IP "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);" 4
.IX Item "unsigned long pth_event_typeof(pth_event_t ev);"
This returns the type of event \fIev\fR. It's a combination of the describing
\&\f(CW\*(C`PTH_EVENT_XX\*(C'\fR and \f(CW\*(C`PTH_UNTIL_XX\*(C'\fR value. This is especially useful to know
which arguments have to be supplied to the \fIpth_event_extract\fR\|(3) function.
.IP "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);" 4
.IX Item "int pth_event_extract(pth_event_t ev, ...);"
When \fIpth_event\fR\|(3) is treated like \fIsprintf\fR\|(3), then this function is
\&\fIsscanf\fR\|(3), i.e., it is the inverse operation of \fIpth_event\fR\|(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 \fIpth_event_typeof\fR\|(3).
.Sp
To make it clear, when you constructed \fIev\fR via `\f(CW\*(C`ev =
pth_event(PTH_EVENT_FD, fd);\*(C'\fR' you have to extract it via
`\f(CW\*(C`pth_event_extract(ev, &fd)\*(C'\fR', etc. For multiple arguments of an event the
order of the pointer arguments is the same as for \fIpth_event\fR\|(3). But always
keep in mind that you have to always supply \fIpointers\fR to \fIvariables\fR and
these variables have to be of the same type as the argument of \fIpth_event\fR\|(3)
required.
.IP "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);" 4
.IX Item "pth_event_t pth_event_concat(pth_event_t ev, ...);"
This concatenates one or more additional event rings to the event ring \fIev\fR
and returns \fIev\fR. The end of the argument list has to be marked with a
\&\f(CW\*(C`NULL\*(C'\fR argument. Use this function to create real events rings out of the
single-event rings created by \fIpth_event\fR\|(3).
.IP "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);" 4
.IX Item "pth_event_t pth_event_isolate(pth_event_t ev);"
This isolates the event \fIev\fR from possibly appended events in the event ring.
When in \fIev\fR only one event exists, this returns \f(CW\*(C`NULL\*(C'\fR. When remaining
events