zmq_poll(3)

SYNOPSIS

int zmq_poll (zmq_pollitem_t *items, int nitems, long timeout);

DESCRIPTION

The zmq_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 zmq_pollitem_t -structure. The nitems argument specifies the number of items in the items -array. The zmq_pollitem_t structure is defined as follows:

typedef struct
-{
-    void *socket;
-    int fd;
-    short events;
-    short revents;
-} zmq_pollitem_t;

For each zmq_pollitem_t item, zmq_poll() shall examine either the ØMQ -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 zmq_pollitem_t, the ØMQ socket referenced by -socket shall take precedence and the value of fd shall be ignored.

- - - -

Note

All ØMQ sockets passed to the zmq_poll() function must share the -same ØMQ context and must belong to the thread calling zmq_poll().

For each zmq_pollitem_t item, zmq_poll() shall first clear the revents -member, and then indicate any requested events that have occured by setting the -bit corresponding to the event condition in the revents member.

If none of the requested events have occured on any zmq_pollitem_t item, -zmq_poll() shall wait up to timeout microseconds for an event to occur on -any of the requested items. If the value of timeout is 0, zmq_poll() -shall return immediately. If the value of timeout is -1, zmq_poll() shall -block indefinitely until a requested event has occured on at least one -zmq_pollitem_t.

The events and revents members of zmq_pollitem_t are bitmasks constructed -by OR’ing a combination of the following event flags:

-ZMQ_POLLIN -: -
-For ØMQ 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. -
-
-ZMQ_POLLOUT -: -
-For ØMQ 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. -
-
-ZMQ_POLLERR -: -
-For standard sockets, this flag is passed through zmq_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 ØMQ sockets this flag -has no effect if set in events, and shall never be returned in revents by -zmq_poll(). -
-

- - - -

Note

The zmq_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 zmq_poll() function shall return the number -of zmq_pollitem_t structures with events signaled in revents or 0 if no -events have been signaled. Upon failure, zmq_poll() shall return -1 and set -errno to one of the values defined below.

- - - -

Important

The zmq_poll() function may return before the timeout period -has expired even if no events have been signaled.

ERRORS

-EFAULT -: -
-At least one of the members of the items array refers to a socket belonging -to a different application thread. -
-
-ETERM -: -
-At least one of the members of the items array refers to a socket whose -associated ØMQ context was terminated. -
-
-EFAULT -: -
-The provided items was not valid (NULL). -
-

EXAMPLE

Polling indefinitely for input events on both a ØMQ socket and a standard socket.

zmq_pollitem_t items [2];
-/* First item refers to 0MQ socket 'socket' */
-items[0].socket = socket;
-items[0].events = ZMQ_POLLIN;
-/* Second item refers to standard socket 'fd' */
-items[1].socket = NULL;
-items[1].fd = fd;
-items[1].events = ZMQ_POLLIN;
-/* Poll for events indefinitely */
-int rc = zmq_poll (items, 2, -1);
-assert (rc >= 0);
-/* Returned events will be stored in items[].revents */

AUTHORS

The ØMQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and -Martin Lucina <mato@kotelna.sk>.

-zmq_poll(3) Manual Page -

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLE

SEE ALSO

AUTHORS