1ZPOLLER(3) CZMQ Manual ZPOLLER(3)
2
6 zpoller - Class for trivial socket poller class
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // Create new poller, specifying zero or more readers. The list of
12 // readers ends in a NULL. Each reader can be a zsock_t instance, a
13 // zactor_t instance, a libzmq socket (void *), or a file handle.
14 CZMQ_EXPORT zpoller_t *
15 zpoller_new (void *reader, ...);
16 // Destroy a poller
18 CZMQ_EXPORT void
19 zpoller_destroy (zpoller_t **self_p);
20 // Add a reader to be polled. Returns 0 if OK, -1 on failure. The reader may
22 // be a libzmq void * socket, a zsock_t instance, a zactor_t instance or a
23 // file handle.
24 CZMQ_EXPORT int
25 zpoller_add (zpoller_t *self, void *reader);
26 // Remove a reader from the poller; returns 0 if OK, -1 on failure. The reader
28 // must have been passed during construction, or in an zpoller_add () call.
29 CZMQ_EXPORT int
30 zpoller_remove (zpoller_t *self, void *reader);
31 // By default the poller stops if the process receives a SIGINT or SIGTERM
33 // signal. This makes it impossible to shut-down message based architectures
34 // like zactors. This method lets you switch off break handling. The default
35 // nonstop setting is off (false).
36 CZMQ_EXPORT void
37 zpoller_set_nonstop (zpoller_t *self, bool nonstop);
38 // Poll the registered readers for I/O, return first reader that has input.
40 // The reader will be a libzmq void * socket, a zsock_t, a zactor_t
41 // instance or a file handle as specified in zpoller_new/zpoller_add. The
42 // timeout should be zero or greater, or -1 to wait indefinitely. Socket
43 // priority is defined by their order in the poll list. If you need a
44 // balanced poll, use the low level zmq_poll method directly. If the poll
45 // call was interrupted (SIGINT), or the ZMQ context was destroyed, or the
46 // timeout expired, returns NULL. You can test the actual exit condition by
47 // calling zpoller_expired () and zpoller_terminated (). The timeout is in
48 // msec.
49 CZMQ_EXPORT void *
50 zpoller_wait (zpoller_t *self, int timeout);
51 // Return true if the last zpoller_wait () call ended because the timeout
53 // expired, without any error.
54 CZMQ_EXPORT bool
55 zpoller_expired (zpoller_t *self);
56 // Return true if the last zpoller_wait () call ended because the process
58 // was interrupted, or the parent context was destroyed.
59 CZMQ_EXPORT bool
60 zpoller_terminated (zpoller_t *self);
61 // Self test of this class.
63 CZMQ_EXPORT void
64 zpoller_test (bool verbose);
65 Please add '@interface' section in './../src/zpoller.c'.
67
69 The zpoller class provides a minimalist interface to ZeroMQ’s zmq_poll
70 API, for the very common case of reading from a number of sockets. It
71 does not provide polling for output, nor polling on file handles. If
72 you need either of these, use the zmq_poll API directly.
73 The class implements the poller using the zmq_poller API if that
75 exists, else does the work itself.
76
78 From zpoller_test method.
79 // Create a few sockets
81 zsock_t *vent = zsock_new (ZMQ_PUSH);
82 assert (vent);
83 int port_nbr = zsock_bind (vent, "tcp://127.0.0.1:*");
84 assert (port_nbr != -1);
85 zsock_t *sink = zsock_new (ZMQ_PULL);
86 assert (sink);
87 int rc = zsock_connect (sink, "tcp://127.0.0.1:%d", port_nbr);
88 assert (rc != -1);
89 zsock_t *bowl = zsock_new (ZMQ_PULL);
90 assert (bowl);
91 zsock_t *dish = zsock_new (ZMQ_PULL);
92 assert (dish);
93 // Set up poller
95 zpoller_t *poller = zpoller_new (bowl, dish, NULL);
96 assert (poller);
97 // Add a reader to the existing poller
99 rc = zpoller_add (poller, sink);
100 assert (rc == 0);
101 zstr_send (vent, "Hello, World");
103 // We expect a message only on the sink
105 zsock_t *which = (zsock_t *) zpoller_wait (poller, -1);
106 assert (which == sink);
107 assert (zpoller_expired (poller) == false);
108 assert (zpoller_terminated (poller) == false);
109 char *message = zstr_recv (which);
110 assert (streq (message, "Hello, World"));
111 zstr_free (&message);
112 // Stop polling reader
114 rc = zpoller_remove (poller, sink);
115 assert (rc == 0);
116 // Removing a non-existent reader shall fail
118 rc = zpoller_remove (poller, sink);
119 assert (rc == -1);
120 assert (errno == EINVAL);
121 // Check we can poll an FD
123 rc = zsock_connect (bowl, "tcp://127.0.0.1:%d", port_nbr);
124 assert (rc != -1);
125 SOCKET fd = zsock_fd (bowl);
126 rc = zpoller_add (poller, (void *) &fd);
127 assert (rc != -1);
128 zstr_send (vent, "Hello again, world");
129 assert (zpoller_wait (poller, 500) == &fd);
130 // Check zpoller_set_nonstop ()
132 zsys_interrupted = 1;
133 zpoller_wait (poller, 0);
134 assert (zpoller_terminated (poller));
135 zpoller_set_nonstop (poller, true);
136 zpoller_wait (poller, 0);
137 assert (!zpoller_terminated (poller));
138 zsys_interrupted = 0;
139 zpoller_destroy (&poller);
141 zsock_destroy (&vent);
142 zsock_destroy (&sink);
143 zsock_destroy (&bowl);
144 zsock_destroy (&dish);
145 #ifdef ZMQ_SERVER
147 // Check thread safe sockets
148 zpoller_destroy (&poller);
149 zsock_t *client = zsock_new (ZMQ_CLIENT);
150 assert (client);
151 zsock_t *server = zsock_new (ZMQ_SERVER);
152 assert (server);
153 poller = zpoller_new (client, server, NULL);
154 assert (poller);
155 port_nbr = zsock_bind (server, "tcp://127.0.0.1:*");
156 assert (port_nbr != -1);
157 rc = zsock_connect (client, "tcp://127.0.0.1:%d", port_nbr);
158 assert (rc != -1);
159 zstr_send (client, "Hello, World");
161 // We expect a message only on the server
163 which = (zsock_t *) zpoller_wait (poller, -1);
164 assert (which == server);
165 assert (zpoller_expired (poller) == false);
166 assert (zpoller_terminated (poller) == false);
167 message = zstr_recv (which);
168 assert (streq (message, "Hello, World"));
169 zstr_free (&message);
170 zpoller_destroy (&poller);
172 zsock_destroy (&client);
173 zsock_destroy (&server);
174 #endif
175 #if defined (__WINDOWS__)
177 zsys_shutdown();
178 #endif
179
182 The czmq manual was written by the authors in the AUTHORS file.
183
185 Main web site:
186 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
188
190 Copyright (c) the Contributors as noted in the AUTHORS file. This file
191 is part of CZMQ, the high-level C binding for 0MQ:
192 http://czmq.zeromq.org. This Source Code Form is subject to the terms
193 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
194 distributed with this file, You can obtain one at
195 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
196 distribution.
197
199 1. zeromq-dev@lists.zeromq.org
200 mailto:zeromq-dev@lists.zeromq.org
201CZMQ 4.2.1 01/20/2022 ZPOLLER(3)