📄 reference.html
字号:
<HTML><HEAD><TITLE>State Threads Library Reference</TITLE></HEAD><BODY BGCOLOR=#FFFFFF><H2>State Threads Library Reference</H2><DL><DD><A HREF=#types><B>Types</B></A></DD><DL><DD><A HREF=#thread_t>st_thread_t</A></DD></DL><DL><DD><A HREF=#cond_t>st_cond_t</A></DD></DL><DL><DD><A HREF=#mutex_t>st_mutex_t</A></DD></DL><DL><DD><A HREF=#utime_t>st_utime_t</A></DD></DL><DL><DD><A HREF=#netfd_t>st_netfd_t</A></DD></DL><DL><DD><A HREF=#switch_cb_t>st_switch_cb_t</A></DD></DL><P><DD><A HREF=#errors><B>Error Handling</B></A></DD><P><DD><A HREF=#init><B>Library Initialization</B></A></DD><P><DL><DD><A HREF=#st_init>st_init()</A></DD></DL><DL><DD><A HREF=#getfdlimit>st_getfdlimit()</A></DD></DL><DL><DD><A HREF=#set_eventsys>st_set_eventsys()</A></DD></DL><DL><DD><A HREF=#get_eventsys>st_get_eventsys()</A></DD></DL><DL><DD><A HREF=#get_eventsys_name>st_get_eventsys_name()</A></DD></DL><DL><DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD></DL><DL><DD><A HREF=#timecache_set>st_timecache_set()</A></DD></DL><DL><DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD></DL><P><DL><DD><A HREF=#switch_cb_t><B>st_switch_cb_t</B> type</A></DD></DL><DL><DD><A HREF=#set_switch_in_cb>st_set_switch_in_cb()</A></DD></DL><DL><DD><A HREF=#set_switch_out_cb>st_set_switch_out_cb()</A></DD></DL><P><DD><A HREF=#threads><B>Thread Control and Identification</B></A></DD><P><DL><DD><A HREF=#thread_t><B>st_thread_t</B> type</A></DD></DL><DL><DD><A HREF=#thread_create>st_thread_create()</A></DD></DL><DL><DD><A HREF=#thread_exit>st_thread_exit()</A></DD></DL><DL><DD><A HREF=#thread_join>st_thread_join()</A></DD></DL><DL><DD><A HREF=#thread_self>st_thread_self()</A></DD></DL><DL><DD><A HREF=#thread_interrupt>st_thread_interrupt()</A></DD></DL><DL><DD><A HREF=#sleep>st_sleep()</A></DD></DL><DL><DD><A HREF=#sleep>st_usleep()</A></DD></DL><DL><DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD></DL><P><DD><A HREF=#priv><B>Per-Thread Private Data</B></A></DD><P><DL><DD><A HREF=#key_create>st_key_create()</A></DD></DL><DL><DD><A HREF=#key_getlimit>st_key_getlimit()</A></DD></DL><DL><DD><A HREF=#thread_setspecific>st_thread_setspecific()</A></DD></DL><DL><DD><A HREF=#thread_getspecific>st_thread_getspecific()</A></DD></DL><P><DD><A HREF=#sync><B>Synchronization</B></A></DD><P><DL><DD><A HREF=#cond_t><B>st_cond_t</B> type</A></DD></DL><DL><DD><A HREF=#cond_new>st_cond_new()</A></DD></DL><DL><DD><A HREF=#cond_destroy>st_cond_destroy()</A></DD></DL><DL><DD><A HREF=#cond_wait>st_cond_wait()</A></DD></DL><DL><DD><A HREF=#cond_timedwait>st_cond_timedwait()</A></DD></DL><DL><DD><A HREF=#cond_signal>st_cond_signal()</A></DD></DL><DL><DD><A HREF=#cond_broadcast>st_cond_broadcast()</A></DD></DL><P><DL><DD><A HREF=#mutex_t><B>st_mutex_t</B> type</A></DD></DL><DL><DD><A HREF=#mutex_new>st_mutex_new()</A></DD></DL><DL><DD><A HREF=#mutex_destroy>st_mutex_destroy()</A></DD></DL><DL><DD><A HREF=#mutex_lock>st_mutex_lock()</A></DD></DL><DL><DD><A HREF=#mutex_trylock>st_mutex_trylock()</A></DD></DL><DL><DD><A HREF=#mutex_unlock>st_mutex_unlock()</A></DD></DL><P><DD><A HREF=#timing><B>Timing</B></A></DD><P><DL><DD><A HREF=#utime_t><B>st_utime_t</B> type</A></DD></DL><DL><DD><A HREF=#utime>st_utime()</A></DD></DL><DL><DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD></DL><DL><DD><A HREF=#timecache_set>st_timecache_set()</A></DD></DL><DL><DD><A HREF=#time>st_time()</A></DD></DL><P><DD><A HREF=#io><B>I/O Functions</B></A></DD><P><DL><DD><A HREF=#netfd_t><B>st_netfd_t</B> type</A></DD></DL><DL><DD><A HREF=#netfd_open>st_netfd_open()</A></DD></DL><DL><DD><A HREF=#netfd_open_socket>st_netfd_open_socket()</A></DD></DL><DL><DD><A HREF=#netfd_free>st_netfd_free()</A></DD></DL><DL><DD><A HREF=#netfd_close>st_netfd_close()</A></DD></DL><DL><DD><A HREF=#netfd_fileno>st_netfd_fileno()</A></DD></DL><DL><DD><A HREF=#netfd_setspecific>st_netfd_setspecific()</A></DD></DL><DL><DD><A HREF=#netfd_getspecific>st_netfd_getspecific()</A></DD></DL><DL><DD><A HREF=#netfd_serialize_accept>st_netfd_serialize_accept()</A></DD></DL><DL><DD><A HREF=#netfd_poll>st_netfd_poll()</A></DD></DL><P><DL><DD><A HREF=#accept>st_accept()</A></DD></DL><DL><DD><A HREF=#connect>st_connect()</A></DD></DL><DL><DD><A HREF=#read>st_read()</A></DD></DL><DL><DD><A HREF=#read_fully>st_read_fully()</A></DD></DL><DL><DD><A HREF=#read_resid>st_read_resid()</A></DD></DL><DL><DD><A HREF=#readv>st_readv()</A></DD></DL><DL><DD><A HREF=#readv_resid>st_readv_resid()</A></DD></DL><DL><DD><A HREF=#write>st_write()</A></DD></DL><DL><DD><A HREF=#write_resid>st_write_resid()</A></DD></DL><DL><DD><A HREF=#writev>st_writev()</A></DD></DL><DL><DD><A HREF=#writev_resid>st_writev_resid()</A></DD></DL><DL><DD><A HREF=#recvfrom>st_recvfrom()</A></DD></DL><DL><DD><A HREF=#sendto>st_sendto()</A></DD></DL><DL><DD><A HREF=#recvmsg>st_recvmsg()</A></DD></DL><DL><DD><A HREF=#sendmsg>st_sendmsg()</A></DD></DL><P><DL><DD><A HREF=#open>st_open()</A></DD></DL><DL><DD><A HREF=#poll>st_poll()</A></DD></DL><P><DD><A HREF=#progr><B>Program Structure</B></A></DD><P><DD><A HREF=#block><B>List of Blocking Functions</B></A></DD><P></DL><P><HR><P><A NAME="types"><H2>Types</H2></A>The State Thread library defines the following types in the <TT>st.h</TT>header file:<P><DL><DD><A HREF=#thread_t>st_thread_t</A></DD><DD><A HREF=#cond_t>st_cond_t</A></DD><DD><A HREF=#mutex_t>st_mutex_t</A></DD><DD><A HREF=#utime_t>st_utime_t</A></DD><DD><A HREF=#netfd_t>st_netfd_t</A></DD></DL><P><HR><P><A NAME="thread_t"><H4>st_thread_t</H4></A>Thread type.<P><H5>Syntax</H5><PRE>#include <st.h>typedef void * st_thread_t;</PRE><P><H5>Description</H5>A thread is represented and identified by a pointer to an opaque datastructure. This pointer is a required parameter for most of the functionsthat operate on threads.<P>The thread identifier remains valid until the thread returns from its rootfunction and, if the thread was created joinable, is joined.<P><HR><P><A NAME="cond_t"><H4>st_cond_t</H4></A>Condition variable type.<P><H5>Syntax</H5><PRE>#include <st.h>typedef void * st_cond_t;</PRE><P><H5>Description</H5>A condition variable is an opaque object identified by a pointer.Condition variables provide synchronization primitives to wait for or wakeup threads waiting for certain conditions to be satisfied.<P>In the State Threads library there is no need to lock a mutex beforewaiting on a condition variable.<P><HR><P><A NAME="mutex_t"><H4>st_mutex_t</H4></A>Mutex type.<P><H5>Syntax</H5><PRE>#include <st.h>typedef void * st_mutex_t;</PRE><P><H5>Description</H5>A mutex is an opaque object identified by a pointer.Mutual exclusion locks (mutexes) are used to serialize the execution ofthreads through critical sections of code.<P>If application using the State Threads library is written with noI/O or control yielding in critical sections (that is no<A HREF=#block>blocking functions</A> in critical sections), then there isno need for mutexes.<P>These mutexes can only be used for intra-process thread synchronization.They cannot be used for inter-process synchronization.<P><HR><P><A NAME="utime_t"><H4>st_utime_t</H4></A>High resolution time type ("u" stands for "micro").<P><H5>Syntax</H5><PRE>#include <st.h>typedef unsigned long long st_utime_t;</PRE><P><H5>Description</H5>This datatype (unsigned 64-bit integer) represents high-resolution real timeexpressed in microseconds since some arbitrary time in the past. It is notcorrelated in any way to the time of day.<P><HR><P><A NAME="netfd_t"><H4>st_netfd_t</H4></A>File descriptor type.<P><H5>Syntax</H5><PRE>#include <st.h>typedef void * st_netfd_t;</PRE><P><H5>Description</H5>This datatype typically represents any open end point of networkcommunication (socket, end point of a pipe, FIFO, etc.) but canencapsulate any open file descriptor. Objects of this type areidentified by a pointer to an opaque data structure.<P><HR><P><A NAME="switch_cb_t"><H4>st_switch_cb_t</H4></A>Context switch callback function type.<P><H5>Syntax</H5><PRE>#include <st.h>typedef void (*st_switch_cb_t)(void);</PRE><P><H5>Description</H5>This datatype is a convenience type for describing a pointerto a function that will be called when a thread is set to stopor set to run.This feature is available only when <TT>ST_SWITCH_CB</TT> is definedin <TT><st.h></TT>.<P><HR><P><A NAME="errors"><H2>Error Handling</H2></A>All State Threads library non-void functions return on success either anon-negative integer or a pointer to a newly created object (constructor-typefunctions). On failure they return either <TT>-1</TT> or a <TT>NULL</TT>pointer respectively and set global <TT>errno</TT> to indicate the error.It is safe to use <TT>errno</TT> because it is set right before the functionreturn and only one thread at a time can modify its value.<P>The <TT>perror(3)</TT> function can be used to produce an error message on thestandard error output.<P><HR><P><A NAME="init"><H2>Library Initialization</H2></A><P><DL><DD><A HREF=#st_init>st_init()</A></DD><DD><A HREF=#getfdlimit>st_getfdlimit()</A></DD><DD><A HREF=#set_eventsys>st_set_eventsys()</A></DD><DD><A HREF=#get_eventsys>st_get_eventsys()</A></DD><DD><A HREF=#get_eventsys_name>st_get_eventsys_name()</A></DD><P>These functions operate on a callback function of type<A HREF=#switch_cb_t><B>st_switch_cb_t</B></A>:<DD><A HREF=#set_switch_in_cb>st_set_switch_in_cb()</A></DD><DD><A HREF=#set_switch_out_cb>st_set_switch_out_cb()</A></DD></DL><P><HR><P><A NAME="st_init"><H4>st_init()</H4></A>Initializes the runtime.<P><H5>Syntax</H5><PRE>#include <st.h>int st_init(void);</PRE><P><H5>Parameters</H5>None.<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 setto indicate the error.<P><H5>Description</H5>This function initializes the library runtime. It should be called nearthe beginning of the application's <TT>main()</TT> function before any otherState Threads library function is called.<P>Among other things, this function limits the number of open file descriptorsto the OS imposed per-process maximum number or, if <TT>select(2)</TT> isused, to <TT>FD_SETSIZE</TT>, whichever is less (<TT>getrlimit(2)</TT>).This limit can beretrieved by <A HREF=#getfdlimit>st_getfdlimit()</A>. It also sets thedisposition of the <TT>SIGPIPE</TT> signal to <TT>SIG_IGN</TT> (to be ignored)(<TT>signal(5)</TT>).<P>Unlike POSIX threads, a new process created by the <TT>fork(2)</TT> systemcall is an <I>exact</I> copy of the calling process and all state threadswhich are running in the parent do exist in the child. That means that<TT>st_init()</TT> may be called either before or after multiple processesare created by <TT>fork(2)</TT>.<P>If the library runtime is not properly initialized (e.g., <TT>st_init()</TT>is accidentally omitted), then the process will receive either an arithmeticexception (SIGFPE or SIGTRAP) or segmentation fault (SIGSEGV) signal uponnew thread creation or the first context switch, respectively.<P><HR><P><A NAME="getfdlimit"><H4>st_getfdlimit()</H4></A>Returns the maximum number of file descriptors that the calling processcan open.<P><H5>Syntax</H5><PRE>#include <st.h>int st_getfdlimit(void);</PRE><P><H5>Parameters</H5>None.<P><H5>Returns</H5>The maximum number of file descriptors that the calling process can open.If this function is called before the library is successfully initialized by<A HREF=#st_init>st_init()</A>, a value of <TT>-1</TT> is returned.<P><H5>Description</H5>This function returns the limit on the number of open file descriptors whichis set by the <A HREF=#st_init>st_init()</A> function.<P><HR><P><A NAME="set_eventsys"><H4>st_set_eventsys()</H4></A>Sets event notification mechanism.<P><H5>Syntax</H5><PRE>#include <st.h>int st_set_eventsys(int eventsys);</PRE><P><H5>Parameters</H5><TT>st_set_eventsys()</TT> has the following parameter:<P><TT>eventsys</TT><P>An integer value identifying selected event notification mechanism. Thefollowing values are defined in the <TT>st.h</TT> header file:<P><TABLE BORDER=0 CELLPADDING=5 CELLSPACING=15><TR><TD VALIGN=TOP><TT>ST_EVENTSYS_DEFAULT</TT></TD><TD>Use default event notification mechanism. Usually it's <TT>select(2)</TT>but if the library was compiled with the <TT>USE_POLL</TT> macro definedthen the default is <TT>poll(2)</TT>.</TD></TR><TR><TD VALIGN=TOP><TT>ST_EVENTSYS_SELECT</TT></TD><TD>Use <TT>select(2)</TT> as an event notification mechanism.</TD>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -