[zeromq-dev] ZMQ_MONITOR socket option

[Lourens Naudé]

Hey guys,

I took a stab at implementing a socket option ( ZMQ_MONITOR ) that exposes
changes in session state to a callback function. This is driven partly by
requests for such a feature on the list as well as upcoming operations
requirements for a commercial project.

>From the docs :

"ZMQ_MONITOR: Registers a callback for socket state changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Registers a callback function / event sink for changes in underlying socket
state.
Expected signature is `void (zmq_monitor_fn) (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_fn
Option value unit:: N/A
Default value:: no callback function
Applicable socket types:: all"

Caveats :

* Session state changes for tcp and ipc transport only ( those are much
more volatile than inproc )
* No HWM or other mailbox events - they're tricky with distributor sockets
( PUSH, PUB )
* Callbacks are per socket and there's no effort towards any correlation
and topology mapping - this can be done elsewhere.
* Events and event arguments aren't stable contracts yet ( eg. exposing the
underlying socket descriptor for some events are dangerous )

At this point I'm soliciting feedback / requirements from other
environments and not spawning a formal pull request. Please review at
https://github.com/methodmissing/libzmq/compare/master...events and circle
back if and when there's a moment.

- Lourens
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20120504/a3d10315/attachment.htm>