3party/libzmq
0
0
Fork 0
mirror of https://github.com/zeromq/libzmq.git synced 2025-03-09 15:26:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation for zmq_monitor

Browse Source
This commit is contained in:
Lourens Naudé 2012-05-22 20:08:02 +01:00
parent f27c02d01e
commit 04f0e7f26e
5 changed files with 225 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Makefile.am
View File

@ -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 \

3
doc/zmq.txt
View File

@ -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::

11
doc/zmq_getsockopt.txt
View File

@ -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

221
doc/zmq_monitor.txt Normal file
View File

@ -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>

40
doc/zmq_setsockopt.txt
View File

@ -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