XS_POLL(3) Crossroads I/O Manual XS_POLL(3)NAMExs_poll - input/output multiplexing
SYNOPSIS
int xs_poll (xs_pollitem_t *items, int nitems, int timeout);
DESCRIPTION
The xs_poll() function provides a mechanism for applications to
multiplex input/output events in a level-triggered fashion over a set
of sockets. Each member of the array pointed to by the items argument
is a xs_pollitem_t structure. The nitems argument specifies the number
of items in the items array. The xs_pollitem_t structure is defined as
follows:
typedef struct
{
void *socket;
int fd;
short events;
short revents;
} xs_pollitem_t;
For each xs_pollitem_t item, xs_poll() shall examine either the
Crossroads socket referenced by socket or the standard socket specified
by the file descriptor fd, for the event(s) specified in events. If
both socket and fd are set in a single xs_pollitem_t, the Crossroads
socket referenced by socket shall take precedence and the value of fd
shall be ignored.
For each xs_pollitem_t item, xs_poll() shall first clear the revents
member, and then indicate any requested events that have occurred by
setting the bit corresponding to the event condition in the revents
member.
If none of the requested events have occurred on any xs_pollitem_t
item, xs_poll() shall wait timeout milliseconds for an event to occur
on any of the requested items. If the value of timeout is 0, xs_poll()
shall return immediately. If the value of timeout is -1, xs_poll()
shall block indefinitely until a requested event has occurred on at
least one xs_pollitem_t.
The events and revents members of xs_pollitem_t are bit masks
constructed by OR’ing a combination of the following event flags:
XS_POLLIN
For Crossroads sockets, at least one message may be received from
the socket without blocking. For standard sockets this is
equivalent to the POLLIN flag of the poll() system call and
generally means that at least one byte of data may be read from fd
without blocking.
XS_POLLOUT
For Crossroads sockets, at least one message may be sent to the
socket without blocking. For standard sockets this is equivalent to
the POLLOUT flag of the poll() system call and generally means that
at least one byte of data may be written to fd without blocking.
XS_POLLERR
For standard sockets, this flag is passed through xs_poll() to the
underlying poll() system call and generally means that some sort of
error condition is present on the socket specified by fd. For
Crossroads sockets this flag has no effect if set in events, and
shall never be returned in revents by xs_poll().
Note
The xs_poll() function may be implemented or emulated using
operating system interfaces other than poll(), and as such may be
subject to the limits of those interfaces in ways not defined in
this documentation.
RETURN VALUE
Upon successful completion, the xs_poll() function shall return the
number of xs_pollitem_t structures with events signaled in revents or 0
if no events have been signaled. Upon failure, xs_poll() shall return
-1 and set errno to one of the values defined below.
ERRORS
ETERM
At least one of the members of the items array refers to a socket
whose associated context was terminated.
EFAULT
The provided items was not valid (NULL).
EINTR
The operation was interrupted by delivery of a signal before any
events were available.
EXAMPLE
Polling indefinitely for input events on both a Crossroads socket and a
standard socket..
xs_pollitem_t items [2];
/* First item refers to Crossroads socket 'socket' */
items[0].socket = socket;
items[0].events = XS_POLLIN;
/* Second item refers to standard socket 'fd' */
items[1].socket = NULL;
items[1].fd = fd;
items[1].events = XS_POLLIN;
/* Poll for events indefinitely */
int rc = xs_poll (items, 2, -1);
assert (rc >= 0);
/* Returned events will be stored in items[].revents */
SEE ALSOxs_socket(3)xs_send(3)xs_recv(3)xs(7)
Your operating system documentation for the poll() system call.
AUTHORS
The Crossroads documentation was written by Martin Sustrik
<sustrik@250bpm.com[1]> and Martin Lucina <martin@lucina.net[2]>.
NOTES
1. sustrik@250bpm.com
mailto:sustrik@250bpm.com
2. martin@lucina.net
mailto:martin@lucina.net
Crossroads I/O 1.2.0 02/17/2016 XS_POLL(3)
