zpoller(3)

zpoller(3)

CZMQ Manual - CZMQ/3.0.1

Name

zpoller - trivial socket poller class

Synopsis

//  Create new poller; the reader can be a libzmq socket (void *), a zsock_t
//  instance, or a zactor_t instance.
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, or a zactor_t instance.
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 may be a libzmq void * socket, a zsock_t instance, or a zactor_t
//  instance.
CZMQ_EXPORT int
    zpoller_remove (zpoller_t *self, void *reader);

//  Poll the registered readers for I/O, return first reader that has input.
//  The reader will be a libzmq void * socket, or a zsock_t or zactor_t
//  instance as specified in zpoller_new/zpoller_add. The order that
//  sockets are defined in the poll list affects their priority. 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);

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.

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);

// Check we can poll an FD
rc = zsock_connect (bowl, "tcp://127.0.0.1:%d", port_nbr);
assert (rc != -1);
int 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);

// Destroy poller and sockets
zpoller_destroy (&poller);

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

See also

czmq(7)

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for ØMQ: 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/.