1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
zmq_poll(3)
===========
NAME
----
zmq_poll - input/output multiplexing
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:
["literal", subs="quotes"]
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 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'
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 wait
indefinitely for requested events to occur.
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 0MQ sockets, at least one message may be dequeued from the underlying
_message queue_ associated with '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 0MQ sockets, at least one message may be queued on the underlying
_message queue_ associated with '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 0MQ 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 the
'timeout' period has expired and no events have been signaled. Upon failure,
_zmq_poll()_ shall return -1 and set 'errno' to one of the values defined
below.
ERRORS
------
*EFAULT*::
At least one of the members of the 'items' array refers to a 'socket' belonging
to a different application thread.
*ENOTSUP*::
At least one of the members of the 'items' array refers to a 'socket' whose
associated 0MQ 'context' was initialised without the 'ZMQ_POLL' flag.
EXAMPLE
-------
.Polling idenfinitely for input events on both a 0MQ 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 */
----
SEE ALSO
--------
linkzmq:zmq_socket[3]
linkzmq:zmq_send[3]
linkzmq:zmq_recv[3]
linkzmq:zmq[7]
Your operating system documentation for the _poll()_ system call.
AUTHORS
-------
The 0MQ documentation was written by Martin Sustrik <sustrik@250bpm.com> and
Martin Lucina <mato@kotelna.sk>.
|
