1ZMQ_POLLER(3)                     0MQ Manual                     ZMQ_POLLER(3)
2
3
4

NAME

6       zmq_poller - input/output multiplexing
7

SYNOPSIS

9       void *zmq_poller_new (void);
10
11       int zmq_poller_destroy (void *poller_p);
12
13       int zmq_poller_size (void *poller);
14
15       int zmq_poller_add (void *poller, void *socket, void *user_data, short
16       events);
17
18       int zmq_poller_modify (void *poller, void *socket, short events);
19
20       int zmq_poller_remove (void *poller, void *socket);
21
22       int zmq_poller_add_fd (void *poller, int fd, void *user_data, short
23       events);
24
25       int zmq_poller_modify_fd (void *poller, int fd, short events);
26
27       int zmq_poller_remove_fd (void *poller, int fd);
28
29       int zmq_poller_wait (void *poller, zmq_poller_event_t *event, long
30       timeout);
31
32       int zmq_poller_wait_all (void *poller, zmq_poller_event_t *events, int
33       n_events, long timeout);
34
35       int zmq_poller_fd (void *poller, zmq_fd_t *fd);
36

DESCRIPTION

38       The zmq_poller*_ functions provide a mechanism for applications to
39       multiplex input/output events in a level-triggered fashion over a set
40       of sockets.
41
42       zmq_poller_new and zmq_poller_destroy manage the lifetime of a poller
43       instance. zmq_poller_new creates and returns a new poller instance,
44       while zmq_poller_destroy destroys it. A pointer to a valid poller must
45       be passed as the poller_p argument of zmq_poller_destroy. In
46       particular, zmq_poller_destroy may not be called multiple times for the
47       same poller instance. zmq_poller_destroy sets the passed pointer to
48       NULL in case of a successful execution. zmq_poller_destroy implicitly
49       unregisters all registered sockets and file descriptors.
50
51       zmq_poller_size queries the number of sockets or file descriptors
52       registered with a poller. The initial size of a poller is 0, a
53       successful add operation increases the size by 1 and a successful
54       remove operation decreases the size by 1. The size is unaffected by the
55       events specified.
56
57       zmq_poller_add, zmq_poller_modify and zmq_poller_remove manage the 0MQ
58       sockets registered with a poller.
59
60       zmq_poller_add registers a new socket with a given poller. Both poller
61       and socket must point to valid 0MQ objects. The events parameter
62       specifies which event types the client wants to subscribe to. It is
63       legal to specify no events (i.e. 0), and activate them later with
64       zmq_poller_modify. In addition, user_data may be specified, which is
65       not used by the poller, but passed back to the caller when an event was
66       signalled in a call to zmq_poller_wait or zmq_poller_wait_all.
67       user_data may be NULL. If it is not NULL, it must be a valid pointer.
68       Otherwise, behaviour is undefined. You must only add a socket to a
69       single poller instance once (unless zmq_poller_remove has been called
70       for that socket before). You may add a socket to multiple poller
71       instances, if the socket itself is explicitly thread-safe (Server,
72       Client, ...). If the socket is not, you may invoke undefined behavior.
73
74       zmq_poller_modify modifies the subscribed events for a socket. It is
75       legal to specify no events (i.e. 0) to disable events temporarily, and
76       reactivate them later with another call to zmq_poller_modify.
77
78       zmq_poller_remove removes a socket registration completely.
79       zmq_poller_remove must be called before a socket is closed with
80       zmq_close.
81
82       Note that it is not necessary to call zmq_poller_remove for any socket
83       before calling zmq_poller_destroy.
84
85       Also note that calling zmq_poller_remove is not equivalent to calling
86       zmq_poller_modify with no events. zmq_poller_modify does not free
87       resources associated with the socket registration, and requires that
88       the socket remains valid.
89
90       zmq_poller_add_fd, zmq_poller_modify_fd and zmq_poller_remove_fd are
91       analogous to the previous functions but manage regular file
92       descriptiors registered with a poller. On Windows, these functions can
93       only be used with WinSock sockets.
94
95       In the following, 0MQ sockets added with zmq_poller_add and file
96       descriptors added with zmq_poller_add_fd are referred to as registered
97       objects.
98
99       The zmq_poller_event_t structure is defined as follows:
100
101           typedef struct
102           {
103               void *socket;
104               zmq_fd_t fd;
105               void *user_data;
106               short events;
107           } zmq_poller_event_t;
108
109       For each registered object, zmq_poller_wait_all() shall examine the
110       registered objects for the event(s) currently registered.
111
112       If none of the registered events have occurred, zmq_poller_wait_all
113       shall wait timeout milliseconds for an event to occur on any of the
114       registered objects. If the value of timeout is 0, zmq_poller_wait_all
115       shall return immediately. If the value of timeout is -1,
116       zmq_poller_wait_all shall block indefinitely until one event has
117       occurred on any of the registered objects.
118
119       The events argument zmq_poller_wait_all must be a pointer to an array
120       of at least n_events elements. Behaviour is undefined if events does
121       not point to an array of at least n_events elements.
122
123       zmq_poller_wait_all returns at most n_events events. If more than
124       n_events events were signalled, only an unspecified subset of the
125       signalled events is returned through events.
126
127       A caller is advised to ensure that n_events is equal to the number of
128       registered objects. Otherwise, a livelock situation may result: If more
129       than n_events registered objects have an active event on each call to
130       zmq_poller_wait_all, it might happen that the same subset of registered
131       objects is always returned, and the caller never notices the events on
132       the others. The number of objects registered can be queried with
133       zmq_poller_size.
134
135       zmq_poller_wait_all returns the number of valid elements. The valid
136       elements are placed in positions 0 to n_events - 1 in the events array.
137       All members of a valid element are set to valid values by
138       zmq_poller_wait_all. For socket events socket is non-null and fd is an
139       operating system specific value for an invalid socket (-1 or
140       INVALID_SOCKET). For fd events socket is NULL and fd is a valid file
141       descriptor. The client does therefore not need to initialize the
142       contents of the events array before a call to zmq_poller_wait_all. It
143       is unspecified whether the the remaining elements of events are written
144       to by zmq_poller_wait_all.
145
146       zmq_poller_fd queries the file descriptor associated with the
147       zmq_poller, and stores it in the address pointer to by fd. The
148       zmq_poller is only guaranteed to have a file descriptor if at least one
149       thread-safe socket is currently registered.
150
151       Note that closing a socket that is registered in a poller leads to
152       undefined behavior. The socket must be unregistered first.
153

EVENT TYPES

155       The events parameter of zmq_poller_add and zmq_poller_modify, and the
156       events member of the zmq_poller_event_t structure are bit masks
157       constructed by OR’ing a combination of the following event flags:
158
159       ZMQ_POLLIN
160           For 0MQ sockets, at least one message may be received from the
161           socket without blocking. For standard sockets this is equivalent to
162           the POLLIN flag of the poll() system call and generally means that
163           at least one byte of data may be read from fd without blocking.
164
165       ZMQ_POLLOUT
166           For 0MQ sockets, at least one message may be sent to the socket
167           without blocking. For standard sockets this is equivalent to the
168           POLLOUT flag of the poll() system call and generally means that at
169           least one byte of data may be written to fd without blocking.
170
171       ZMQ_POLLERR
172           For 0MQ sockets this flag has no effect on the zmq_poller_add and
173           zmq_poller_modify functions, and is never set in the events member
174           of the zmq_poller_event_t structure. For standard sockets, this
175           flag is passed through zmq_poller_wait_all to the underlying poll()
176           system call and generally means that some sort of error condition
177           is present on the socket specified by fd.
178
179       ZMQ_POLLPRI
180           For 0MQ sockets this flag has no effect on the zmq_poller_add and
181           zmq_poller_modify functions, and is never set in the events member
182           of the zmq_poller_event_t structure. For standard sockets this
183           means there is urgent data to read. Refer to the POLLPRI flag for
184           more informations. For a file descriptor, refer to your OS
185           documentation: as an example, GPIO interrupts are signaled through
186           a POLLPRI event. This flag has no effect on Windows.
187
188           Note
189           The zmq_poller*_ functions may be implemented or emulated using
190           operating system interfaces other than poll(), and as such may be
191           subject to the limits of those interfaces in ways not defined in
192           this documentation.
193

THREAD SAFETY

195       Like most other 0MQ objects, a poller is not thread-safe. All
196       operations must be called from the same thread. Otherwise, behaviour is
197       undefined.
198
199       In addition to that, if you want to add a socket to multiple existing
200       poller instances, the socket itself needs to be thread-safe (Server,
201       Client, ...). Otherwise, behaviour is undefined.
202

RETURN VALUE

204       zmq_poller_new returns a valid pointer to a poller, or NULL in case of
205       a failure.
206
207       All functions that return an int, return -1 in case of a failure. In
208       that case, zmq_errno() can be used to query the type of the error as
209       described below.
210
211       zmq_poller_wait_all returns the number of events signalled and returned
212       in the events array. It never returns 0.
213
214       All other functions return 0 in case of a successful execution.
215

ERRORS

217       On zmq_poller_new: ENOMEM:: A new poller could not be allocated
218       successfully.
219
220       On zmq_poller_destroy: EFAULT:: poller_p did not point to a valid
221       poller. Note that passing an invalid pointer (e.g. pointer to
222       deallocated memory) may cause undefined behaviour (e.g. an access
223       violation).
224
225       On zmq_poller_size: EFAULT:: poller did not point to a valid poller.
226       Note that passing an invalid pointer (e.g. pointer to deallocated
227       memory) may cause undefined behaviour (e.g. an access violation).
228
229       On zmq_poller_add, zmq_poller_modify and zmq_poller_remove: EFAULT::
230       poller did not point to a valid poller. Note that passing an invalid
231       pointer (e.g. pointer to deallocated memory) may cause undefined
232       behaviour (e.g. an access violation). ENOTSOCK:: socket did not point
233       to a valid socket. Note that passing an invalid pointer (e.g. pointer
234       to deallocated memory) may cause undefined behaviour (e.g. an access
235       violation).
236
237       On zmq_poller_add: EMFILE:: TODO
238
239       On zmq_poller_add or zmq_poller_add_fd: ENOMEM:: Necessary resources
240       could not be allocated. EINVAL:: socket resp. fd was already registered
241       with the poller.
242
243       On zmq_poller_modify, zmq_poller_modify_fd, zmq_poller_remove or
244       zmq_poller_remove_fd: EINVAL:: socket resp. fd was not registered with
245       the poller.
246
247       On zmq_poller_add_fd, zmq_poller_modify_fd and zmq_poller_remove_fd:
248       EBADF*: The fd specified was the retired fd.
249
250       On zmq_poller_wait and zmq_poller_wait_all: ENOMEM:: Necessary
251       resources could not be allocated. ETERM:: At least one of the
252       registered objects is a socket whose associated 0MQ context was
253       terminated. EFAULT:: The provided events was NULL, or poller did not
254       point to a valid poller, or there are no registered objects or all
255       event subscriptions are disabled and timeout was negative. EINTR:: The
256       operation was interrupted by delivery of a signal before any events
257       were available. EAGAIN:: No registered event was signalled before the
258       timeout was reached.
259
260       On zmq_poller_fd: EINVAL:: The poller has no associated file
261       descriptor. EFAULT:: The provided poller did not point to a valid
262       poller.
263

EXAMPLE

265       Polling indefinitely for input events on both a 0MQ socket and a
266       standard socket..
267
268           void *poller = zmq_poller_new ();
269
270           zmq_poller_event_t events [2];
271           /* First item refers to 0MQ socket 'socket' */
272           zmq_poller_add (poller, socket, NULL, ZMQ_POLLIN);
273           /* Second item refers to standard socket 'fd' */
274           zmq_poller_add_fd (poller, fd, NULL, ZMQ_POLLIN);
275           /* Poll for events indefinitely */
276           int rc = zmq_poller_wait_all (poller, events, 2, -1);
277           assert (rc >= 0);
278           /* Returned events will be stored in 'events' */
279           zmq_poller_destroy (poller);
280
281

SEE ALSO

283       zmq_socket(3) zmq_send(3) zmq_recv(3) zmq(7)
284

AUTHORS

286       This page was written by the 0MQ community. To make a change please
287       read the 0MQ Contribution Policy at
288       http://www.zeromq.org/docs:contributing.
289
290
291
2920MQ 4.3.4                         07/22/2023                     ZMQ_POLLER(3)
Impressum