NAME

       xs_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 ALSO

       xs_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                               06/13/2012                                         XS_POLL(3)