zmq_ctx_set_monitor(3)
zmq_ctx_set_monitor(3)
ØMQ Manual - ØMQ/3.2.0
Name
zmq_ctx_set_monitor - register a monitoring callback
Synopsis
int zmq_ctx_set_monitor (void *context, zmq_monitor_fn *monitor);
Description
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 prototype:
typedef void (zmq_monitor_fn) (void *s, int event, zmq_event_data_t *data);</screen>
</para></formalpara>
The callback is global (per context), with the socket that triggered the event
passed to the handler as well. Each event also populates a //zmq_event_data_t//
union with additional metadata which can be used for correlation.
<caution>//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.</caution>
Only tcp and ipc specific transport events are supported in this initial
implementation.
Supported events are:
<refsect2 id="_zmq_event_connected_connection_established">
<title>ZMQ_EVENT_CONNECTED: connection established</title>
The //ZMQ_EVENT_CONNECTED// event triggers when a connection has been established
to a remote peer. This can happen either synchronous or asynchronous.
<formalpara><title>Callback metadata:</title><para>
[[code]]
data.connected.addr // peer address data.connected.fd // socket descriptor
[[/code]]
+++ 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:**
[[code]]
data.connect_delayed.addr // peer address data.connect_delayed.err // errno
[[/code]]
+++ 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:**
[[code]]
data.connect_retried.addr // peer address data.connect_retried.interval // computed reconnect interval
[[/code]]
+++ 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:**
[[code]]
data.listening.addr // listen address data.listening.fd // socket descriptor
[[/code]]
+++ 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:**
[[code]]
data.bind_failed.addr // listen address data.bind_failed.err // errno
[[/code]]
+++ 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:**
[[code]]
data.accepted.addr // listen address data.accepted.fd // socket descriptor
[[/code]]
+++ 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:**
[[code]]
data.accept_failed.addr // listen address data.accept_failed.err // errno
[[/code]]
+++ ZMQ_EVENT_CLOSED: connection closed
The //ZMQ_EVENT_CLOSED// event triggers when a connection's underlying descriptor has been closed.
**Callback metadata:**
[[code]]
data.closed.addr // address data.closed.fd // socket descriptor
[[/code]]
+++ 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:**
[[code]]
data.close_failed.addr // address data.close_failed.err // errno
[[/code]]
+++ ZMQ_EVENT_DISCONNECTED: broken session
The //ZMQ_EVENT_DISCONNECTED// event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session.
**Callback metadata:**
[[code]]
data.disconnected.addr // address data.disconnected.fd // socket descriptor
[[/code]]
++ 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.
++ Errors
: **EINVAL** : The requested callback function //monitor// is invalid.
++ Example
**Observing a //pub// socket's connection state**
[[code]]
void socket_monitor (void *s, int event_, zmq_event_data_t *data_)
{
switch (event_) {
case ZMQ_EVENT_LISTENING:
printf ("Socket bound to %s, socket descriptor is %d\n",
data.listening.addr, data.listening.fd);
break;
case ZMQ_EVENT_ACCEPTED:
printf ("Accepted connection to %s, socket descriptor is %d\n",
data.accepted.addr, data.accepted.fd);
break;
}
}
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://127.0.0.1:5560");
assert (rc == 0);
rc = zmq_connect (sub, "tcp://127.0.0.1:5560");
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
Authors
This ØMQ manual page was written by Lourens Naudé <moc.gnissimdohtem|sneruol#moc.gnissimdohtem|sneruol>