State Threads Library Reference
- Types
- st_thread_t
- st_cond_t
- st_mutex_t
- st_utime_t
- st_netfd_t
- st_switch_cb_t
- Error Handling
- Library Initialization
- st_init()
- st_getfdlimit()
- st_set_eventsys()
- st_get_eventsys()
- st_get_eventsys_name()
- st_set_utime_function()
- st_timecache_set()
- st_randomize_stacks()
- st_switch_cb_t type
- st_set_switch_in_cb()
- st_set_switch_out_cb()
- Thread Control and Identification
- st_thread_t type
- st_thread_create()
- st_thread_exit()
- st_thread_join()
- st_thread_self()
- st_thread_interrupt()
- st_sleep()
- st_usleep()
- st_randomize_stacks()
- Per-Thread Private Data
- st_key_create()
- st_key_getlimit()
- st_thread_setspecific()
- st_thread_getspecific()
- Synchronization
- st_cond_t type
- st_cond_new()
- st_cond_destroy()
- st_cond_wait()
- st_cond_timedwait()
- st_cond_signal()
- st_cond_broadcast()
- st_mutex_t type
- st_mutex_new()
- st_mutex_destroy()
- st_mutex_lock()
- st_mutex_trylock()
- st_mutex_unlock()
- Timing
- st_utime_t type
- st_utime()
- st_set_utime_function()
- st_timecache_set()
- st_time()
- I/O Functions
- st_netfd_t type
- st_netfd_open()
- st_netfd_open_socket()
- st_netfd_free()
- st_netfd_close()
- st_netfd_fileno()
- st_netfd_setspecific()
- st_netfd_getspecific()
- st_netfd_serialize_accept()
- st_netfd_poll()
- st_accept()
- st_connect()
- st_read()
- st_read_fully()
- st_read_resid()
- st_readv()
- st_readv_resid()
- st_write()
- st_write_resid()
- st_writev()
- st_writev_resid()
- st_recvfrom()
- st_sendto()
- st_recvmsg()
- st_sendmsg()
- st_open()
- st_poll()
- Program Structure
- List of Blocking Functions
The State Thread library defines the following types in the st.h
header file:
- st_thread_t
- st_cond_t
- st_mutex_t
- st_utime_t
- st_netfd_t
Thread type.
Syntax
#include <st.h>
typedef void * st_thread_t;
Description
A thread is represented and identified by a pointer to an opaque data
structure. This pointer is a required parameter for most of the functions
that operate on threads.
The thread identifier remains valid until the thread returns from its root
function and, if the thread was created joinable, is joined.
Condition variable type.
Syntax
#include <st.h>
typedef void * st_cond_t;
Description
A condition variable is an opaque object identified by a pointer.
Condition variables provide synchronization primitives to wait for or wake
up threads waiting for certain conditions to be satisfied.
In the State Threads library there is no need to lock a mutex before
waiting on a condition variable.
Mutex type.
Syntax
#include <st.h>
typedef void * st_mutex_t;
Description
A mutex is an opaque object identified by a pointer.
Mutual exclusion locks (mutexes) are used to serialize the execution of
threads through critical sections of code.
If application using the State Threads library is written with no
I/O or control yielding in critical sections (that is no
blocking functions in critical sections), then there is
no need for mutexes.
These mutexes can only be used for intra-process thread synchronization.
They cannot be used for inter-process synchronization.
High resolution time type ("u" stands for "micro").
Syntax
#include <st.h>
typedef unsigned long long st_utime_t;
Description
This datatype (unsigned 64-bit integer) represents high-resolution real time
expressed in microseconds since some arbitrary time in the past. It is not
correlated in any way to the time of day.
File descriptor type.
Syntax
#include <st.h>
typedef void * st_netfd_t;
Description
This datatype typically represents any open end point of network
communication (socket, end point of a pipe, FIFO, etc.) but can
encapsulate any open file descriptor. Objects of this type are
identified by a pointer to an opaque data structure.
Context switch callback function type.
Syntax
#include <st.h>
typedef void (*st_switch_cb_t)(void);
Description
This datatype is a convenience type for describing a pointer
to a function that will be called when a thread is set to stop
or set to run.
This feature is available only when ST_SWITCH_CB is defined
in <st.h>.
All State Threads library non-void functions return on success either a
non-negative integer or a pointer to a newly created object (constructor-type
functions). On failure they return either -1 or a NULL
pointer respectively and set global errno to indicate the error.
It is safe to use errno because it is set right before the function
return and only one thread at a time can modify its value.
The perror(3) function can be used to produce an error message on the
standard error output.
- st_init()
- st_getfdlimit()
- st_set_eventsys()
- st_get_eventsys()
- st_get_eventsys_name()
These functions operate on a callback function of type
st_switch_cb_t:
- st_set_switch_in_cb()
- st_set_switch_out_cb()
Initializes the runtime.
Syntax
#include <st.h>
int st_init(void);
Parameters
None.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error.
Description
This function initializes the library runtime. It should be called near
the beginning of the application's main() function before any other
State Threads library function is called.
Among other things, this function limits the number of open file descriptors
to the OS imposed per-process maximum number or, if select(2) is
used, to FD_SETSIZE, whichever is less (getrlimit(2)).
This limit can be
retrieved by st_getfdlimit(). It also sets the
disposition of the SIGPIPE signal to SIG_IGN (to be ignored)
(signal(5)).
Unlike POSIX threads, a new process created by the fork(2) system
call is an exact copy of the calling process and all state threads
which are running in the parent do exist in the child. That means that
st_init() may be called either before or after multiple processes
are created by fork(2).
If the library runtime is not properly initialized (e.g., st_init()
is accidentally omitted), then the process will receive either an arithmetic
exception (SIGFPE or SIGTRAP) or segmentation fault (SIGSEGV) signal upon
new thread creation or the first context switch, respectively.
Returns the maximum number of file descriptors that the calling process
can open.
Syntax
#include <st.h>
int st_getfdlimit(void);
Parameters
None.
Returns
The maximum number of file descriptors that the calling process can open.
If this function is called before the library is successfully initialized by
st_init(), a value of -1 is returned.
Description
This function returns the limit on the number of open file descriptors which
is set by the st_init() function.
Sets event notification mechanism.
Syntax
#include <st.h>
int st_set_eventsys(int eventsys);
Parameters
st_set_eventsys() has the following parameter:
eventsys
An integer value identifying selected event notification mechanism. The
following values are defined in the st.h header file:
| ST_EVENTSYS_DEFAULT |
Use default event notification mechanism. Usually it's select(2)
but if the library was compiled with the USE_POLL macro defined
then the default is poll(2). |
| ST_EVENTSYS_SELECT |
Use select(2) as an event notification mechanism. |
| ST_EVENTSYS_POLL |
Use poll(2) as an event notification mechanism. |
| ST_EVENTSYS_ALT |
Use an alternative event notification mechanism. The actual
mechanism selected depends on OS support. For example, epoll(4)
will be used on Linux if supported and kqueue(2) will be used
on FreeBSD/OpenBSD. If the OS supports no alternative event
notification mechanism, setting ST_EVENTSYS_ALT has no effect
and the ST_EVENTSYS_DEFAULT mechanism will be used. |
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EINVAL |
The supplied eventsys parameter has an invalid value.
|
| EBUSY |
The event notification mechanism has already been set.
|
Description
This function sets the event notification mechanism that will be used by
the State Threads library. To have any effect, it must be called
before the st_init() function which performs
the actual initialization. If st_set_eventsys() is not called,
st_init() will set the ST_EVENTSYS_DEFAULT
mechanism. The mechanism cannot be changed once set.
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 ST_EVENTSYS_ALT mechanism if your
application deals with a very large number of network connections of
which only a few are active at once.
Returns the integer value identifying the event notification mechanism
being used by the State Threads library.
Syntax
#include <st.h>
int st_get_eventsys(void);
Parameters
None.
Returns
The integer value identifying the current event notification mechanism.
This value can be one of the following (see st_set_eventsys()):
ST_EVENTSYS_SELECT, ST_EVENTSYS_POLL, or
ST_EVENTSYS_ALT. Future versions of the library may return other
values. If a mechanism hasn't been set yet, a value of -1 is returned.
Description
This function returns the integer value identifying the event notification
mechanism which is actually being used by the State Threads library.
Returns the name of the event notification mechanism being used by the
State Threads library.
Syntax
#include <st.h>
const char *st_get_eventsys_name(void);
Parameters
None.
Returns
The string identifying the current event notification mechanism. If a
mechanism hasn't been set yet (see st_set_eventsys()), an empty string is
returned. Possible return values are "select",
"poll", "kqueue", or "epoll". Future versions
of the library may return other values.
Description
This function returns the string identifying the event notification
mechanism which is actually being used by the State Threads library.
st_set_switch_out_cb()
Set the optional callback function for thread switches.
Syntax
#include <st.h>
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);
Parameters
st_set_switch_in_cb() and st_set_switch_out_cb() have the
following parameter:
cb
A function to be called when a thread is resumed and stopped respectively.
Returns
The previous callback function pointer.
Description
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 NULL pointer to disable the callback (this is the default).
Use st_thread_self() or thread
specific data to differentiate between threads.
These functions can be called at any time.
This feature is available only when ST_SWITCH_CB is defined
in <st.h>.
These functions operate on a thread object of type
st_thread_t.
- st_thread_create()
- st_thread_exit()
- st_thread_join()
- st_thread_self()
- st_thread_interrupt()
- st_sleep()
- st_usleep()
- st_randomize_stacks()
Creates a new thread.
Syntax
#include <st.h>
st_thread_t st_thread_create(void *(*start)(void *arg), void *arg,
int joinable, int stack_size);
Parameters
st_thread_create() has the following parameters:
start
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.
arg
A pointer to the root function's only parameter.
joinable
Specifies whether the thread is joinable or unjoinable. If this parameter
is zero, the thread is unjoinable. Otherwise, it is joinable.
See also st_thread_join().
stack_size
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 stack_size
bytes is used for the memory stack. The other half is used for the register
stack backing store.
Returns
Upon successful completion, a new thread identifier is returned (this
identifier remains valid until the thread returns from its start function).
Otherwise, NULL is returned and errno is set
to indicate the error.
Description
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, stack_size bytes are reserved on the swap
space. The stack pages are not actually used (valid) until touched by the
application.
Terminates the calling thread.
Syntax
#include <st.h>
void st_thread_exit(void *retval);
Parameters
st_thread_exit() has the following parameters:
retval
If the thread is joinable, then the value retval may be retrieved
by st_thread_join(). If a thread returns from its
start function, it acts as if it had called st_thread_exit() with
retval as the value returned.
Returns
Nothing.
Description
This function terminates the calling thread. When a thread exits, per-thread
private data is destroyed by invoking the destructor function for any
non-NULL thread specific values associated with active keys (see
st_key_create()). This function is implicitly called
when a thread returns from its start function.
When the last thread terminates the process exits with a zero status value.
Blocks the calling thread until a specified thread terminates.
Syntax
#include <st.h>
int st_thread_join(st_thread_t thread, void **retvalp);
Parameters
st_thread_join() has the following parameters:
thread
A valid identifier for the thread that is to be joined.
retvalp
If this parameter is not NULL, then the exit value of the
thread will be placed in the location referenced by this parameter
(see st_thread_exit()).
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EINVAL | Target thread is unjoinable. |
| EINVAL | Other thread already waits on the same
joinable thread. |
| EDEADLK | Target thread is the same as the
calling thread. |
| EINTR | Current thread was interrupted by
st_thread_interrupt(). |
Description
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.
Identifies the calling thread.
Syntax
#include <st.h>
st_thread_t st_thread_self(void);
Parameters
None.
Returns
Always returns a valid reference to the calling thread - a self-identity.
Description
This function identifies the calling thread. This is the same identifier
that the creating thread obtains from
st_thread_create().
Interrupts a target thread.
Syntax
#include <st.h>
void st_thread_interrupt(st_thread_t thread);
Parameters
st_thread_interrupt() has the following parameters:
thread
A valid identifier for the thread being interrupted.
Returns
Nothing.
Description
This function interrupts (unblocks) a target thread that is blocked in one
of the blocking functions. A function that was interrupted
returns an error and sets errno to EINTR. It is up to
the target thread to act upon an interrupt (e.g., it may exit or just
abort the current transaction).
Note: State Threads library functions are never interrupted by a
caught signal. A blocking library function returns an error and sets
errno to EINTR only if the current thread was
interrupted via st_thread_interrupt().
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.
Suspends current thread for a specified amount of time.
Syntax
#include <st.h>
int st_sleep(int secs);
int st_usleep(st_utime_t usecs);
Parameters
st_sleep() has the following parameters:
secs
The number of seconds you want the thread to sleep for.
st_usleep() has the following parameters:
usecs
The number of microseconds you want the thread to sleep for. This parameter
is a variable of type st_utime_t.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
Description
These functions suspend the calling thread from execution for a specified
number of seconds (st_sleep()) or microseconds (st_usleep()).
If zero is passed as a parameter to st_sleep(), or
ST_UTIME_NO_WAIT (0) is passed to
st_usleep(), the calling thread yields, thus potentially
allowing another thread to run.
If -1 is passed as a parameter to st_sleep(), or
ST_UTIME_NO_TIMEOUT (-1) is passed to
st_usleep(), the calling thread will be suspended permanently.
It can be resumed again by interrupting it via st_thread_interrupt().
Turns stack base address randomization on or off.
Syntax
#include <st.h>
int st_randomize_stacks(int on);
Parameters
st_randomize_stacks() has the following parameters:
on
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.
Returns
The previous state of stack randomization (a value of 0 if it
was off and a non-zero value otherwise).
Description
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.
When randomization is enabled, new stacks are allocated one page larger
to accomodate the randomization.
This call affects only threads created afterward. It has no effect on
existing threads.
These functions allow to associate private data with each of the threads in
a process.
- st_key_create()
- st_key_getlimit()
- st_thread_setspecific()
- st_thread_getspecific()
Creates a key (non-negative integer) that can be used by all
threads in the process to get and set thread-specific data.
Syntax
#include <st.h>
int st_key_create(int *keyp, void (*destructor)(void *));
Parameters
st_key_create() has the following parameters:
keyp
The newly created key is returned in the memory pointed to by this parameter.
The new key can be used with
st_thread_setspecific() and
st_thread_getspecific().
destructor
Specifies an optional destructor function for the private data associated
with the key. This function can be specified as NULL.
Upon thread exit (see st_thread_exit()), if a key
has a non-NULL destructor and has a non-NULL value
associated with that key, then the destructor function will be
called with the associated value.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EAGAIN | The limit on the total number of keys per
process has been exceeded (see st_key_getlimit()).
|
Description
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 NULL associated with that key.
After a new thread is created, the value NULL is associated with
all keys for that thread. If a non-NULL 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 NULL:
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.
Returns the key limit.
Syntax
#include <st.h>
int st_key_getlimit(void);
Parameters
None.
Returns
The limit on the total number of keys per process.
Description
This function can be used to obtain the limit on the total number of keys
per process (see st_key_create()).
Sets per-thread private data.
Syntax
#include <st.h>
int st_thread_setspecific(int key, void *value);
Parameters
st_thread_setspecific() has the following parameters:
key
This parameter represents a key with which thread-specific data is associated.
value
The per-thread private data, or more likely, a pointer to the data which is
associated with key.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EINVAL | The specified key is invalid. |
Description
This function associates a thread-specific value with key.
Different threads may bind different values to the same key.
If the thread already has non-NULL private data associated with
key, and if the destructor function for that key is not
NULL, this destructor function will be called before setting the
new data value.
Retrieves the per-thread private data for the current thread.
Syntax
#include <st.h>
void *st_thread_getspecific(int key);
Parameters
st_thread_getspecific() has the following parameters:
key
This parameter represents a key with which thread-specific data is associated.
Returns
The thread-specific data associated with key. If no data is
associated with key, then NULL is returned.
Description
This function returns the calling thread's value that is bound to the
specified key (see
st_thread_setspecific()).
These functions operate on condition variables
and mutual exclusion locks (mutexes).
Functions are provided to wait on a condition variable and to wake up
(signal) threads that are waiting on the condition variable.
- st_cond_new()
- st_cond_destroy()
- st_cond_wait()
- st_cond_timedwait()
- st_cond_signal()
- st_cond_broadcast()
- st_mutex_new()
- st_mutex_destroy()
- st_mutex_lock()
- st_mutex_trylock()
- st_mutex_unlock()
Creates a new condition variable.
Syntax
#include <st.h>
st_cond_t st_cond_new(void);
Parameters
None.
Returns
Upon successful completion, a new condition variable identifier is returned.
Otherwise, NULL is returned and errno is set
to indicate the error.
Description
This function creates a new condition variable.
Destroys a condition variable.
Syntax
#include <st.h>
int st_cond_destroy(st_cond_t cvar);
Parameters
st_cond_destroy() has the following parameters:
cvar
An identifier of the condition variable object to be destroyed.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EBUSY | The condition variable is currently being
used by one or more threads. |
Description
This function destroys a condition variable. The caller is responsible for
ensuring that the condition variable is no longer in use.
Waits on a condition.
Syntax
#include <st.h>
int st_cond_wait(st_cond_t cvar);
Parameters
st_cond_wait() has the following parameters:
cvar
The condition variable on which to wait.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
Description
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.
Note: 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
blocking functions between the condition checking and
the st_cond_wait() call.
Waits on a condition.
Syntax
#include <st.h>
int st_cond_timedwait(st_cond_t cvar, st_utime_t timeout);
Parameters
st_cond_timedwait() has the following parameters:
cvar
The condition variable on which to wait.
timeout
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 st_utime_t. Note that this
time value is a time delta; it is not an absolute time.
Also note that timeouts are measured since
the last context switch.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
Description
This function works the same way as st_cond_wait(),
except that an error is returned if the number of microseconds specified by
timeout passes before the waiting thread is signalled.
Unblocks a thread waiting on a condition variable.
Syntax
#include <st.h>
int st_cond_signal(st_cond_t cvar);
Parameters
st_cond_signal() has the following parameters:
cvar
The condition variable to signal.
Returns
Always zero.
Description
This function unblocks (signals) one of the threads that are blocked on
cvar at the time of the call. If no thread is waiting on the
condition variable, the signal operation is a no-op.
Unblocks all threads waiting on a condition variable.
Syntax
#include <st.h>
int st_cond_broadcast(st_cond_t cvar);
Parameters
st_cond_broadcast() has the following parameters:
cvar
The condition variable to broadcast.
Returns
Always zero.
Description
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.
Creates a new mutual exclusion lock (mutex).
Syntax
#include <st.h>
st_mutex_t st_mutex_new(void);
Parameters
None.
Returns
Upon successful completion, a new mutex identifier is returned.
Otherwise, NULL is returned and errno is set to
indicate the error.
Description
This function creates a new opaque mutual exclusion lock (see
st_mutex_t).
Destroys a specified mutex object.
Syntax
#include <st.h>
int st_mutex_destroy(st_mutex_t lock);
Parameters
st_mutex_destroy() has the following parameters:
lock
An identifier of the mutex object to be destroyed.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EBUSY | The mutex is currently being used by
other threads. |
Description
This function destroys a mutex. The caller is responsible for ensuring
that the mutex is no longer in use.
Locks a specified mutex object.
Syntax
#include <st.h>
int st_mutex_lock(st_mutex_t lock);
Parameters
st_mutex_lock() has the following parameters:
lock
An identifier of the mutex object to be locked.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EDEADLK | The current thread already owns the mutex.
|
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
Description
A thread that calls this function will block until it can gain exclusive
ownership of a mutex, and retains ownership until it calls
st_mutex_unlock().
Attempts to acquire a mutex.
Syntax
#include <st.h>
int st_mutex_trylock(st_mutex_t lock);
Parameters
st_mutex_trylock() has the following parameters:
lock
An identifier of the mutex object to be locked.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EBUSY | The mutex is currently held by another
thread. |
Description
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.
Releases a specified mutex object.
Syntax
#include <st.h>
int st_mutex_unlock(st_mutex_t lock);
Parameters
st_mutex_unlock() has the following parameters:
lock
An identifier of the mutex object to be unlocked.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error:
| EPERM | The current thread does not own the mutex.
|
Description
This function releases a specified mutex object previously acquired by
st_mutex_lock() or
st_mutex_trylock(). Only the thread that locked
a mutex should unlock it.
- st_utime()
- st_set_utime_function()
- st_timecache_set()
- st_time()
Returns current high-resolution time.
Syntax
#include <st.h>
st_utime_t st_utime(void);
Parameters
None.
Returns
Current high-resolution time value of type
st_utime_t.
Description
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 st_utime_t and st_time().
Set high-resolution time function.
Syntax
#include <st.h>
int st_set_utime_function(st_utime_t (*func)(void));
Parameters
st_set_utime_function() has the following parameters:
func
This function will be called to get high-resolution time instead of the
default st_utime() function. It must return
number of microseconds since some arbitrary time in the past.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to EINVAL to indicate the error.
Description
This function may be called to replace the default implementation of the
st_utime() function. It must be called before the ST
library has been initialized (see st_init()).
The user-provided function func will be invoked whenever
st_utime() 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.
Turns the time caching on or off.
Syntax
#include <st.h>
int st_timecache_set(int on);
Parameters
st_timecache_set() has the following parameters:
on
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.
Returns
The previous state of time caching (a value of 0 if it was off and
a value of 1 otherwise).
Description
The State Threads library has the ability to "cache" the time value that is
reported by the time(2) system call. If the time caching is enabled
by calling this function with a non-zero argument, then the result value
of time(2) will be stored and updated at most once per second. The
cached time can be retrieved by st_time().
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.
Note: 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
always need "real-time" time values, don't enable the time caching.
Returns the value of time in seconds since 00:00:00 UTC, January 1, 1970.
Syntax
#include <st.h>
time_t st_time(void);
Parameters
None.
Returns
The value of time in seconds since 00:00:00 UTC, January 1, 1970 as reported
by the time(2) system call.
Description
If the time caching was enabled by
st_timecache_set(), then this function returns
the cached result. Otherwise, it just calls time(2).
Most State Threads library I/O functions look like corresponding C library
functions with two exceptions:
- They operate on file descriptor objects of type
st_netfd_t.
- They take an additional argument of type
st_utime_t which represents an inactivity
timeout: if no I/O is possible during this amount of time, I/O functions
return an error code and set errno to ETIME.
The boundary values ST_UTIME_NO_WAIT (0) and
ST_UTIME_NO_TIMEOUT (-1) 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 since the
last context switch.
- st_netfd_open()
- st_netfd_open_socket()
- st_netfd_free()
- st_netfd_close()
- st_netfd_fileno()
- st_netfd_setspecific()
- st_netfd_getspecific()
- st_netfd_serialize_accept()
- st_netfd_poll()
- st_accept()
- st_connect()
- st_read()
- st_read_fully()
- st_read_resid()
- st_readv()
- st_read_resid()
- st_write()
- st_write_resid()
- st_writev()
- st_writev_resid()
- st_recvfrom()
- st_sendto()
- st_recvmsg()
- st_sendmsg()
- st_open()
- st_poll()
Creates a new file descriptor object.
Syntax
#include <st.h>
st_netfd_t st_netfd_open(int osfd);
Parameters
st_netfd_open() has the following parameters:
osfd
Any open OS file descriptor; can be obtained from calls to
functions including, but not restricted to, pipe(2), socket(3),
socketpair(3), fcntl(2), dup(2), etc.
Returns
Upon successful completion, a new file descriptor object identifier is
returned. Otherwise, NULL is returned and errno is set
to indicate the error.
Description
This function creates a new file descriptor object of type
st_netfd_t.
Note: 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 st_netfd_t
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 dup(2), this applies to
dup()'ed file descriptors as well - for instance, if you pass
standard output or standard input to st_netfd_open(), then
you should use st_write() instead of write
or fprintf when writing to standard error as well - since all
three descriptors could point to the same terminal. If necessary, you
can still use write directly if you remember to check
errno for EAGAIN, but fprintf 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 st_netfd_open() or st_netfd_open_socket(), or which are
related to such descriptors through dup(); other file
descriptors are untouched by State Threads.)
Creates a new file descriptor object from a socket.
Syntax
#include <st.h>
st_netfd_t st_netfd_open_socket(int osfd);
Parameters
st_netfd_open_socket() has the following parameters:
osfd
An open OS file descriptor which is a socket initially obtained from a
socket(3) or socketpair(3) call.
Returns
Upon successful completion, a new file descriptor object identifier is
returned. Otherwise, NULL is returned and errno is set
to indicate the error.
Description
This function creates a new file descriptor object of type
st_netfd_t which represents an open end
point of network communication.
Unlike the st_netfd_open() function which may be used
on OS file descriptors of any origin, st_netfd_open_socket() must
be used only on sockets. It is slightly more efficient than
st_netfd_open().
Note: Among other things, this function sets a non-blocking flag
on the underlying OS socket. You should not modify this flag directly.
See st_netfd_open().
Frees a file descriptor object without closing the underlying OS file
descriptor.
Syntax
#include <st.h>
void st_netfd_free(st_netfd_t fd);
Parameters
st_netfd_free() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
Returns
Nothing.
Description
This function frees the memory and other resources identified by the
fd parameter without closing the underlying OS file descriptor.
Any non-NULL descriptor-specific data is destroyed by invoking
the specified destructor function (see st_netfd_setspecific()). A thread should
not free file descriptor objects that are in use by other threads
because it may lead to unpredictable results (e.g., a freed file
descriptor may be reused without other threads knowing that).
Closes a file descriptor.
Syntax
#include <st.h>
int st_netfd_close(st_netfd_t fd);
Parameters
st_netfd_close() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error.
Description
This function closes the underlying OS file descriptor, frees the memory and
other resources identified by the fd parameter. Any non-NULL
descriptor-specific data is destroyed by invoking the specified destructor
function (see st_netfd_setspecific()).
A thread should not close file descriptor objects that are in use by other
threads because it may lead to unpredictable results (e.g., a closed
file descriptor may be reused without other threads knowing that).
Returns an underlying OS file descriptor.
Syntax
#include <st.h>
int st_netfd_fileno(st_netfd_t fd);
Parameters
st_netfd_fileno() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
Returns
An underlying OS file descriptor.
Description
This function returns the integer OS file descriptor associated with the named
file descriptor object.
Sets per-descriptor private data.
Syntax
#include <st.h>
void st_netfd_setspecific(st_netfd_t fd, void *value,
void (*destructor)(void *));
Parameters
st_netfd_setspecific() has the following parameters:
fd
A valid file descriptor object identifier (see
st_netfd_t).
value
The per-descriptor private data, or more likely, a pointer to the data which
is being associated with the named file descriptor object.
destructor
Specifies an optional destructor function for the private data associated
with fd. This function can be specified as NULL.
If value is not NULL, then this destructor function will
be called with value as an argument upon freeing the file descriptor
object (see st_netfd_free() and
st_netfd_close()).
Returns
Nothing.
Description
This function allows to associate any data with the specified file
descriptor object (network connection). If a non-NULL destructor
function is registered, it will be called at one of two times, as long as
the associated data is not NULL:
Retrieves the per-descriptor private data.
Syntax
#include <st.h>
void *st_netfd_getspecific(st_netfd_t fd);
Parameters
st_netfd_getspecific() has the following parameters:
fd
A valid file descriptor object identifier (see
st_netfd_t).
Returns
The data associated with the named file descriptor object. If no data is
associated with fd, then NULL is returned.
Description
This function allows to retrieve the data that was associated with the
specified file descriptor object (see
st_netfd_setspecific()).
Serializes all subsequent accept(3) calls on a specified file
descriptor object.
Syntax
#include <st.h>
int st_netfd_serialize_accept(st_netfd_t fd);
Parameters
st_netfd_serialize_accept() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) which has been successfully created
from a valid listening socket by st_netfd_open() or
st_netfd_open_socket().
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error.
Description
On some platforms (e.g., Solaris 2.5 and possibly other SVR4 implementations)
accept(3) calls from different processes on
the same listening socket (see bind(3), listen(3)) must be
serialized. This function causes all subsequent accept(3) calls
made by st_accept() on the specified file descriptor
object to be serialized.
st_netfd_serialize_accept() must be called before
creating multiple server processes via fork(2). If the application
does not create multiple processes to accept network connections on
the same listening socket, there is no need to call this function.
Deciding whether or not to serialize accepts is tricky. On some
platforms (IRIX, Linux) it's not needed at all and
st_netfd_serialize_accept() is a no-op. On other platforms
it depends on the version of the OS (Solaris 2.6 doesn't need it but
earlier versions do). Serializing accepts does incur a slight
performance penalty so you want to enable it only if necessary. Read
your system's manual pages for accept(2) and select(2)
to see if accept serialization is necessary on your system.
st_netfd_serialize_accept() allocates resources that are
freed upon freeing of the specified file descriptor object (see
st_netfd_free() and
st_netfd_close()).
Waits for I/O on a single file descriptor object.
Syntax
#include <st.h>
int st_netfd_poll(st_netfd_t fd, int how, st_utime_t timeout);
Parameters
st_netfd_poll() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
how
Specifies I/O events of interest. This parameter can be constructed by
OR-ing any combination of the following event flags which are defined
in the poll.h header file:
| POLLIN | fd is readable. |
| POLLOUT | fd is is writable. |
| POLLPRI | fd has an exception condition. |
timeout
Amount of time in microseconds the call will block waiting for I/O
to become ready. This parameter is a variable of type
st_utime_t. If this time expires without any
I/O becoming ready, st_netfd_poll() returns an error and sets
errno to ETIME.
Note that timeouts are measured since the
last context switch.
Returns
If the named file descriptor object is ready for I/O within the specified
amount of time, a value of 0 is returned. Otherwise, a value
of -1 is returned and errno is set to indicate the error:
| EBADF | The underlying OS file descriptor is invalid.
|
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred without any I/O
becoming ready. |
Description
This function returns as soon as I/O is ready on the named file
descriptor object or the specified amount of time expires. The
how parameter should be set to the I/O events (readable,
writable, exception, or some combination) that the caller is interested
in. If the value of timeout is ST_UTIME_NO_TIMEOUT
(-1), this function blocks until a requested I/O event occurs
or until the call is interrupted by st_thread_interrupt().
Despite having an interface like poll(2), this function uses
the same event notification mechanism as the rest of the library. For
instance if an alternative event nofication mechanism was set using st_set_eventsys(), this function uses that
mechanism to check for events.
Note: if kqueue(2) is used as an alternative event
notification mechanism (see st_set_eventsys()), the POLLPRI
event flag is not supported and st_netfd_poll() will return an error
if it's set (errno will be set to EINVAL).
Accepts a connection on a specified file descriptor object.
Syntax
#include <st.h>
st_netfd_t st_accept(st_netfd_t fd, struct sockaddr *addr, int *addrlen,
st_utime_t timeout);
Parameters
st_accept() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing the rendezvous socket
on which the caller is willing to accept new connections. This object has been
created from a valid listening socket by
st_netfd_open() or
st_netfd_open_socket().
addr
If this value is non-zero, it is a result parameter that is filled
in with the address of the connecting entity, as known to the communications
layer (see accept(3)).
addrlen
This parameter should initially contain the amount of space pointed to by
addr; on return it will contain the actual length (in bytes) of the
address returned (see accept(3)).
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the accept operation.
Note that timeouts are measured since the
last context switch.
Returns
Upon successful completion, a new file descriptor object identifier
representing the newly accepted connection is returned. Otherwise,
NULL is returned and errno is set to indicate the error.
Possible errno values are the same as set by the accept(3)
call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no pending
connection was accepted. |
Description
This function accepts the first connection from the queue of pending
connections and creates a new file descriptor object for the newly
accepted connection. The rendezvous socket can still be used to accept
more connections.
st_accept() blocks the calling thread until either a new connection
is successfully accepted or an error occurs. If no pending connection can
be accepted before the time limit, this function returns NULL
and sets errno to ETIME.
Initiates a connection on a specified file descriptor object.
Syntax
#include <st.h>
int st_connect(st_netfd_t fd, struct sockaddr *addr, int addrlen,
st_utime_t timeout);
Parameters
st_connect() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing a socket.
addr
A pointer to the address of the peer to which the socket is to be connected.
addrlen
This parameter specifies the amount of space pointed to by addr.
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the connect operation.
Note that timeouts are measured since the
last context switch.
Returns
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error. Possible errno values are the same as set
by the connect(3) call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and connection setup
was not completed. |
Description
This function is usually invoked on a file descriptor object representing
a TCP socket. Upon completion it establishes a TCP connection to the peer.
If the underlying OS socket is not bound, it will be bound to an arbitrary
local address (see connect(3)).
st_connect() blocks the calling thread until either the connection
is successfully established or an error occurs. If the connection setup
cannot complete before the specified time limit, this function fails with
errno set to ETIME.
Reads data from a specified file descriptor object.
Syntax
#include <st.h>
ssize_t st_read(st_netfd_t fd, void *buf, size_t nbyte, st_utime_t timeout);
Parameters
st_read() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
buf
A pointer to a buffer to hold the data read in. On output the buffer
contains the data.
nbyte
The size of buf in bytes.
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the read operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes actually
read is returned (a value of 0 means the network connection is
closed or end of file is reached). Otherwise, a value of -1 is
returned and errno is set to indicate the error.
Possible errno values are the same as set by the read(2)
call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was read.
|
Description
This function blocks the calling thread until it encounters an end-of-stream
indication, some positive number of bytes (but no more than nbyte
bytes) are read in, a timeout occurs, or an error occurs.
Reads the specified amount of data in full from a file descriptor object.
Syntax
#include <st.h>
ssize_t st_read_fully(st_netfd_t fd, void *buf, size_t nbyte,
st_utime_t timeout);
Parameters
st_read_fully() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
buf
A pointer to a buffer to hold the data read in. On output the buffer
contains the data.
nbyte
The amount of data to be read in full (in bytes). It must not exceed the
size of buf.
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes actually
read is returned (a value less than nbyte means the network
connection is closed or end of file is reached). Otherwise, a value of
-1 is returned and errno is set to indicate the error.
Possible errno values are the same as set by the read(2)
call with two exceptions:
Description
This function blocks the calling thread until the specified amount of data
is read in full, it encounters an end-of-stream indication, a timeout occurs,
or an error occurs.
Reads the specified amount of data in full from a file descriptor object.
Syntax
#include <st.h>
int st_read_resid(st_netfd_t fd, void *buf, size_t *resid,
st_utime_t timeout);
Parameters
st_read_resid() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
buf
A pointer to a buffer to hold the data read in. On output the buffer
contains the data.
resid
A pointer to a number of bytes.
On entry, the amount of data to be read in full.
It must not exceed the size of buf.
On return, the amount of data remaining to be read.
(A non-zero returned value means some but not all of the data was read.)
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success, zero is returned. *resid may be zero, indicating
a complete read, or non-zero, indicating the network
connection is closed or end of file is reached.
Otherwise, a value of -1 is returned, *resid is non-zero,
and errno is set to indicate the error.
Possible errno values are the same as set by the read(2)
call with two exceptions:
Description
This function blocks the calling thread until the specified amount of data
is read in full, it encounters an end-of-stream indication, a timeout occurs,
or an error occurs. It differs from st_read_fully() only in that
it allows the caller to know how many bytes were transferred before an error
occurred.
Reads data from a specified file descriptor object into multiple buffers.
Syntax
#include <st.h>
ssize_t st_readv(st_netfd_t fd, const struct iovec *iov, int iov_size,
st_utime_t timeout);
Parameters
st_readv() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
iov
An array of iovec structures that identify the buffers for holding
the data read in.
On return the buffers contain the data.
iov_size
The number of iovec structures in the iov array.
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the read operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes actually
read is returned (a value of 0 means the network connection is
closed or end of file is reached). Otherwise, a value of -1 is
returned and errno is set to indicate the error.
Possible errno values are the same as set by the readv(2)
call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was read.
|
Description
This function blocks the calling thread until it encounters an end-of-stream
indication, some positive number of bytes (but no more than fit in the buffers)
are read in, a timeout occurs, or an error occurs.
Reads the specified amount of data in full from a file descriptor object
into multiple buffers.
Syntax
#include <st.h>
int st_readv_resid(st_netfd_t fd, struct iovec **iov, int *iov_size,
st_utime_t timeout);
Parameters
st_readv_resid() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
iov
A pointer to an array of iovec structures.
On entry, the iovecs identify the buffers for holding the data read in.
On return, the incomplete iovecs.
This function modifies both the pointer and the array to which it points.
iov_size
A pointer to a number of iovec structures.
On entry, the number of iovec structures pointed to by *iov.
On return, the number of incomplete or unused iovec structures.
(A non-zero returned value means some but not all of the data was read.)
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success, zero is returned. *iov_size may be zero, indicating
a complete read, or non-zero, indicating the network connection is
closed or end of file is reached. *iov points to the first
iovec after the end of the original array on a complete read, or to the
first incomplete iovec on an incomplete read.
Otherwise, a value of -1 is returned, *iov_size is non-zero,
and errno is set to indicate the error. *iov points to the
first unused iovec.
Possible errno values are the same as set by the readv(2)
call with two exceptions:
All of the iovecs before *iov are modified such that
iov_base points to the end of the original buffer and
iov_len is zero.
Description
This function blocks the calling thread until the specified amount of data
is read in full, it encounters an end-of-stream indication, a timeout occurs,
or an error occurs. Like st_read_resid() it blocks the thread until
all of the requested data is read or an error occurs. Use
st_readv() to read up to the requested amount of data.
Writes a buffer of data to a specified file descriptor object.
Syntax
#include <st.h>
ssize_t st_write(st_netfd_t fd, const void *buf, size_t nbyte,
st_utime_t timeout);
Parameters
st_write() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
buf
A pointer to the buffer holding the data to be written.
nbyte
The amount of data in bytes to be written from the buffer.
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer equal to nbyte is returned.
Otherwise, a value of -1 is returned and errno is set
to indicate the error. Possible errno values are the same as set
by the write(2) call with two exceptions:
Description
This function blocks the calling thread until all the data is written,
a timeout occurs, or the write operation fails. The return value is equal to
either nbyte (on success) or -1 (on failure). Note that if
st_write() returns -1, some data (less than nbyte
bytes) may have been written before an error occurred.
Writes a buffer of data to a specified file descriptor object.
Syntax
#include <st.h>
int st_write_resid(st_netfd_t fd, const void *buf, size_t *resid,
st_utime_t timeout);
Parameters
st_write_resid() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
buf
A pointer to the buffer holding the data to be written.
resid
A pointer to a number of bytes.
On entry, the amount of data to be written from the buffer.
On return, the amount of data remaining to be written.
(A non-zero returned value means some but not all of the data was written.)
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success, zero is returned and *resid is zero.
Otherwise, a value of -1 is returned, *resid is non-zero,
and errno is set
to indicate the error. Possible errno values are the same as set
by the write(2) call with two exceptions:
Description
This function blocks the calling thread until all the data is written,
a timeout occurs, or the write operation fails. It differs from
st_write() only in that it allows the caller to know how many bytes
were transferred before an error occurred.
Writes data to a specified file descriptor object from multiple buffers.
Syntax
#include <st.h>
ssize_t st_writev(st_netfd_t fd, const struct iovec *iov, int iov_size,
st_utime_t timeout);
Parameters
st_writev() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
iov
An array of iovec structures that describe the buffers to write
from (see writev(2)).
iov_size
Number of iovec structures in the iov array.
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer equal to the sum of all the buffer lengths
is returned. Otherwise, a value of -1 is returned and errno
is set to indicate the error. Possible errno values are the same as
set by the writev(2) call with two exceptions:
Description
This function blocks the calling thread until all the data is written,
a timeout occurs, or the write operation fails. The return value is equal to
either the sum of all the buffer lengths (on success) or -1 (on
failure). Note that if st_writev() returns -1, part of the
data may have been written before an error occurred.
Writes multiple buffers of data to a specified file descriptor object.
Syntax
#include <st.h>
int st_writev_resid(st_netfd_t fd, struct iovec **iov, int *iov_size,
st_utime_t timeout);
Parameters
st_writev_resid() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t).
iov
A pointer to an array of iovec structures.
On entry, the iovecs identify the buffers holding the data to write.
On return, the incomplete iovecs.
This function modifies both the pointer and the array to which it points.
iov_size
A pointer to a number of iovec structures.
On entry, the number of iovec structures pointed to by *iov.
On return, the number of incomplete or unused iovec structures.
(A non-zero returned value means some but not all of the data was written.)
timeout
A value of type st_utime_t specifying the
inactivity timeout (in microseconds).
Note that timeouts are measured since the
last context switch.
Returns
On success, zero is returned, *iov_size is zero, and *iov
points to the first iovec after the end of the original array.
Otherwise, a value of -1 is returned, *iov_size is non-zero,
*iov points to the first incomplete iovec, and errno is set
to indicate the error. Possible errno values are the same as set
by the writev(2) call with two exceptions:
All of the iovecs before *iov are modified such that
iov_base points to the end of the original buffer and
iov_len is zero.
Description
This function blocks the calling thread until all the data is written,
a timeout occurs, or the write operation fails. It differs from
st_writev() only in that it allows the caller to know how many bytes
were transferred before an error occurred.
Receives bytes from a file descriptor object and stores the sending peer's
address.
Syntax
#include <st.h>
int st_recvfrom(st_netfd_t fd, void *buf, int len, struct sockaddr *from,
int *fromlen, st_utime_t timeout);
Parameters
st_recvfrom() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing a UDP socket.
buf
A pointer to a buffer to hold the data received.
len
The size of buf in bytes.
from
If this parameter is not a NULL pointer, the source address of the
message is filled in (see recvfrom(3)).
fromlen
This is a value-result parameter, initialized to the size of the buffer
associated with from, and modified on return to indicate the actual
size of the address stored there.
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the receive operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the length of the received
message in bytes is returned. Otherwise, a value of -1 is returned
and errno is set to indicate the error. Possible errno
values are the same as set by the recvfrom(3) call with two
exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was received.
|
Description
This function receives up to a specified number of bytes from the specified
file descriptor object representing a UDP socket.
st_recvfrom() blocks the calling thread until one or more bytes are
transferred, a timeout has occurred, or there is an error. No more than
len bytes will be transferred.
Sends bytes to a specified destination.
Syntax
#include <st.h>
int st_sendto(st_netfd_t fd, const void *msg, int len, struct sockaddr *to,
int tolen, st_utime_t timeout);
Parameters
st_sendto() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing a UDP socket.
msg
A pointer to a buffer containing the message to be sent.
len
The length of the message to be sent (in bytes).
to
A pointer to the address of the destination (see sendto(3)).
tolen
This parameter specifies the size of the destination address.
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the send operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes sent is
returned. Otherwise, a value of -1 is returned and errno is
set to indicate the error. Possible errno values are the same as
set by the sendto(3) call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was sent.
|
Description
This function sends a specified number of bytes from a file descriptor
object representing a UDP socket to the specified destination address.
If no buffer space is available at the underlying OS socket to hold the
message to be transmitted, then st_sendto() blocks the calling
thread until the space becomes available, a timeout occurs, or an error
occurs.
Receives a message from a file descriptor object.
Syntax
#include <st.h>
int st_recvmsg(st_netfd_t fd, struct msghdr *msg, int flags,
st_utime_t timeout);
Parameters
st_recvmsg() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing a UDP socket.
msg
A pointer to a msghdr structure to describe the data received.
flags
Control flags for recvmsg(3).
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the receive operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes received
is returned. Otherwise, a value of -1 is returned
and errno is set to indicate the error. Possible errno
values are the same as set by the recvmsg(3) call with two
exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was received.
|
Description
This function receives bytes from the specified file descriptor object
representing a UDP socket. The operation is controlled by the in/out
msg parameter.
st_recvmsg() blocks the calling thread until one or more bytes are
transferred, a timeout has occurred, or there is an error.
Sends a message to a file descriptor object.
Syntax
#include <st.h>
int st_sendmsg(st_netfd_t fd, const struct msghdr *msg, int flags,
st_utime_t timeout);
Parameters
st_sendmsg() has the following parameters:
fd
A file descriptor object identifier (see
st_netfd_t) representing a UDP socket.
msg
A pointer to a msghdr structure describing the message to be sent.
flags
Control flags for sendmsg(3).
timeout
A value of type st_utime_t specifying the time
limit in microseconds for completion of the send operation.
Note that timeouts are measured since the
last context switch.
Returns
On success a non-negative integer indicating the number of bytes sent is
returned. Otherwise, a value of -1 is returned and errno is
set to indicate the error. Possible errno values are the same as
set by the sendmsg(3) call with two exceptions:
| EINTR | The current thread was interrupted by
st_thread_interrupt(). |
| ETIME | The timeout occurred and no data was sent.
|
Description
This function sends bytes to a file descriptor object representing a UDP
socket. The operation is controlled by the msg parameter.
If no buffer space is available at the underlying OS socket to hold the
message to be transmitted, then st_sendmsg() blocks the calling
thread until the space becomes available, a timeout occurs, or an error
occurs.
Opens a file for reading, writing, or both.
Syntax
#include <st.h>
st_netfd_t st_open(const char *path, int oflags, mode_t mode);
Parameters
st_open() has the following parameters:
path
The pathname of the file to be opened.
oflags
File status flags. These are the same flags that are used by the
open(2) system call.
mode
Access permission bits of the file mode, if the file is created when
O_CREAT is set in oflags (see open(2)).
Returns
Upon successful completion, a new file descriptor object identifier is
returned. Otherwise, NULL is returned and errno is set
to indicate the error.
Description
This function creates a new file descriptor object of type
st_netfd_t for the file with the pathname
path. This object can be freed by
st_netfd_free() or
st_netfd_close().
The primary purpose of this function is to open FIFOs (named pipes) or
other special files in order to create an end point of communication.
However, it can be used on regular files as well.
Among other things, this function always sets a non-blocking flag on the
underlying OS file descriptor, so there is no need to include that flag in
oflags.
Detects when I/O is ready for a set of OS file descriptors.
Syntax
#include <st.h>
int st_poll(struct pollfd *pds, int npds, st_utime_t timeout);
Parameters
st_poll() has the following parameters:
pds
A pointer to an array of pollfd structures (see poll(2)).
npds
The number of elements in the pds array.
timeout
A value of type st_utime_t specifying the
amount of time in microseconds the call will block waiting for I/O
to become ready. If this time expires without any I/O becoming ready,
st_poll() returns zero.
Note that timeouts are measured since the
last context switch.
Returns
Upon successful completion, a non-negative value is returned. A positive
value indicates the total number of OS file descriptors in pds
that have events. A value of 0 indicates that the call timed out.
Upon failure, a value of -1 is returned and errno is set
to indicate the error:
If an alternative event notification mechanism has been set by
st_set_eventsys(), other values of
errno could be set upon failure as well. The values
depend on the specific mechanism in use.
Description
This function returns as soon as I/O is ready on one or more of the specified
OS file descriptors. A count of the number of ready descriptors is returned
unless a timeout occurs, in which case zero is returned.
The pollfd structure is defined in the poll.h header file
and contains the following members:
int fd; /* OS file descriptor */
short events; /* requested events */
short revents; /* returned events */
The events field should be set to the I/O events (readable,
writable, exception, or some combination) that the caller is interested in.
On return, the revents field is set to indicate what kind of I/O
is ready on the respective descriptor.
The events and revents fields are constructed by OR-ing
any combination of the following event flags (defined in poll.h):
| POLLIN | fd is readable. |
| POLLOUT | fd is is writable. |
| POLLPRI | fd has an exception condition. |
| POLLNVAL | fd is bad. |
The POLLNVAL flag is only valid in the revents field;
it is not used in the events field.
Despite having an interface like poll(2), this function uses
the same event notification mechanism as the rest of the library. For
instance if an alternative event nofication mechanism was set using st_set_eventsys(), this function uses that
mechanism to check for events.
Note that unlike the poll(2) call, this function has the
timeout parameter expressed in microseconds. If the value of
timeout is ST_UTIME_NO_TIMEOUT
(-1), this function blocks until a requested I/O
event occurs or until the call is interrupted by
st_thread_interrupt().
Note: if kqueue(2) is used as an alternative event
notification mechanism (see st_set_eventsys()), the POLLPRI
event flag is not supported and st_poll() will return an error
if it's set (errno will be set to EINVAL).
Generally, the following steps should be followed when writing an application
using the State Threads library:
- Configure the library by calling these pre-init functions, if desired.
- Initialize the library by calling st_init().
- Configure the library by calling these post-init functions, if desired.
- Create resources that will be shared among different processes:
create and bind listening sockets (see socket(3),
bind(3), listen(3),
st_netfd_open_socket(), and possibly
st_netfd_serialize_accept()),
create shared memory segments, inter-process communication (IPC)
channels and synchronization primitives (if any).
- Create several processes via fork(2). The parent process should
either exit or become a "watchdog" (e.g., it starts a new process when
an existing one crashes, does a cleanup upon application termination,
etc.).
- In each child process create a pool of threads (see
st_thread_create()) to handle user
connections. Each thread in the pool may accept client connections
(st_accept()), connect to other servers
(st_connect()), perform various network I/O
(st_read(), st_write(), etc.).
Note that only State Threads library I/O functions should
be used for a network I/O: any other I/O calls may block the calling process
indefinitely. For example, standard I/O functions (fgets(3),
fread(3), fwrite(3), fprintf(3), etc.) call
read(2) and write(2) directly and therefore should not be
used on sockets or pipes.
Also note that for short timeouts to work the program
should do context switches (for example by calling
st_usleep()) on a regular basis.
The thread context switch (process state change) can only happen
in a well-known set of blocking functions.
Only the following functions can block the calling thread:
- st_thread_join()
- st_sleep()
- st_usleep()
- st_cond_wait()
- st_cond_timedwait()
- st_mutex_lock()
- st_netfd_poll()
- st_accept()
- st_connect()
- st_read()
- st_read_fully()
- st_read_resid()
- st_readv()
- st_readv_resid()
- st_write()
- st_write_resid()
- st_writev()
- st_writev_resid()
- st_recvfrom()
- st_sendto()
- st_recvmsg()
- st_sendmsg()
- st_poll()