--- pth.3 2001/03/24 16:30:36 1.230
+++ pth.3 2001/07/12 07:20:04 1.231
@@ -1,5 +1,5 @@
-.\" Automatically generated by Pod::Man version 1.02
-.\" Sat Mar 24 17:29:24 2001
+.\" Automatically generated by Pod::Man version 1.15
+.\" Thu Jul 12 09:19:00 2001
.\"
.\" Standard preamble:
.\" ======================================================================
@@ -46,8 +46,8 @@
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
-. ds C` `
-. ds C' '
+. ds C` ""
+. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
@@ -63,7 +63,7 @@
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
-. .
+..
. nr % 0
. rr F
.\}
@@ -675,7 +675,8 @@
argument \fIquery\fR is a bitmask formed out of one or more \f(CW\*(C`PTH_CTRL_\*(C'\fR\fI\s-1XXXX\s0\fR
queries. Currently the following queries are supported:
.RS 4
-.Ip "\f(CW\*(C`PTH_CTRL_GETTHREADS\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_CTRL_GETTHREADS""""\fR" 4
+.el .Ip "\f(CWPTH_CTRL_GETTHREADS\fR" 4
.IX Item "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
@@ -693,7 +694,8 @@
threads in the suspended queue (threads waiting to be resumed) and
\&\f(CW\*(C`PTH_CTRL_GETTHREADS_DEAD\*(C'\fR for the number of threads in the new queue
(terminated threads waiting for a join).
-.Ip "\f(CW\*(C`PTH_CTRL_GETAVLOAD\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_CTRL_GETAVLOAD""""\fR" 4
+.el .Ip "\f(CWPTH_CTRL_GETAVLOAD\fR" 4
.IX Item "PTH_CTRL_GETAVLOAD"
This requires a second argument of type `\f(CW\*(C`float *\*(C'\fR' (pointer to a floating
point variable). It stores a floating point value describing the exponential
@@ -703,17 +705,20 @@
situation when the application has no high load). A higher load value means
there a more threads ready who want to do \s-1CPU\s0 bursts. The average load value
updates once per second only. The return value for this query is always 0.
-.Ip "\f(CW\*(C`PTH_CTRL_GETPRIO\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_CTRL_GETPRIO""""\fR" 4
+.el .Ip "\f(CWPTH_CTRL_GETPRIO\fR" 4
.IX Item "PTH_CTRL_GETPRIO"
This requires a second argument of type `\f(CW\*(C`pth_t\*(C'\fR' which identifies a
thread. It returns the priority (ranging from \f(CW\*(C`PTH_PRIO_MIN\*(C'\fR to
\&\f(CW\*(C`PTH_PRIO_MAX\*(C'\fR) of the given thread.
-.Ip "\f(CW\*(C`PTH_CTRL_GETNAME\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_CTRL_GETNAME""""\fR" 4
+.el .Ip "\f(CWPTH_CTRL_GETNAME\fR" 4
.IX Item "PTH_CTRL_GETNAME"
This requires a second argument of type `\f(CW\*(C`pth_t\*(C'\fR' which identifies a
thread. It returns the name of the given thread, i.e., the return value of
\&\fIpth_ctrl\fR\|(3) should be casted to a `\f(CW\*(C`char *\*(C'\fR'.
-.Ip "\f(CW\*(C`PTH_CTRL_DUMPSTATE\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_CTRL_DUMPSTATE""""\fR" 4
+.el .Ip "\f(CWPTH_CTRL_DUMPSTATE\fR" 4
.IX Item "PTH_CTRL_DUMPSTATE"
This requires a second argument of type `\f(CW\*(C`FILE *\*(C'\fR' to which a summary
of the internal \fBPth\fR library state is written to. The main information
@@ -738,61 +743,75 @@
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:
-.Ip "\f(CW\*(C`PTH_ATTR_PRIO\*(C'\fR (read-write) [\f(CW\*(C`int\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_PRIO""""\fR (read-write) [\f(CW""""int""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]" 4
.IX Item "PTH_ATTR_PRIO (read-write) [int]"
Thread Priority between \f(CW\*(C`PTH_PRIO_MIN\*(C'\fR and \f(CW\*(C`PTH_PRIO_MAX\*(C'\fR.
The default is \f(CW\*(C`PTH_PRIO_STD\*(C'\fR.
-.Ip "\f(CW\*(C`PTH_ATTR_NAME\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_NAME""""\fR (read-write) [\f(CW""""char *""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" 4
.IX Item "PTH_ATTR_NAME (read-write) [char *]"
Name of thread (up to 40 characters are stored only), mainly for debugging
purposes.
-.Ip "\f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR (read-write> [\f(CW\*(C`int\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_JOINABLE""""\fR (read-write> [\f(CW""""int""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]" 4
.IX Item "PTH_ATTR_JOINABLE (read-write> [int]"
The thread detachment type, \f(CW\*(C`TRUE\*(C'\fR indicates a joinable thread, \f(CW\*(C`FALSE\*(C'\fR
indicates a detached thread. When a the is detached after termination it is
immediately kicked out of the system instead of inserted into the dead queue.
-.Ip "\f(CW\*(C`PTH_ATTR_CANCEL_STATE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_CANCEL_STATE""""\fR (read-write) [\f(CW""""unsigned int""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]" 4
.IX Item "PTH_ATTR_CANCEL_STATE (read-write) [unsigned int]"
The thread cancellation state, i.e., 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.
-.Ip "\f(CW\*(C`PTH_ATTR_STACK_SIZE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_STACK_SIZE""""\fR (read-write) [\f(CW""""unsigned int""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]" 4
.IX Item "PTH_ATTR_STACK_SIZE (read-write) [unsigned int]"
The thread stack size in bytes. Use lower values than 64 \s-1KB\s0 with great care!
-.Ip "\f(CW\*(C`PTH_ATTR_STACK_ADDR\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_STACK_ADDR""""\fR (read-write) [\f(CW""""char *""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]" 4
.IX Item "PTH_ATTR_STACK_ADDR (read-write) [char *]"
A pointer to the lower address of a chunk of \fImalloc\fR\|(3)'ed memory for the
stack.
-.Ip "\f(CW\*(C`PTH_ATTR_TIME_SPAWN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_TIME_SPAWN""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]" 4
.IX Item "PTH_ATTR_TIME_SPAWN (read-only) [pth_time_t]"
The time when the thread was spawned.
This can be queried only when the attribute object is bound to a thread.
-.Ip "\f(CW\*(C`PTH_ATTR_TIME_LAST\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_TIME_LAST""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]" 4
.IX Item "PTH_ATTR_TIME_LAST (read-only) [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.
-.Ip "\f(CW\*(C`PTH_ATTR_TIME_RAN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_TIME_RAN""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]" 4
.IX Item "PTH_ATTR_TIME_RAN (read-only) [pth_time_t]"
The total time the thread was running.
This can be queried only when the attribute object is bound to a thread.
-.Ip "\f(CW\*(C`PTH_ATTR_START_FUNC\*(C'\fR (read-only) [\f(CW\*(C`void *(*)(void *)\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_START_FUNC""""\fR (read-only) [\f(CW""""void *(*)(void *)""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]" 4
.IX Item "PTH_ATTR_START_FUNC (read-only) [void *(*)(void *)]"
The thread start function.
This can be queried only when the attribute object is bound to a thread.
-.Ip "\f(CW\*(C`PTH_ATTR_START_ARG\*(C'\fR (read-only) [\f(CW\*(C`void *\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_START_ARG""""\fR (read-only) [\f(CW""""void *""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]" 4
.IX Item "PTH_ATTR_START_ARG (read-only) [void *]"
The thread start argument.
This can be queried only when the attribute object is bound to a thread.
-.Ip "\f(CW\*(C`PTH_ATTR_STATE\*(C'\fR (read-only) [\f(CW\*(C`pth_state_t\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_STATE""""\fR (read-only) [\f(CW""""pth_state_t""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]" 4
.IX Item "PTH_ATTR_STATE (read-only) [pth_state_t]"
The scheduling state of the thread, i.e., either \f(CW\*(C`PTH_STATE_NEW\*(C'\fR,
\&\f(CW\*(C`PTH_STATE_READY\*(C'\fR, \f(CW\*(C`PTH_STATE_WAITING\*(C'\fR, or \f(CW\*(C`PTH_STATE_DEAD\*(C'\fR
This can be queried only when the attribute object is bound to a thread.
-.Ip "\f(CW\*(C`PTH_ATTR_EVENTS\*(C'\fR (read-only) [\f(CW\*(C`pth_event_t\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_EVENTS""""\fR (read-only) [\f(CW""""pth_event_t""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]" 4
.IX Item "PTH_ATTR_EVENTS (read-only) [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.
-.Ip "\f(CW\*(C`PTH_ATTR_BOUND\*(C'\fR (read-only) [\f(CW\*(C`int\*(C'\fR]" 4
+.if n .Ip "\f(CW""""PTH_ATTR_BOUND""""\fR (read-only) [\f(CW""""int""""\fR]" 4
+.el .Ip "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]" 4
.IX Item "PTH_ATTR_BOUND (read-only) [int]"
Whether the attribute object is bound (\f(CW\*(C`TRUE\*(C'\fR) to a thread or not (\f(CW\*(C`FALSE\*(C'\fR).
.PP
@@ -1075,14 +1094,16 @@
of the generated event is specified by \fIspec\fR. The following types are
available:
.RS 4
-.Ip "\f(CW\*(C`PTH_EVENT_FD\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_FD""""\fR" 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_EXECPTION\*(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'.
-.Ip "\f(CW\*(C`PTH_EVENT_SELECT\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_SELECT""""\fR" 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
@@ -1098,7 +1119,8 @@
\&\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.
-.Ip "\f(CW\*(C`PTH_EVENT_SIGS\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_SIGS""""\fR" 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
@@ -1109,7 +1131,8 @@
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'.
-.Ip "\f(CW\*(C`PTH_EVENT_TIME\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_TIME""""\fR" 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
@@ -1118,19 +1141,22 @@
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'.
-.Ip "\f(CW\*(C`PTH_EVENT_MSG\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_MSG""""\fR" 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'.
-.Ip "\f(CW\*(C`PTH_EVENT_TID\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_TID""""\fR" 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'.
-.Ip "\f(CW\*(C`PTH_EVENT_FUNC\*(C'\fR" 4
+.if n .Ip "\f(CW""""PTH_EVENT_FUNC""""\fR" 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',
@@ -1360,8 +1386,8 @@
This notified one or all threads which are waiting on \fIcond\fR. When
\&\fIbroadcast\fR is \f(CW\*(C`TRUE\*(C'\fR all thread are notified, else only a single
(unspecified) one.
-.Ip "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int \fIthreshold); \fR" 4
-.IX Item "int pth_barrier_init(pth_barrier_t *barrier, int threshold); "
+.Ip "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int \fIthreshold\fR);" 4
+.IX Item "int pth_barrier_init(pth_barrier_t *barrier, int threshold);"
This dynamically initializes a barrier variable of type `\f(CW\*(C`pth_barrier_t\*(C'\fR'.
Alternatively one can also use static initialization via `\f(CW\*(C`pth_barrier_t
barrier = PTH_BARRIER_INIT(\*(C'\fR\fIthreadhold\fR\f(CW\*(C`)\*(C'\fR'.
@@ -2089,7 +2115,7 @@
pre-processor macros). Additionally any debugging code is \fIcompletely\fR
removed from the source when not built with \f(CW\*(C`\-DPTH_DEBUG\*(C'\fR (see Autoconf
\&\f(CW\*(C`\-\-enable\-debug\*(C'\fR option), i.e., not only stub functions remain [see
-\&\f(CW\*(C`pth_debug.h\*(C'\fR for details].
+\&\f(CW\*(C`pth_debug.c\*(C'\fR for details].
.SH "RESTRICTIONS"
.IX Header "RESTRICTIONS"
\&\fBPth\fR (intentionally) provides no replacements for non-thread-safe
|
