reference.html

快速开发

</A>
Creates a new mutual exclusion lock (mutex).
<P>
<H5>Syntax</H5>

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

st_mutex_t st_mutex_new(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
Upon successful completion, a new mutex 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 opaque mutual exclusion lock (see
<A HREF=#mutex_t><B>st_mutex_t</B></A>).
<P>
<HR>
<P>
<A NAME="mutex_destroy">
<H4>st_mutex_destroy()</H4>
</A>
Destroys a specified mutex object.
<P>
<H5>Syntax</H5>

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

int st_mutex_destroy(st_mutex_t lock);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_mutex_destroy()</TT> has the following parameters:<P>
<TT>lock</TT><P>
An identifier of the mutex 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 mutex is currently being used by
other threads.</TD>
</TR>
</TABLE>
<P>
<H5>Description</H5>
This function destroys a mutex. The caller is responsible for ensuring
that the mutex is no longer in use.
<P>
<HR>
<P>
<A NAME="mutex_lock">
<H4>st_mutex_lock()</H4>
</A>
Locks a specified mutex object.
<P>
<H5>Syntax</H5>

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

int st_mutex_lock(st_mutex_t lock);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_mutex_lock()</TT> has the following parameters:<P>
<TT>lock</TT><P>
An identifier of the mutex object to be locked.
<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>EDEADLK</TT></TD><TD>The current thread already owns the mutex.
</TD></TR>
<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>
A thread that calls this function will block until it can gain exclusive
ownership of a mutex, and retains ownership until it calls
<A HREF=#mutex_unlock>st_mutex_unlock()</A>.
<P>
<HR>
<P>
<A NAME="mutex_trylock">
<H4>st_mutex_trylock()</H4>
</A>
Attempts to acquire a mutex.
<P>
<H5>Syntax</H5>

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

int st_mutex_trylock(st_mutex_t lock);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_mutex_trylock()</TT> has the following parameters:<P>
<TT>lock</TT><P>
An identifier of the mutex object to be locked.
<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 mutex is currently held by another
thread.</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function attempts to acquire a mutex. If the mutex object is locked
(by any thread, including the current thread), the call returns immediately
with an error.
<P>
<HR>
<P>
<A NAME="mutex_unlock">
<H4>st_mutex_unlock()</H4>
</A>
Releases a specified mutex object.
<P>
<H5>Syntax</H5>

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

int st_mutex_unlock(st_mutex_t lock);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_mutex_unlock()</TT> has the following parameters:<P>
<TT>lock</TT><P>
An identifier of the mutex object to be unlocked.
<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>EPERM</TT></TD><TD>The current thread does not own the mutex.
</TD></TR>
</TABLE>
<P>
<H5>Description</H5>
This function releases a specified mutex object previously acquired by
<A HREF=#mutex_lock>st_mutex_lock()</A> or
<A HREF=#mutex_trylock>st_mutex_trylock()</A>. Only the thread that locked
a mutex should unlock it.
<P>
<HR>
<P>

<A NAME="timing">
<H2>Timing</H2>
</A>
<P>
<DL>
<DD><A HREF=#utime>st_utime()</A></DD>
<DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD>
<DD><A HREF=#timecache_set>st_timecache_set()</A></DD>
<DD><A HREF=#time>st_time()</A></DD>
</DL>
<P>
<HR>
<P>
<A NAME="utime">
<H4>st_utime()</H4>
</A>
Returns current high-resolution time.
<P>
<H5>Syntax</H5>

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

st_utime_t st_utime(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
Current high-resolution time value of type
<A HREF=#utime_t><B>st_utime_t</B></A>.
<P>
<H5>Description</H5>
This function returns the current high-resolution time. Time is
expressed as microseconds since some arbitrary time in the past. It is
not correlated in any way to the time of day.  See also <A
HREF=#utime_t><B>st_utime_t</B></A> and <A
HREF="#time"><B>st_time()</B></A>.
<P>
<HR>
<P>
<A NAME="set_utime_function">
<H4>st_set_utime_function()</H4>
</A>
Set high-resolution time function.
<P>
<H5>Syntax</H5>

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

int st_set_utime_function(st_utime_t (*func)(void));
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_set_utime_function()</TT> has the following parameters:<P>
<TT>func</TT><P>
This function will be called to get high-resolution time instead of the
default <A HREF=#utime>st_utime()</A> function. It must return
number of microseconds since some arbitrary time in the past.
<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 <TT>EINVAL</TT> to indicate the error.
<P>
<H5>Description</H5>
This function may be called to replace the default implementation of the
<A HREF=#utime>st_utime()</A> function.  It must be called before the ST
library has been initialized (see <A HREF=#st_init>st_init()</A>).
The user-provided function <TT>func</TT> will be invoked whenever
<A HREF=#utime>st_utime()</A> is called to obtain current high-resolution time.
Replacing default implementation may be useful, for example, for taking
advantage of high performance CPU cycle counters.
<P>
<HR>
<P>
<A NAME="timecache_set">
<H4>st_timecache_set()</H4>
</A>
Turns the time caching on or off.
<P>
<H5>Syntax</H5>

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

int st_timecache_set(int on);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_timecache_set()</TT> has the following parameters:<P>
<TT>on</TT><P>
If this parameter has a non-zero value, the time caching is turned on
(enabled). Otherwise, the time caching is turned off (disabled).
By default time caching is disabled.
<P>
<H5>Returns</H5>
The previous state of time caching (a value of <TT>0</TT> if it was off and
a value of <TT>1</TT> otherwise).
<P>
<H5>Description</H5>
The State Threads library has the ability to "cache" the time value that is
reported by the <TT>time(2)</TT> system call. If the time caching is enabled
by calling this function with a non-zero argument, then the result value
of <TT>time(2)</TT> will be stored and updated at most once per second. The
cached time can be retrieved by <A HREF=#time>st_time()</A>.
By default time caching is disabled.
You may enable or disable time caching at any time but generally
you enable it once (if desired) during program initialization.<P>
<B>Note:</B> There are some pathological cases (e.g., very heavy loads during
application benchmarking) when a single thread runs for a long time without
giving up control and the cached time value is not updated properly. If you
<I>always</I> need "real-time" time values, don't enable the time caching.
<P>
<HR>
<P>
<A NAME="time">
<H4>st_time()</H4>
</A>
Returns the value of time in seconds since 00:00:00 UTC, January 1, 1970.
<P>
<H5>Syntax</H5>

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

time_t st_time(void);
</PRE>
<P>
<H5>Parameters</H5>
None.
<P>
<H5>Returns</H5>
The value of time in seconds since 00:00:00 UTC, January 1, 1970 as reported
by the <TT>time(2)</TT> system call.
<P>
<H5>Description</H5>
If the time caching was enabled by
<A HREF=#timecache_set>st_timecache_set()</A>, then this function returns
the cached result. Otherwise, it just calls <TT>time(2)</TT>.
<P>
<HR>
<P>

<A NAME="io">
<H2>I/O Functions</H2>
</A>
<P>
Most State Threads library I/O functions look like corresponding C library
functions with two exceptions:
<UL>
<LI>They operate on file descriptor objects of type
<A HREF=#netfd_t><B>st_netfd_t</B></A>.</LI>
<LI>They take an additional argument of type
<A HREF=#utime_t><B>st_utime_t</B></A> which represents an <I>inactivity
timeout</I>: if no I/O is possible during this amount of time, I/O functions
return an error code and set <TT>errno</TT> to <TT>ETIME</TT>.

The boundary values <tt>ST_UTIME_NO_WAIT</tt> (<TT>0</TT>) and
<tt>ST_UTIME_NO_TIMEOUT</tt> (<TT>-1</TT>) for this argument indicate
that the thread should wait no time (function returns immediately) or
wait forever (never time out), respectively.

Note that timeouts are measured <A HREF="notes.html#timeouts">since the
last context switch</A>.
</LI>
</UL>
<P>
<DL>
<DD><A HREF=#netfd_open>st_netfd_open()</A></DD>
<DD><A HREF=#netfd_open_socket>st_netfd_open_socket()</A></DD>
<DD><A HREF=#netfd_free>st_netfd_free()</A></DD>
<DD><A HREF=#netfd_close>st_netfd_close()</A></DD>
<DD><A HREF=#netfd_fileno>st_netfd_fileno()</A></DD>
<DD><A HREF=#netfd_setspecific>st_netfd_setspecific()</A></DD>
<DD><A HREF=#netfd_getspecific>st_netfd_getspecific()</A></DD>
<DD><A HREF=#netfd_serialize_accept>st_netfd_serialize_accept()</A></DD>
<DD><A HREF=#netfd_poll>st_netfd_poll()</A></DD>
<P>
<DD><A HREF=#accept>st_accept()</A></DD>
<DD><A HREF=#connect>st_connect()</A></DD>
<DD><A HREF=#read>st_read()</A></DD>
<DD><A HREF=#read_fully>st_read_fully()</A></DD>
<DD><A HREF=#read_resid>st_read_resid()</A></DD>
<DD><A HREF=#readv>st_readv()</A></DD>
<DD><A HREF=#readv_resid>st_read_resid()</A></DD>
<DD><A HREF=#write>st_write()</A></DD>
<DD><A HREF=#write_resid>st_write_resid()</A></DD>
<DD><A HREF=#writev>st_writev()</A></DD>
<DD><A HREF=#writev_resid>st_writev_resid()</A></DD>
<DD><A HREF=#recvfrom>st_recvfrom()</A></DD>
<DD><A HREF=#sendto>st_sendto()</A></DD>
<DD><A HREF=#recvmsg>st_recvmsg()</A></DD>
<DD><A HREF=#sendmsg>st_sendmsg()</A></DD>
<DD><A HREF=#open>st_open()</A></DD>
<DD><A HREF=#poll>st_poll()</A></DD>
</DL>
<P>
<HR>
<P>
<A NAME="netfd_open">
<H4>st_netfd_open()</H4>
</A>
Creates a new file descriptor object.
<P>
<H5>Syntax</H5>

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

st_netfd_t st_netfd_open(int osfd);
</PRE>
<P>
<H5>Parameters</H5>
<TT>st_netfd_open()</TT> has the following parameters:<P>
<TT>osfd</TT><P>

Any open OS file descriptor; can be obtained from calls to
functions including, but not restricted to, <TT>pipe(2), socket(3),
socketpair(3), fcntl(2), dup(2),</TT> etc.


<P>
<H5>Returns</H5>
Upon successful completion, a new file descriptor object 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 file descriptor object of type
<A HREF=#netfd_t><B>st_netfd_t</B></A>.<P>

<B>Note:</B> Among other things, this function sets a non-blocking
flag on the underlying OS file descriptor. You should not modify this
flag directly. Also, once an <A HREF=#netfd_t><B>st_netfd_t</B></A>
has been created with a given file descriptor, you should avoid
passing that descriptor to normal I/O or stdio functions. Since the
O_NONBLOCK flag is shared across <TT>dup(2)</TT>, this applies to
<TT>dup()</TT>'ed file descriptors as well - for instance, if you pass
standard output or standard input to <TT>st_netfd_open()</TT>, then
you should use <A HREF=#write>st_write()</A> instead of <TT>write</TT>
or <TT>fprintf</TT> when writing to standard error as well - since all
three descriptors could point to the same terminal. If necessary, you
can still use <TT>write</TT> directly if you remember to check
<TT>errno</TT> for <TT>EAGAIN</TT>, but <TT>fprintf</TT> and other
stdio functions should be avoided completely because, at least on
Linux, the stdio library cannot be made to work reliably with
non-blocking files. (This only applies to file descriptors which are
passed to <TT>st_netfd_open()</TT> or <A
HREF=#netfd_open_socket>st_netfd_open_socket()</A>, or which are
related to such descriptors through <TT>dup()</TT>; other file
descriptors are untouched by State Threads.)
<P>
<HR>
<P>
<A NAME="netfd_open_socket">
<H4>st_netfd_open_socket()</H4>
</A>
Creates a new file descriptor object from a socket.
<P>
<H5>Syntax</H5>