Provided by: libczmq-dev_4.2.1-1_amd64 bug

NAME

       zpoller - Class for trivial socket poller class

SYNOPSIS

       //  This is a stable class, and may not change except for emergencies. It
       //  is provided in stable builds.
       //  Create new poller, specifying zero or more readers. The list of
       //  readers ends in a NULL. Each reader can be a zsock_t instance, a
       //  zactor_t instance, a libzmq socket (void *), or a file handle.
       CZMQ_EXPORT zpoller_t *
           zpoller_new (void *reader, ...);

       //  Destroy a poller
       CZMQ_EXPORT void
           zpoller_destroy (zpoller_t **self_p);

       //  Add a reader to be polled. Returns 0 if OK, -1 on failure. The reader may
       //  be a libzmq void * socket, a zsock_t instance, a zactor_t instance or a
       //  file handle.
       CZMQ_EXPORT int
           zpoller_add (zpoller_t *self, void *reader);

       //  Remove a reader from the poller; returns 0 if OK, -1 on failure. The reader
       //  must have been passed during construction, or in an zpoller_add () call.
       CZMQ_EXPORT int
           zpoller_remove (zpoller_t *self, void *reader);

       //  By default the poller stops if the process receives a SIGINT or SIGTERM
       //  signal. This makes it impossible to shut-down message based architectures
       //  like zactors. This method lets you switch off break handling. The default
       //  nonstop setting is off (false).
       CZMQ_EXPORT void
           zpoller_set_nonstop (zpoller_t *self, bool nonstop);

       //  Poll the registered readers for I/O, return first reader that has input.
       //  The reader will be a libzmq void * socket, a zsock_t, a zactor_t
       //  instance or a file handle as specified in zpoller_new/zpoller_add. The
       //  timeout should be zero or greater, or -1 to wait indefinitely. Socket
       //  priority is defined by their order in the poll list. If you need a
       //  balanced poll, use the low level zmq_poll method directly. If the poll
       //  call was interrupted (SIGINT), or the ZMQ context was destroyed, or the
       //  timeout expired, returns NULL. You can test the actual exit condition by
       //  calling zpoller_expired () and zpoller_terminated (). The timeout is in
       //  msec.
       CZMQ_EXPORT void *
           zpoller_wait (zpoller_t *self, int timeout);

       //  Return true if the last zpoller_wait () call ended because the timeout
       //  expired, without any error.
       CZMQ_EXPORT bool
           zpoller_expired (zpoller_t *self);

       //  Return true if the last zpoller_wait () call ended because the process
       //  was interrupted, or the parent context was destroyed.
       CZMQ_EXPORT bool
           zpoller_terminated (zpoller_t *self);

       //  Self test of this class.
       CZMQ_EXPORT void
           zpoller_test (bool verbose);

       Please add '@interface' section in './../src/zpoller.c'.

DESCRIPTION

       The zpoller class provides a minimalist interface to ZeroMQ’s zmq_poll API, for the very
       common case of reading from a number of sockets. It does not provide polling for output,
       nor polling on file handles. If you need either of these, use the zmq_poll API directly.

       The class implements the poller using the zmq_poller API if that exists, else does the
       work itself.

EXAMPLE

       From zpoller_test method.

           //  Create a few sockets
           zsock_t *vent = zsock_new (ZMQ_PUSH);
           assert (vent);
           int port_nbr = zsock_bind (vent, "tcp://127.0.0.1:*");
           assert (port_nbr != -1);
           zsock_t *sink = zsock_new (ZMQ_PULL);
           assert (sink);
           int rc = zsock_connect (sink, "tcp://127.0.0.1:%d", port_nbr);
           assert (rc != -1);
           zsock_t *bowl = zsock_new (ZMQ_PULL);
           assert (bowl);
           zsock_t *dish = zsock_new (ZMQ_PULL);
           assert (dish);

           //  Set up poller
           zpoller_t *poller = zpoller_new (bowl, dish, NULL);
           assert (poller);

           // Add a reader to the existing poller
           rc = zpoller_add (poller, sink);
           assert (rc == 0);

           zstr_send (vent, "Hello, World");

           //  We expect a message only on the sink
           zsock_t *which = (zsock_t *) zpoller_wait (poller, -1);
           assert (which == sink);
           assert (zpoller_expired (poller) == false);
           assert (zpoller_terminated (poller) == false);
           char *message = zstr_recv (which);
           assert (streq (message, "Hello, World"));
           zstr_free (&message);

           //  Stop polling reader
           rc = zpoller_remove (poller, sink);
           assert (rc == 0);

           // Removing a non-existent reader shall fail
           rc = zpoller_remove (poller, sink);
           assert (rc == -1);
           assert (errno == EINVAL);

           //  Check we can poll an FD
           rc = zsock_connect (bowl, "tcp://127.0.0.1:%d", port_nbr);
           assert (rc != -1);
           SOCKET fd = zsock_fd (bowl);
           rc = zpoller_add (poller, (void *) &fd);
           assert (rc != -1);
           zstr_send (vent, "Hello again, world");
           assert (zpoller_wait (poller, 500) == &fd);

           // Check zpoller_set_nonstop ()
           zsys_interrupted = 1;
           zpoller_wait (poller, 0);
           assert (zpoller_terminated (poller));
           zpoller_set_nonstop (poller, true);
           zpoller_wait (poller, 0);
           assert (!zpoller_terminated (poller));
           zsys_interrupted = 0;

           zpoller_destroy (&poller);
           zsock_destroy (&vent);
           zsock_destroy (&sink);
           zsock_destroy (&bowl);
           zsock_destroy (&dish);

           #ifdef ZMQ_SERVER
           //  Check thread safe sockets
           zpoller_destroy (&poller);
           zsock_t *client = zsock_new (ZMQ_CLIENT);
           assert (client);
           zsock_t *server = zsock_new (ZMQ_SERVER);
           assert (server);
           poller = zpoller_new (client, server, NULL);
           assert (poller);
           port_nbr = zsock_bind (server, "tcp://127.0.0.1:*");
           assert (port_nbr != -1);
           rc = zsock_connect (client, "tcp://127.0.0.1:%d", port_nbr);
           assert (rc != -1);

           zstr_send (client, "Hello, World");

           //  We expect a message only on the server
           which = (zsock_t *) zpoller_wait (poller, -1);
           assert (which == server);
           assert (zpoller_expired (poller) == false);
           assert (zpoller_terminated (poller) == false);
           message = zstr_recv (which);
           assert (streq (message, "Hello, World"));
           zstr_free (&message);

           zpoller_destroy (&poller);
           zsock_destroy (&client);
           zsock_destroy (&server);
           #endif

           #if defined (__WINDOWS__)
           zsys_shutdown();
           #endif

AUTHORS

       The czmq manual was written by the authors in the AUTHORS file.

RESOURCES

       Main web site:

       Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT

       Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ,
       the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject
       to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
       distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE
       included with the czmq distribution.

NOTES

        1. zeromq-dev@lists.zeromq.org
           mailto:zeromq-dev@lists.zeromq.org