From 04f0e7f26e18a2802d8683fc12ef8a67197fda6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lourens=20Naud=C3=A9?= Date: Tue, 22 May 2012 20:08:02 +0100 Subject: [PATCH] Documentation for zmq_monitor --- doc/Makefile.am | 2 +- doc/zmq.txt | 3 + doc/zmq_getsockopt.txt | 11 -- doc/zmq_monitor.txt | 221 +++++++++++++++++++++++++++++++++++++++++ doc/zmq_setsockopt.txt | 40 -------- 5 files changed, 225 insertions(+), 52 deletions(-) create mode 100644 doc/zmq_monitor.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index eba0f998..58c84aa7 100644 --- a/doc/Makefile.am +++ b/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 \ diff --git a/doc/zmq.txt b/doc/zmq.txt index 4dfe0d1f..a2635874 100644 --- a/doc/zmq.txt +++ b/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:: diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index a2258411..0eae8d91 100644 --- a/doc/zmq_getsockopt.txt +++ b/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 diff --git a/doc/zmq_monitor.txt b/doc/zmq_monitor.txt new file mode 100644 index 00000000..1570f5ba --- /dev/null +++ b/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é \ No newline at end of file diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index d4a48ea7..fee30cc8 100644 --- a/doc/zmq_setsockopt.txt +++ b/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