zloop(3)

zloop(3)

CZMQ Manual - CZMQ/3.0.1

Name

zloop - event-driven reactor

Synopsis

//  Callback function for reactor socket activity
typedef int (zloop_reader_fn) (zloop_t *loop, zsock_t *reader, void *arg);

//  Callback function for reactor events (low-level)
typedef int (zloop_fn) (zloop_t *loop, zmq_pollitem_t *item, void *arg);

// Callback for reactor timer events
typedef int (zloop_timer_fn) (zloop_t *loop, int timer_id, void *arg);

//  Create a new zloop reactor
CZMQ_EXPORT zloop_t *
    zloop_new (void);

//  Destroy a reactor
CZMQ_EXPORT void
    zloop_destroy (zloop_t **self_p);

//  Register socket reader with the reactor. When the reader has messages,
//  the reactor will call the handler, passing the arg. Returns 0 if OK, -1
//  if there was an error. If you register the same socket more than once,
//  each instance will invoke its corresponding handler.
CZMQ_EXPORT int
    zloop_reader (zloop_t *self, zsock_t *sock, zloop_reader_fn handler, void *arg);

//  Cancel a socket reader from the reactor. If multiple readers exist for
//  same socket, cancels ALL of them.
CZMQ_EXPORT void
    zloop_reader_end (zloop_t *self, zsock_t *sock);

//  Configure a registered reader to ignore errors. If you do not set this,
//  then readers that have errors are removed from the reactor silently.
CZMQ_EXPORT void
    zloop_reader_set_tolerant (zloop_t *self, zsock_t *sock);

//  Register low-level libzmq pollitem with the reactor. When the pollitem
//  is ready, will call the handler, passing the arg. Returns 0 if OK, -1
//  if there was an error. If you register the pollitem more than once, each
//  instance will invoke its corresponding handler. A pollitem with
//  socket=NULL and fd=0 means 'poll on FD zero'.
CZMQ_EXPORT int
    zloop_poller (zloop_t *self, zmq_pollitem_t *item, zloop_fn handler, void *arg);

//  Cancel a pollitem from the reactor, specified by socket or FD. If both
//  are specified, uses only socket. If multiple poll items exist for same
//  socket/FD, cancels ALL of them.
CZMQ_EXPORT void
    zloop_poller_end (zloop_t *self, zmq_pollitem_t *item);

//  Configure a registered poller to ignore errors. If you do not set this,
//  then poller that have errors are removed from the reactor silently.
CZMQ_EXPORT void
    zloop_poller_set_tolerant (zloop_t *self, zmq_pollitem_t *item);

//  Register a timer that expires after some delay and repeats some number of
//  times. At each expiry, will call the handler, passing the arg. To run a
//  timer forever, use 0 times. Returns a timer_id that is used to cancel the
//  timer in the future. Returns -1 if there was an error.
CZMQ_EXPORT int
    zloop_timer (zloop_t *self, size_t delay, size_t times, zloop_timer_fn handler, void *arg);

//  Cancel a specific timer identified by a specific timer_id (as returned by
//  zloop_timer).
CZMQ_EXPORT int
    zloop_timer_end (zloop_t *self, int timer_id);

//  Set verbose tracing of reactor on/off
CZMQ_EXPORT void
    zloop_set_verbose (zloop_t *self, bool verbose);

//  Start the reactor. Takes control of the thread and returns when the ØMQ
//  context is terminated or the process is interrupted, or any event handler
//  returns -1. Event handlers may register new sockets and timers, and
//  cancel sockets. Returns 0 if interrupted, -1 if cancelled by a handler.
CZMQ_EXPORT int
    zloop_start (zloop_t *self);

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

Description

The zloop class provides an event-driven reactor pattern. The reactor handles zmq_pollitem_t items (pollers or writers, sockets or fds), and once-off or repeated timers. Its resolution is 1 msec. It uses a tickless timer to reduce CPU interrupts in inactive processes.

Example

From zloop_test method

//  Create two PAIR sockets and connect over inproc
zsock_t *output = zsock_new (ZMQ_PAIR);
assert (output);
zsock_bind (output, "inproc://zloop.test");

zsock_t *input = zsock_new (ZMQ_PAIR);
assert (input);
zsock_connect (input, "inproc://zloop.test");

zloop_t *loop = zloop_new ();
assert (loop);
zloop_set_verbose (loop, verbose);

//  Create a timer that will be cancelled
int timer_id = zloop_timer (loop, 1000, 1, s_timer_event, NULL);
zloop_timer (loop, 5, 1, s_cancel_timer_event, &timer_id);

//  After 20 msecs, send a ping message to output3
zloop_timer (loop, 20, 1, s_timer_event, output);

//  When we get the ping message, end the reactor
rc = zloop_reader (loop, input, s_socket_event, NULL);
assert (rc == 0);
zloop_reader_set_tolerant (loop, input);
zloop_start (loop);

zloop_destroy (&loop);
assert (loop == NULL);

zsock_destroy (&input); 
zsock_destroy (&output);

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/.