Documentation for zmq_monitor

doc/Makefile.am

@@ -1,6 +1,6 @@
 MAN3 = zmq_bind.3 zmq_close.3 zmq_connect.3 zmq_device.3 \
     zmq_ctx_new.3 zmq_ctx_destroy.3 zmq_ctx_get.3 zmq_ctx_set.3 \
-    zmq_init.3 zmq_term.3 \
+    zmq_init.3 zmq_term.3 zmq_monitor.3\
     zmq_msg_close.3 zmq_msg_copy.3 zmq_msg_data.3 zmq_msg_init.3 \
     zmq_msg_init_data.3 zmq_msg_init_size.3 zmq_msg_move.3 zmq_msg_size.3 \
     zmq_msg_send.3 zmq_msg_recv.3 \

doc/zmq.txt

@@ -44,6 +44,9 @@ Work with context properties::
 Destroy a 0MQ context::
     linkzmq:zmq_ctx_destroy[3]
 
+Monitor a 0MQ context::
+    linkzmq:zmq_monitor[3]
+
 These deprecated functions let you create and destroy 'contexts':
 
 Initialise 0MQ context::

doc/zmq_getsockopt.txt

@@ -455,17 +455,6 @@ Option value unit:: -1,>0
 Default value:: -1 (leave to OS default)
 Applicable socket types:: all, when using TCP transports.
 
-ZMQ_MONITOR: Registers a callback for socket state changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Registers a callback function / event sink for changes in underlying socket state.
-The default value of `NULL` means no monitor callback function.
-
-[horizontal]
-Option value type:: zmq_monitor
-Option value unit:: N/A
-Default value:: no callback function
-Applicable socket types:: all
-
 RETURN VALUE
 ------------
 The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it

doc/zmq_monitor.txt

@@ -0,0 +1,221 @@
+zmq_monitor(3)
+==============
+
+
+NAME
+----
+
+zmq_monitor - register a monitoring callback
+
+
+SYNOPSIS
+--------
+*int zmq_monitor (void '*context', zmq_monitor_fn '*monitor');*
+
+
+DESCRIPTION
+-----------
+The _zmq_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_monitor()_ callback function is expected to have this prototype:
+----
+typedef void (zmq_monitor_fn) (void *s, int event, zmq_event_data_t *data);
+----
+
+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_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
+----
+
+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:
+----
+data.disconnected.addr // address
+data.disconnected.fd // socket descriptor
+----
+
+RETURN VALUE
+------------
+The _zmq_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 
+----
+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_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
+--------
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This 0MQ manual page was written by Lourens Naudé <lourens@methodmissing.com>

doc/zmq_setsockopt.txt

@@ -431,46 +431,6 @@ Default value:: no filters (allow from all)
 Applicable socket types:: all listening sockets, when using TCP transports.
 
 
-ZMQ_MONITOR: Registers a callback for socket state changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Registers a callback function / event sink for changes in underlying socket state.
-Expected signature of function member of zmq_monitor union is `void (*function)(void *s, int event, zmq_event_data_t *data);`
-To remove the callback function call `zmq_setsockopt(socket, ZMQ_MONITOR, NULL, 0)`
-The default value of `NULL` means no monitor callback function.
-Supported events are :
-
-* 'ZMQ_EVENT_CONNECTED' - connection established
-* 'ZMQ_EVENT_CONNECT_DELAYED' - connection could not be established synchronously, it's being polled
-* 'ZMQ_EVENT_CONNECT_RETRIED' - asynchronous connect / reconnection attempt
-
-* 'ZMQ_EVENT_LISTENING' - socket bound to an address, ready to accept connections
-* 'ZMQ_EVENT_BIND_FAILED' - socket couldn't bind to an address
-
-* 'ZMQ_EVENT_ACCEPTED' - connection accepted to bound interface
-* 'ZMQ_EVENT_ACCEPT_FAILED' - could not accept client connection
-
-* 'ZMQ_EVENT_CLOSED' - connection closed
-* 'ZMQ_EVENT_CLOSE_FAILED' - connection couldn't be closed
-* 'ZMQ_EVENT_DISCONNECTED' - broken session
-
-See `zmq_event_data_t` and `ZMQ_EVENT_*` constants in zmq.h for event specific data (third argument to callback).
-
-Please note that both events and their context data aren't stable contracts. The 'ZMQ_MONITOR' socket option 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 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 severe latency there will block the socket's application thread.
-
-Only tcp and ipc specific transport events are supported in this initial implementation.
-
-[horizontal]
-Option value type:: zmq_monitor
-Option value unit:: N/A
-Default value:: no callback function
-Applicable socket types:: all
-
 RETURN VALUE
 ------------
 The _zmq_setsockopt()_ function shall return zero if successful. Otherwise it