reference.html

快速开发

<H5>Parameters</H5>
<TT>st_randomize_stacks()</TT> has the following parameters:<P>
<TT>on</TT><P>
If this parameter has a non-zero value, the State Threads library
randomizes the base addresses of stacks allocated for threads created
after this call.  Otherwise new threads' stacks are typically page
aligned.
<P>
<H5>Returns</H5>
The previous state of stack randomization (a value of <TT>0</TT> if it
was off and a non-zero value otherwise).
<P>
<H5>Description</H5>
Randomizing state threads' stack bases may improve cache performance on
some systems when large numbers of state threads all perform roughly the
same work, as when they all start from the same root function.  On many
modern systems the performance increase is negligible.  You should
compare your application's performance with this feature on and off to
see if you really need it.
<P>
When randomization is enabled, new stacks are allocated one page larger
to accomodate the randomization.
<P>
This call affects only threads created afterward.  It has no effect on
existing threads.
<P>
<HR>
<P>

<A NAME="priv">
<H2>Per-Thread Private Data</H2>
</A>
These functions allow to associate private data with each of the threads in
a process.
<P>
<DL>
<DD><A HREF=#key_create>st_key_create()</A></DD>
<DD><A HREF=#key_getlimit>st_key_getlimit()</A></DD>
<DD><A HREF=#thread_setspecific>st_thread_setspecific()</A></DD>
<DD><A HREF=#thread_getspecific>st_thread_getspecific()</A></DD>
</DL>
<P>
<HR>
<P>
<A NAME="key_create">
<H4>st_key_create()</H4>
</A>
Creates a key (non-negative integer) that can be used by all
threads in the process to get and set thread-specific data.
<P>
<H5>Syntax</H5>

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

int st_key_create(int *keyp, void (*destructor)(void *));
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_key_create()</TT> has the following parameters:<P>
<TT>keyp</TT><P>
The newly created key is returned in the memory pointed to by this parameter.
The new key can be used with
<A HREF=#thread_setspecific>st_thread_setspecific()</A> and
<A HREF=#thread_getspecific>st_thread_getspecific()</A>.<P>
<TT>destructor</TT><P>
Specifies an optional destructor function for the private data associated
with the key. This function can be specified as <TT>NULL</TT>.
Upon thread exit (see <A HREF=#thread_exit>st_thread_exit()</A>), if a key
has a non-<TT>NULL</TT> <TT>destructor</TT> and has a non-<TT>NULL</TT> value
associated with that key, then the <TT>destructor</TT> function will be
called with the associated value.
<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>EAGAIN</TT></TD><TD>The limit on the total number of keys per
process has been exceeded (see <A HREF=#key_getlimit>st_key_getlimit()</A>).
</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
If this function is successful, every thread in the same process is capable
of associating private data with the new key. After a new key is created, all
active threads have the value <TT>NULL</TT> associated with that key.
After a new thread is created, the value <TT>NULL</TT> is associated with
all keys for that thread.  If a non-<TT>NULL</TT> destructor function is
registered with a new key, it will be called at one of two times, as long as
the private data is not <TT>NULL</TT>:
<UL>
<LI>when replacement private data is set with
<A HREF=#thread_setspecific>st_thread_setspecific()</A></LI>
<LI>when a thread exits (see <A HREF=#thread_exit>st_thread_exit()</A>)</LI>
</UL>
<P>
The key maintains independent data values for each binding thread. A thread
can get access only to its own thread-specific data. There is no way to
deallocate a private data key once it is allocated.
<P>
<HR>
<P>
<A NAME="key_getlimit">
<H4>st_key_getlimit()</H4>
</A>
Returns the key limit.
<P>
<H5>Syntax</H5>

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

int st_key_getlimit(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
The limit on the total number of keys per process.
<P>
<H5>Description</H5>
This function can be used to obtain the limit on the total number of keys
per process (see <A HREF=#key_create>st_key_create()</A>).
<P>
<HR>
<P>
<A NAME="thread_setspecific">
<H4>st_thread_setspecific()</H4>
</A>
Sets per-thread private data.
<P>
<H5>Syntax</H5>

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

int st_thread_setspecific(int key, void *value);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_setspecific()</TT> has the following parameters:<P>
<TT>key</TT><P>
This parameter represents a key with which thread-specific data is associated.
<P>
<TT>value</TT><P>
The per-thread private data, or more likely, a pointer to the data which is
associated with <TT>key</TT>.
<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>The specified <TT>key</TT> is invalid.</TD>
</TR>
</TABLE>
<P>
<H5>Description</H5>
This function associates a thread-specific <TT>value</TT> with <TT>key</TT>.
Different threads may bind different values to the same key.<P>
If the thread already has non-<TT>NULL</TT> private data associated with
<TT>key</TT>, and if the destructor function for that key is not
<TT>NULL</TT>, this destructor function will be called before setting the
new data value.
<P>
<HR>
<P>
<A NAME="thread_getspecific">
<H4>st_thread_getspecific()</H4>
</A>
Retrieves the per-thread private data for the current thread.
<P>
<H5>Syntax</H5>

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

void *st_thread_getspecific(int key);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_thread_getspecific()</TT> has the following parameters:<P>
<TT>key</TT><P>
This parameter represents a key with which thread-specific data is associated.
<P>
<H5>Returns</H5>
The thread-specific data associated with <TT>key</TT>. If no data is
associated with <TT>key</TT>, then <TT>NULL</TT> is returned.
<P>
<H5>Description</H5>
This function returns the calling thread's value that is bound to the
specified <TT>key</TT> (see
<A HREF=#thread_setspecific>st_thread_setspecific()</A>).
<P>
<HR>
<P>

<A NAME="sync">
<H2>Synchronization</H2>
</A>
<P>
These functions operate on <A HREF=#cond_t>condition variables</A>
and <A HREF=#mutex_t>mutual exclusion locks</A> (mutexes).<P>
Functions are provided to wait on a condition variable and to wake up
(signal) threads that are waiting on the condition variable.
<P>
<DL>
<DD><A HREF=#cond_new>st_cond_new()</A></DD>
<DD><A HREF=#cond_destroy>st_cond_destroy()</A></DD>
<DD><A HREF=#cond_wait>st_cond_wait()</A></DD>
<DD><A HREF=#cond_timedwait>st_cond_timedwait()</A></DD>
<DD><A HREF=#cond_signal>st_cond_signal()</A></DD>
<DD><A HREF=#cond_broadcast>st_cond_broadcast()</A></DD>
<P>
<DD><A HREF=#mutex_new>st_mutex_new()</A></DD>
<DD><A HREF=#mutex_destroy>st_mutex_destroy()</A></DD>
<DD><A HREF=#mutex_lock>st_mutex_lock()</A></DD>
<DD><A HREF=#mutex_trylock>st_mutex_trylock()</A></DD>
<DD><A HREF=#mutex_unlock>st_mutex_unlock()</A></DD>
</DL>
<P>
<HR>
<P>
<A NAME="cond_new">
<H4>st_cond_new()</H4>
</A>
Creates a new condition variable.
<P>
<H5>Syntax</H5>

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

st_cond_t st_cond_new(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
Upon successful completion, a new condition variable identifier is returned.
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 condition variable.
<P>
<HR>
<P>
<A NAME="cond_destroy">
<H4>st_cond_destroy()</H4>
</A>
Destroys a condition variable.
<P>
<H5>Syntax</H5>

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

int st_cond_destroy(st_cond_t cvar);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_cond_destroy()</TT> has the following parameters:<P>
<TT>cvar</TT><P>
An identifier of the condition variable object to be destroyed.
<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>EBUSY</TT></TD><TD>The condition variable is currently being
used by one or more threads.</TD>
</TR>
</TABLE>
<P>
<H5>Description</H5>
This function destroys a condition variable. The caller is responsible for
ensuring that the condition variable is no longer in use.
<P>
<HR>
<P>
<A NAME="cond_wait">
<H4>st_cond_wait()</H4>
</A>
Waits on a condition.
<P>
<H5>Syntax</H5>

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

int st_cond_wait(st_cond_t cvar);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_cond_wait()</TT> has the following parameters:<P>
<TT>cvar</TT><P>
The condition variable on which to wait.
<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>
This function is used to block on a condition variable. A return from this
function does not guarantee that the condition or event for which the caller
was waiting actually occurred. It is the responsibility of the caller
to recheck the condition wait predicate before proceeding.<P>
<B>Note:</B> The State Threads library scheduling guarantees that the
condition cannot change between the checking and blocking, therefore there
is no need for mutex protection. You must not call any
<A HREF=#block>blocking functions</A> between the condition checking and
the <TT>st_cond_wait()</TT> call.
<P>
<HR>
<P>
<A NAME="cond_timedwait">
<H4>st_cond_timedwait()</H4>
</A>
Waits on a condition.
<P>
<H5>Syntax</H5>

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

int st_cond_timedwait(st_cond_t cvar, st_utime_t timeout);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_cond_timedwait()</TT> has the following parameters:<P>
<TT>cvar</TT><P>
The condition variable on which to wait.<P>
<TT>timeout</TT><P>
If the number of microseconds specified by this parameter passes before the
waiting thread is signalled, an error is returned. This parameter is a
variable of type <A HREF=#utime_t><B>st_utime_t</B></A>. Note that this
time value is a <I>time delta</I>; it is not an <I>absolute time</I>.
Also note that timeouts are measured <A HREF="notes.html#timeouts">since
the last context switch</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>
<TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred before the thread was
awakened by <A HREF=#cond_signal>st_cond_signal()</A> or
<A HREF=#cond_broadcast>st_cond_broadcast()</A>.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function works the same way as <A HREF=#cond_wait>st_cond_wait()</A>,
except that an error is returned if the number of microseconds specified by
<TT>timeout</TT> passes before the waiting thread is signalled.
<P>
<HR>
<P>
<A NAME="cond_signal">
<H4>st_cond_signal()</H4>
</A>
Unblocks a thread waiting on a condition variable.
<P>
<H5>Syntax</H5>

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

int st_cond_signal(st_cond_t cvar);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_cond_signal()</TT> has the following parameters:<P>
<TT>cvar</TT><P>
The condition variable to signal.
<P>
<H5>Returns</H5>
Always zero.
<P>
<H5>Description</H5>
This function unblocks (signals) one of the threads that are blocked on
<TT>cvar</TT> at the time of the call.  If no thread is waiting on the
condition variable, the signal operation is a no-op.
<P>
<HR>
<P>
<A NAME="cond_broadcast">
<H4>st_cond_broadcast()</H4>
</A>
Unblocks all threads waiting on a condition variable.
<P>
<H5>Syntax</H5>

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

int st_cond_broadcast(st_cond_t cvar);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_cond_broadcast()</TT> has the following parameters:<P>
<TT>cvar</TT><P>
The condition variable to broadcast.
<P>
<H5>Returns</H5>
Always zero.
<P>
<H5>Description</H5>
This function unblocks all threads blocked on the specified condition
variable at the time of the call. If no threads are waiting, this operation
is a no-op.
<P>
<HR>
<P>

<A NAME="mutex_new">
<H4>st_mutex_new()</H4>