mirror of
https://github.com/zeromq/libzmq.git
synced 2024-12-13 18:55:10 +01:00
221 lines
6.4 KiB
Plaintext
221 lines
6.4 KiB
Plaintext
zmq_ctx_set_monitor(3)
|
|
======================
|
|
|
|
|
|
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);
|
|
----
|
|
|
|
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.
|
|
|
|
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_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
|
|
----
|
|
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
|
|
--------
|
|
linkzmq:zmq[7]
|
|
|
|
|
|
AUTHORS
|
|
-------
|
|
This 0MQ manual page was written by Lourens Naudé <lourens@methodmissing.com> |