1ZPOLLER(3) CZMQ Manual ZPOLLER(3)
2
6 zpoller - 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 // Check we can poll an FD
116 rc = zsock_connect (bowl, "tcp://127.0.0.1:%d", port_nbr);
117 assert (rc != -1);
118 SOCKET fd = zsock_fd (bowl);
119 rc = zpoller_add (poller, (void *) &fd);
120 assert (rc != -1);
121 zstr_send (vent, "Hello again, world");
122 assert (zpoller_wait (poller, 500) == &fd);
123 // Check zpoller_set_nonstop ()
125 zsys_interrupted = 1;
126 zpoller_wait (poller, 0);
127 assert (zpoller_terminated (poller));
128 zpoller_set_nonstop (poller, true);
129 zpoller_wait (poller, 0);
130 assert (!zpoller_terminated (poller));
131 zsys_interrupted = 0;
132 zpoller_destroy (&poller);
134 zsock_destroy (&vent);
135 zsock_destroy (&sink);
136 zsock_destroy (&bowl);
137 zsock_destroy (&dish);
138 #ifdef ZMQ_SERVER
140 // Check thread safe sockets
141 zpoller_destroy (&poller);
142 zsock_t *client = zsock_new (ZMQ_CLIENT);
143 assert (client);
144 zsock_t *server = zsock_new (ZMQ_SERVER);
145 assert (server);
146 poller = zpoller_new (client, server, NULL);
147 assert (poller);
148 port_nbr = zsock_bind (server, "tcp://127.0.0.1:*");
149 assert (port_nbr != -1);
150 rc = zsock_connect (client, "tcp://127.0.0.1:%d", port_nbr);
151 assert (rc != -1);
152 zstr_send (client, "Hello, World");
154 // We expect a message only on the server
156 which = (zsock_t *) zpoller_wait (poller, -1);
157 assert (which == server);
158 assert (zpoller_expired (poller) == false);
159 assert (zpoller_terminated (poller) == false);
160 message = zstr_recv (which);
161 assert (streq (message, "Hello, World"));
162 zstr_free (&message);
163 zpoller_destroy (&poller);
165 zsock_destroy (&client);
166 zsock_destroy (&server);
167 #endif
168
171 The czmq manual was written by the authors in the AUTHORS file.
172
174 Main web site:
175 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
177
179 Copyright (c) the Contributors as noted in the AUTHORS file. This file
180 is part of CZMQ, the high-level C binding for 0MQ:
181 http://czmq.zeromq.org. This Source Code Form is subject to the terms
182 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
183 distributed with this file, You can obtain one at
184 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
185 distribution.
186
188 1. zeromq-dev@lists.zeromq.org
189 mailto:zeromq-dev@lists.zeromq.org
190CZMQ 4.0.2 12/31/2016 ZPOLLER(3)