reference.html

快速开发

</TR>
<TD VALIGN=TOP><TT>ST_EVENTSYS_POLL</TT></TD>
<TD>Use <TT>poll(2)</TT> as an event notification mechanism.</TD>
</TR>
<TD VALIGN=TOP><TT>ST_EVENTSYS_ALT</TT></TD>
<TD>Use an alternative event notification mechanism. The actual
mechanism selected depends on OS support. For example, <TT>epoll(4)</TT>
will be used on Linux if supported and <TT>kqueue(2)</TT> will be used
on FreeBSD/OpenBSD. If the OS supports no alternative event
notification mechanism, setting <TT>ST_EVENTSYS_ALT</TT> has no effect
and the <TT>ST_EVENTSYS_DEFAULT</TT> mechanism will be used.</TD>
</TR>
</TABLE>
<P>
<H5>Returns</H5>
Upon successful completion, a value of <TT>0</TT> is returned.
Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
to indicate the error:<P>
<TABLE BORDER=0 CELLSPACING=15>
<TR><TD><TT>EINVAL</TT></TD>
<TD>
The supplied <TT>eventsys</TT> parameter has an invalid value.
</TD></TR>
<TR><TD><TT>EBUSY</TT></TD>
<TD>
The event notification mechanism has already been set.
</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function sets the event notification mechanism that will be used by
the State Threads library. To have any effect, it must be called
<i>before</i> the <A HREF=#st_init>st_init()</A> function which performs
the actual initialization. If <TT>st_set_eventsys()</TT> is not called,
<A HREF=#st_init>st_init()</A> will set the <TT>ST_EVENTSYS_DEFAULT</TT>
mechanism. The mechanism cannot be changed once set.
<P>
There are no strict rules for selecting an event notification
mechanism.  The "best" one depends on how your application behaves.
Try a few to see which one works best for you.  As a rule of
thumb, you should use the <TT>ST_EVENTSYS_ALT</TT> mechanism if your
application deals with a very large number of network connections of
which only a few are active at once.
<P>
<HR>
<P>
<A NAME="get_eventsys">
<H4>st_get_eventsys()</H4>
</A>
Returns the integer value identifying the event notification mechanism
being used by the State Threads library.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_get_eventsys(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
The integer value identifying the current event notification mechanism.
This value can be one of the following (see <A
HREF=#set_eventsys>st_set_eventsys()</A>):
<TT>ST_EVENTSYS_SELECT</TT>, <TT>ST_EVENTSYS_POLL</TT>, or
<TT>ST_EVENTSYS_ALT</TT>. Future versions of the library may return other
values. If a mechanism hasn't been set yet, a value of <TT>-1</TT> is returned.
<P>
<H5>Description</H5>
This function returns the integer value identifying the event notification
mechanism which is actually being used by the State Threads library.
<P>
<HR>
<P>
<A NAME="get_eventsys_name">
<H4>st_get_eventsys_name()</H4>
</A>
Returns the name of the event notification mechanism being used by the
State Threads library.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

const char *st_get_eventsys_name(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
The string identifying the current event notification mechanism. If a
mechanism hasn't been set yet (see <A
HREF=#set_eventsys>st_set_eventsys()</A>), an empty string is
returned. Possible return values are <TT>"select"</TT>,
<TT>"poll"</TT>, <TT>"kqueue"</TT>, or <TT>"epoll"</TT>.  Future versions
of the library may return other values.
<P>
<H5>Description</H5>
This function returns the string identifying the event notification
mechanism which is actually being used by the State Threads library.
<P>
<HR>
<P>

<A NAME="set_switch_in_cb">
<H4>st_set_switch_in_cb()</H4>
</A>
<A NAME="set_switch_out_cb">
<H4>st_set_switch_out_cb()</H4>
</A>
Set the optional callback function for thread switches.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

st_switch_cb_t st_set_switch_in_cb(st_switch_cb_t cb);
st_switch_cb_t st_set_switch_out_cb(st_switch_cb_t cb);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_set_switch_in_cb()</TT> and <TT>st_set_switch_out_cb()</TT> have the
following parameter:<P>
<TT>cb</TT><P>
A function to be called when a thread is resumed and stopped respectively.<P>
<H5>Returns</H5>
The previous callback function pointer.
<P>
<H5>Description</H5>
These functions set the callback for when a thread is resumed and stopped
respectively.  After being called any thread switch will call the callback.
Use a <TT>NULL</TT> pointer to disable the callback (this is the default).
Use <A HREF=#thread_self>st_thread_self()</A> or <A HREF=#priv>thread
specific data</A> to differentiate between threads.<P>
These functions can be called at any time.<P>
This feature is available only when <TT>ST_SWITCH_CB</TT> is defined
in <TT>&lt;st.h&gt;</TT>.
<P>
<HR>
<P>

<A NAME="threads">
<H2>Thread Control and Identification</H2>
</A>
<P>
These functions operate on a thread object of type
<A HREF=#thread_t><B>st_thread_t</B></A>.
<P>
<DL>
<DD><A HREF=#thread_create>st_thread_create()</A></DD>
<DD><A HREF=#thread_exit>st_thread_exit()</A></DD>
<DD><A HREF=#thread_join>st_thread_join()</A></DD>
<DD><A HREF=#thread_self>st_thread_self()</A></DD>
<DD><A HREF=#thread_interrupt>st_thread_interrupt()</A></DD>
<DD><A HREF=#sleep>st_sleep()</A></DD>
<DD><A HREF=#sleep>st_usleep()</A></DD>
<DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD>
</DL>
<P>
<HR>
<P>
<A NAME="thread_create">
<H4>st_thread_create()</H4>
</A>
Creates a new thread.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

st_thread_t st_thread_create(void *(*start)(void *arg), void *arg,
                             int joinable, int stack_size);

</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_create()</TT> has the following parameters:<P>
<TT>start</TT><P>
A pointer to the thread's start function, which is called as the root of the
new thread. Return from this function terminates a thread.<P>
<TT>arg</TT><P>
A pointer to the root function's only parameter.<P>
<TT>joinable</TT><P>
Specifies whether the thread is joinable or unjoinable. If this parameter
is zero, the thread is unjoinable. Otherwise, it is joinable.
See also <A HREF=#thread_join>st_thread_join()</A>.<P>
<TT>stack_size</TT><P>
Specifies your preference for the size of the stack, in bytes, associated
with the newly created thread. If you pass zero in this parameter, the
default stack size will be used. The default stack size is 128 KB on IA-64
and 64 KB on all other platforms. On IA-64 only a half of <TT>stack_size</TT>
bytes is used for the memory stack. The other half is used for the register
stack backing store.
<P>
<H5>Returns</H5>
Upon successful completion, a new thread identifier is returned (this
identifier remains valid until the thread returns from its start function).
Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
to indicate the error.
<P>
<H5>Description</H5>
This function creates a new thread. Note that the total number of threads
created by the application is limited by the amount of swap space available.
Upon thread creation, <TT>stack_size</TT> bytes are reserved on the swap
space. The stack pages are not actually used (valid) until touched by the
application.
<P>
<HR>
<P>
<A NAME="thread_exit">
<H4>st_thread_exit()</H4>
</A>
Terminates the calling thread.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

void st_thread_exit(void *retval);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_exit()</TT> has the following parameters:<P>
<TT>retval</TT><P>
If the thread is joinable, then the value <TT>retval</TT> may be retrieved
by <A HREF=#thread_join>st_thread_join()</A>. If a thread returns from its
start function, it acts as if it had called <TT>st_thread_exit()</TT> with 
<TT>retval</TT> as the value returned.
<P>
<H5>Returns</H5>
Nothing.
<P>
<H5>Description</H5>
This function terminates the calling thread. When a thread exits, per-thread
private data is destroyed by invoking the destructor function for any
non-<TT>NULL</TT> thread specific values associated with active keys (see
<A HREF=#key_create>st_key_create()</A>). This function is implicitly called
when a thread returns from its start function.<P>
When the last thread terminates the process exits with a zero status value.
<P>
<HR>
<P>
<A NAME="thread_join">
<H4>st_thread_join()</H4>
</A>
Blocks the calling thread until a specified thread terminates.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_thread_join(st_thread_t thread, void **retvalp);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_join()</TT> has the following parameters:<P>
<TT>thread</TT><P>
A valid identifier for the thread that is to be joined.<P>
<TT>retvalp</TT><P>
If this parameter is not <TT>NULL</TT>, then the exit value of the
<TT>thread</TT> will be placed in the location referenced by this parameter
(see <A HREF=#thread_exit>st_thread_exit()</A>).
<P>
<H5>Returns</H5>
Upon successful completion, a value of <TT>0</TT> is returned.
Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
to indicate the error:<P>
<TABLE BORDER=0>
<TR><TD><TT>EINVAL</TT></TD><TD>Target thread is unjoinable.</TD></TR>
<TR><TD><TT>EINVAL</TT></TD><TD>Other thread already waits on the same
joinable thread.</TD></TR>
<TR><TD><TT>EDEADLK</TT></TD><TD>Target thread is the same as the
calling thread.</TD></TR>
<TR><TD><TT>EINTR</TT></TD><TD>Current thread was interrupted by
<A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function is used to synchronize the termination of a thread and possibly
retrieve its exit value. Several threads cannot wait for the same thread
to complete - one of the calling threads operates successfully, and the others
terminate with the error. The calling thread is not blocked if the target
thread has already terminated.
<P>
<HR>
<P>
<A NAME="thread_self">
<H4>st_thread_self()</H4>
</A>
Identifies the calling thread.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

st_thread_t st_thread_self(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
Always returns a valid reference to the calling thread - a self-identity.
<P>
<H5>Description</H5>
This function identifies the calling thread. This is the same identifier
that the creating thread obtains from
<A HREF=#thread_create>st_thread_create()</A>.
<P>
<HR>
<P>
<A NAME="thread_interrupt">
<H4>st_thread_interrupt()</H4>
</A>
Interrupts a target thread.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

void st_thread_interrupt(st_thread_t thread);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_interrupt()</TT> has the following parameters:<P>
<TT>thread</TT><P>
A valid identifier for the thread being interrupted.
<P>
<H5>Returns</H5>
Nothing.
<P>
<H5>Description</H5>
This function interrupts (unblocks) a target thread that is blocked in one
of the <A HREF=#block>blocking functions</A>. A function that was interrupted
returns an error and sets <TT>errno</TT> to <TT>EINTR</TT>. It is up to
the target thread to act upon an interrupt (e.g., it may exit or just
abort the current transaction).<P>
<B>Note: </B> State Threads library functions are never interrupted by a
caught signal. A blocking library function returns an error and sets
<TT>errno</TT> to <TT>EINTR</TT> <I>only</I> if the current thread was
interrupted via <TT>st_thread_interrupt()</TT>.
<P>
If a target thread is already runnable or running (e.g., it is a newly
created thread or calling thread itself), this function will prevent it
from subsequent blocking. In other words, the interrupt will be "delivered"
only when a target thread is about to block.
<P>
<HR>
<P>
<A NAME="sleep">
<H4>st_sleep(), st_usleep()</H4>
</A>
Suspends current thread for a specified amount of time.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_sleep(int secs);

int st_usleep(st_utime_t usecs);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_sleep()</TT> has the following parameters:<P>
<TT>secs</TT><P>
The number of seconds you want the thread to sleep for.
<P>
<TT>st_usleep()</TT> has the following parameters:<P>
<TT>usecs</TT><P>
The number of microseconds you want the thread to sleep for. This parameter
is a variable of type <A HREF=#utime_t><B>st_utime_t</B></A>.
<P>
<H5>Returns</H5>
Upon successful completion, a value of <TT>0</TT> is returned.
Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
to indicate the error:<P>
<TABLE BORDER=0>
<TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
<A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
These functions suspend the calling thread from execution for a specified
number of seconds (<TT>st_sleep()</TT>) or microseconds (<TT>st_usleep()</TT>).
<P>

If zero is passed as a parameter to <tt>st_sleep()</tt>, or
<tt>ST_UTIME_NO_WAIT</tt> (<tt>0</tt>) is passed to
<tt>st_usleep()</tt>, the calling thread yields, thus potentially
allowing another thread to run.

<P>

If <TT>-1</TT> is passed as a parameter to <tt>st_sleep()</tt>, or
<tt>ST_UTIME_NO_TIMEOUT</tt> (<tt>-1</tt>) is passed to
<tt>st_usleep()</tt>, the calling thread will be suspended permanently.
It can be resumed again by interrupting it via <A
HREF=#thread_interrupt>st_thread_interrupt()</A>.

<P>
<HR>
<P>
<A NAME="randomize_stacks">
<H4>st_randomize_stacks()</H4>
</A>
Turns stack base address randomization on or off.
<P>
<H5>Syntax</H5>

<PRE>
#include &lt;st.h&gt;

int st_randomize_stacks(int on);
</PRE>
<P>