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