ØMQ Manual - ØMQ/3.3.0


zmq_ctx_set_monitor - register a monitoring callback


int zmq_ctx_set_monitor (void *context, zmq_monitor_fn *monitor);


The zmq_ctx_set_monitor() function shall register a callback function specified by the monitor argument. This is an event sink for changes in per socket connection and mailbox (work in progress) states.

The zmq_ctx_set_monitor() callback function is expected to have this

typedef void (zmq_monitor_fn) (void *s, int event, zmq_event_data_t *data);

typedef void (zmq_monitor_fn) (void *s, int event, zmq_event_data_t *data);

zmq_ctx_set_monitor() is intended for monitoring infrastructure / operations concerns only - NOT BUSINESS LOGIC. An event is a representation of something that happened - you cannot change the past, but only react to them. The implementation is also only concerned with a single session. No state of peers, other sessions etc. are tracked - this will only pollute internals and is the responsibility of application authors to either implement or correlate in another datastore. Monitor events are exceptional conditions and are thus not directly in the messaging critical path. However, still be careful with what you're doing in the callback function as excess time spent in the handler will block the socket's application thread.

Only tcp and ipc specific transport events are supported in this initial implementation.

Supported events are:

ZMQ_EVENT_CONNECTED: connection established

The ZMQ_EVENT_CONNECTED event triggers when a connection has been established to a remote peer. This can happen either synchronous or asynchronous.

Callback metadata:

data.connected.addr // peer address data.connected.fd // socket descriptor

ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it's being polled

The ZMQ_EVENT_CONNECT_DELAYED event triggers when an immediate connection attempt is delayed and it's completion's being polled for.

Callback metadata:

data.connect_delayed.addr // peer address data.connect_delayed.err // errno

ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt

The ZMQ_EVENT_CONNECT_RETRIED event triggers when a connection attempt is being handled by reconnect timer. The reconnect interval's recomputed for each attempt.

Callback metadata:

data.connect_retried.addr // peer address data.connect_retried.interval // computed reconnect interval

ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections

The ZMQ_EVENT_LISTENING event triggers when a socket's successfully bound to a an interface.

Callback metadata:

data.listening.addr //  listen address data.listening.fd // socket descriptor

ZMQ_EVENT_BIND_FAILED: socket could not bind to an address

The ZMQ_EVENT_BIND_FAILED event triggers when a socket could not bind to a given interface.

Callback metadata:

data.bind_failed.addr // listen address data.bind_failed.err // errno

ZMQ_EVENT_ACCEPTED: connection accepted to bound interface

The ZMQ_EVENT_ACCEPTED event triggers when a connection from a remote peer has been established with a socket's listen address.

Callback metadata:

data.accepted.addr // listen address data.accepted.fd // socket descriptor

ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection

The ZMQ_EVENT_ACCEPT_FAILED event triggers when a connection attempt to a socket's bound address fails.

Callback metadata:

data.accept_failed.addr // listen address data.accept_failed.err // errno

ZMQ_EVENT_CLOSED: connection closed

The ZMQ_EVENT_CLOSED event triggers when a connection's underlying descriptor has been closed.

Callback metadata:

data.closed.addr // address data.closed.fd // socket descriptor

ZMQ_EVENT_CLOSE_FAILED: connection couldn't be closed

The ZMQ_EVENT_CLOSE_FAILED event triggers when a descriptor could not be released back to the OS.

Callback metadata:

data.close_failed.addr // address data.close_failed.err // errno


The ZMQ_EVENT_DISCONNECTED event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session.

Callback metadata:

data.disconnected.addr // address data.disconnected.fd // socket descriptor

Return value

The zmq_ctx_set_monitor() function returns a value of 0 or greater if successful. Otherwise it returns -1 and sets errno to one of the values defined below.


The requested callback function monitor is invalid.


Observing a pub socket's connection state

void socket_monitor (void *s, int event_, zmq_event_data_t *data_)
    switch (event_) {
        printf ("Socket bound to %s, socket descriptor is %d\n",
                 data.listening.addr, data.listening.fd);
        printf ("Accepted connection to %s, socket descriptor is %d\n",
                data.accepted.addr, data.accepted.fd);

void *context = zmq_ctx_new ();
int rc = zmq_ctx_set_monitor (context, socket_monitor);
assert (rc == 0);
void *pub = zmq_socket (context, ZMQ_PUB);
assert (pub);
void *sub = zmq_socket (context, ZMQ_SUB);
assert (pub);
rc = zmq_bind (pub, "tcp://");
assert (rc == 0);
rc = zmq_connect (sub, "tcp://");
assert (rc == 0);

// Allow a window for socket events as connect can be async
zmq_sleep (1);

rc = zmq_close (pub);
assert (rc == 0);
rc = zmq_close (sub);
assert (rc == 0);
 zmq_term (context);

See also



This ØMQ manual page was written by Lourens Naudé <moc.gnissimdohtem|sneruol#moc.gnissimdohtem|sneruol>