zmq_poll.txt 4.91 KB
Newer Older
1 2 3 4 5 6
zmq_poll(3)
===========


NAME
----
Martin Lucina's avatar
Martin Lucina committed
7
zmq_poll - input/output multiplexing
8 9 10 11


SYNOPSIS
--------
Martin Lucina's avatar
Martin Lucina committed
12 13

*int zmq_poll (zmq_pollitem_t '*items', int 'nitems', long 'timeout');*
14 15 16 17


DESCRIPTION
-----------
Martin Lucina's avatar
Martin Lucina committed
18 19 20 21 22
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:
23

Martin Lucina's avatar
Martin Lucina committed
24
["literal", subs="quotes"]
25 26
typedef struct
{
Martin Lucina's avatar
Martin Lucina committed
27 28 29 30
    void '*socket';
    int 'fd';
    short 'events';
    short 'revents';
31 32
} zmq_pollitem_t;

Martin Lucina's avatar
Martin Lucina committed
33 34 35 36 37 38 39
For each *zmq_pollitem_t* item, _zmq_poll()_ shall examine either the 0MQ
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 0MQ socket referenced by
'socket' shall take precedence and the value of 'fd' shall be ignored.

For each *zmq_pollitem_t* item, _zmq_poll()_ shall first clear the 'revents'
40
member, and then indicate any requested events that have occurred by setting the
Martin Lucina's avatar
Martin Lucina committed
41 42
bit corresponding to the event condition in the 'revents' member.

43
If none of the requested events have occurred on any *zmq_pollitem_t* item,
44
_zmq_poll()_ shall wait 'timeout' milliseconds for an event to occur on
Martin Lucina's avatar
Martin Lucina committed
45 46
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
47
block indefinitely until a requested event has occurred on at least one
Martin Lucina's avatar
Martin Lucina committed
48
*zmq_pollitem_t*.
Martin Lucina's avatar
Martin Lucina committed
49

50
The 'events' and 'revents' members of *zmq_pollitem_t* are bit masks constructed
Martin Lucina's avatar
Martin Lucina committed
51
by OR'ing a combination of the following event flags:
52 53

*ZMQ_POLLIN*::
54 55 56 57
For 0MQ 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.
Martin Lucina's avatar
Martin Lucina committed
58

59
*ZMQ_POLLOUT*::
60 61 62 63
For 0MQ 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.
Martin Lucina's avatar
Martin Lucina committed
64 65 66 67 68 69 70

*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 0MQ sockets this flag
has no effect if set in 'events', and shall never be returned in 'revents' by
_zmq_poll()_.
71

72 73 74 75 76 77 78
*ZMQ_POLLPRI*::
For 0MQ sockets this flags is of no use. For standard sockets this means there
is urgent data to read. Refer to the POLLPRI flag for more informations.
For file descriptor, refer to your use case: as an example, GPIO interrupts
are signaled through a POLLPRI event.
This flag has no effect on Windows.

Martin Lucina's avatar
Martin Lucina committed
79 80 81
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.
82

83 84 85 86 87 88 89 90 91 92
THREAD SAFETY
-------------
The *zmq_pollitem_t* array must only be used by the thread which 
will/is calling _zmq_poll_.

If a socket is contained in multiple *zmq_pollitem_t* arrays, each owned by a
different thread, the socket itself needs to be thead-safe (Server, Client, ...).
Otherwise, behaviour is undefined.


93 94
RETURN VALUE
------------
Martin Lucina's avatar
Martin Lucina committed
95
Upon successful completion, the _zmq_poll()_ function shall return the number
96 97 98 99
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.

100 101 102

ERRORS
------
103
*ETERM*::
104 105
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was terminated.
106 107
*EFAULT*::
The provided 'items' was not valid (NULL).
108
*EINTR*::
109 110
The operation was interrupted by delivery of a signal before any events were
available.
111 112 113 114


EXAMPLE
-------
115
.Polling indefinitely for input events on both a 0MQ socket and a standard socket.
116 117
----
zmq_pollitem_t items [2];
Martin Lucina's avatar
Martin Lucina committed
118 119 120
/* First item refers to 0MQ socket 'socket' */
items[0].socket = socket;
items[0].events = ZMQ_POLLIN;
121
/* Second item refers to standard socket 'fd' */
Martin Lucina's avatar
Martin Lucina committed
122 123 124 125 126 127 128
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 */
129 130 131 132 133 134
----


SEE ALSO
--------
linkzmq:zmq_socket[3]
Martin Lucina's avatar
Martin Lucina committed
135 136 137
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
138

Martin Lucina's avatar
Martin Lucina committed
139
Your operating system documentation for the _poll()_ system call.
140

Martin Lucina's avatar
Martin Lucina committed
141

142 143
AUTHORS
-------
144 145
This page was written by the 0MQ community. To make a change please
read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.