'\" t
.\"     Title: zmq_ctx_socket_monitor
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 11/23/2012
.\"    Manual: 0MQ Manual
.\"    Source: 0MQ 3.2.1
.\"  Language: English
.\"
.TH "ZMQ_CTX_SOCKET_MONIT" "3" "11/23/2012" "0MQ 3\&.2\&.1" "0MQ Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
zmq_socket_monitor \- register a monitoring callback
.SH "SYNOPSIS"
.sp
\fBint zmq_socket_monitor (void \fR\fB\fI*socket\fR\fR\fB, char * \fR\fB\fI*addr\fR\fR\fB, int \fR\fB\fIevents\fR\fR\fB);\fR
.SH "DESCRIPTION"
.sp
The \fIzmq_socket_monitor()\fR function shall spawn a \fIPAIR\fR socket that publishes socket state changes (events) over the inproc:// transport to a given endpoint\&. Messages are \fIzmq_event_t\fR structs\&. It\(cqs recommended to connect via a \fIPAIR\fR socket in another application thread and handle monitoring events there\&. It\(cqs possible to also supply a bitmask (\fIZMQ_EVENT_ALL\fR or any combination of the \fIZMQ_EVENT_*\fR constants) of the events you\(cqre interested in\&.
.sp
.if n \{\
.RS 4
.\}
.nf
// monitoring thread
static void *req_socket_monitor (void *ctx)
{
    zmq_event_t event;
    int rc;

    void *s = zmq_socket (ctx, ZMQ_PAIR);
    assert (s);

    rc = zmq_connect (s, "inproc://monitor\&.req");
    assert (rc == 0);
    while (true) {
        zmq_msg_t msg;
        zmq_msg_init (&msg);
        rc = zmq_recvmsg (s, &msg, 0);
        if (rc == \-1 && zmq_errno() == ETERM) break;
        assert (rc != \-1);
        memcpy (&event, zmq_msg_data (&msg), sizeof (event));
        switch (event\&.event) {
        case ZMQ_EVENT_CONNECTED:
            // handle socket connected event
            break;
        case ZMQ_EVENT_CLOSED:
            // handle socket closed event
            break;
        }
    }
    zmq_close (s);
    return NULL;
}

// register a monitor endpoint for all socket events
rc = zmq_socket_monitor (req, "inproc://monitor\&.req", ZMQ_EVENT_ALL);
assert (rc == 0);

// spawn a monitoring thread
rc = pthread_create (&threads [0], NULL, req_socket_monitor, ctx);
assert (rc == 0);
.fi
.if n \{\
.RE
.\}
.sp
Only connection oriented (tcp and ipc) transports are supported in this initial implementation\&.
.sp
Supported events are:
.SS "ZMQ_EVENT_CONNECTED: connection established"
.sp
The \fIZMQ_EVENT_CONNECTED\fR event triggers when a connection has been established to a remote peer\&. This can happen either synchronous or asynchronous\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.connected\&.addr // peer address
data\&.connected\&.fd // socket descriptor
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_CONNECT_DELAYED: synchronous connect failed, it\(cqs being polled"
.sp
The \fIZMQ_EVENT_CONNECT_DELAYED\fR event triggers when an immediate connection attempt is delayed and it\(cqs completion\(cqs being polled for\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.connect_delayed\&.addr // peer address
data\&.connect_delayed\&.err // errno value
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt"
.sp
The \fIZMQ_EVENT_CONNECT_RETRIED\fR event triggers when a connection attempt is being handled by reconnect timer\&. The reconnect interval\(cqs recomputed for each attempt\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.connect_retried\&.addr // peer address
data\&.connect_retried\&.interval // computed reconnect interval
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_LISTENING: socket bound to an address, ready to accept connections"
.sp
The \fIZMQ_EVENT_LISTENING\fR event triggers when a socket\(cqs successfully bound to a an interface\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.listening\&.addr //  listen address
data\&.listening\&.fd // socket descriptor
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_BIND_FAILED: socket could not bind to an address"
.sp
The \fIZMQ_EVENT_BIND_FAILED\fR event triggers when a socket could not bind to a given interface\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.bind_failed\&.addr // listen address
data\&.bind_failed\&.err // errno value
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_ACCEPTED: connection accepted to bound interface"
.sp
The \fIZMQ_EVENT_ACCEPTED\fR event triggers when a connection from a remote peer has been established with a socket\(cqs listen address\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.accepted\&.addr // listen address
data\&.accepted\&.fd // socket descriptor
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_ACCEPT_FAILED: could not accept client connection"
.sp
The \fIZMQ_EVENT_ACCEPT_FAILED\fR event triggers when a connection attempt to a socket\(cqs bound address fails\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.accept_failed\&.addr // listen address
data\&.accept_failed\&.err // errno value
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_CLOSED: connection closed"
.sp
The \fIZMQ_EVENT_CLOSED\fR event triggers when a connection\(cqs underlying descriptor has been closed\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.closed\&.addr // address
data\&.closed\&.fd // socket descriptor
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_CLOSE_FAILED: connection couldn\(cqt be closed"
.sp
The \fIZMQ_EVENT_CLOSE_FAILED\fR event triggers when a descriptor could not be released back to the OS\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.close_failed\&.addr // address
data\&.close_failed\&.err // errno value
.fi
.if n \{\
.RE
.\}
.sp
.SS "ZMQ_EVENT_DISCONNECTED: broken session"
.sp
The \fIZMQ_EVENT_DISCONNECTED\fR event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session\&.
.PP
\fBEvent metadata:\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
data\&.disconnected\&.addr // address
data\&.disconnected\&.fd // socket descriptor
.fi
.if n \{\
.RE
.\}
.sp
.SH "RETURN VALUE"
.sp
The \fIzmq_socket_monitor()\fR function returns a value of 0 or greater if successful\&. Otherwise it returns \-1 and sets \fIerrno\fR to one of the values defined below\&.
.SH "ERRORS"
.PP
\fBETERM\fR
.RS 4
The 0MQ
\fIcontext\fR
associated with the specified
\fIsocket\fR
was terminated\&.
.RE
.PP
\fBEPROTONOSUPPORT\fR
.RS 4
The requested
\fItransport\fR
protocol is not supported\&. Monitor sockets are required to use the inproc:// transport\&.
.RE
.PP
\fBEINVAL\fR
.RS 4
The endpoint supplied is invalid\&.
.RE
.SH "EXAMPLE"
.PP
\fBObserving a REP socket\(cqs connection state\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
// REP socket monitor thread
static void *rep_socket_monitor (void *ctx)
{
    zmq_event_t event;
    int rc;

    void *s = zmq_socket (ctx, ZMQ_PAIR);
    assert (s);

    rc = zmq_connect (s, "inproc://monitor\&.rep");
    assert (rc == 0);
    while (true) {
        zmq_msg_t msg;
        zmq_msg_init (&msg);
        rc = zmq_recvmsg (s, &msg, 0);
        if (rc == \-1 && zmq_errno() == ETERM) break;
        assert (rc != \-1);
        memcpy (&event, zmq_msg_data (&msg), sizeof (event));
        switch (event\&.event) {
        case ZMQ_EVENT_LISTENING:
            printf ("listening socket descriptor %d\en", event\&.data\&.listening\&.fd);
            printf ("listening socket address %s\en", event\&.data\&.listening\&.addr);
            break;
        case ZMQ_EVENT_ACCEPTED:
            printf ("accepted socket descriptor %d\en", event\&.data\&.accepted\&.fd);
            printf ("accepted socket address %s\en", event\&.data\&.accepted\&.addr);
            break;
        case ZMQ_EVENT_CLOSE_FAILED:
            printf ("socket close failure error code %d\en", event\&.data\&.close_failed\&.err);
            printf ("socket address %s\en", event\&.data\&.close_failed\&.addr);
            break;
        case ZMQ_EVENT_CLOSED:
            printf ("closed socket descriptor %d\en", event\&.data\&.closed\&.fd);
            printf ("closed socket address %s\en", event\&.data\&.closed\&.addr);
            break;
        case ZMQ_EVENT_DISCONNECTED:
            printf ("disconnected socket descriptor %d\en", event\&.data\&.disconnected\&.fd);
            printf ("disconnected socket address %s\en", event\&.data\&.disconnected\&.addr);
            break;
        }
        zmq_msg_close (&msg);
    }
    zmq_close (s);
    return NULL;
}


//  Create the infrastructure
void *ctx = zmq_init (1);
assert (ctx);

// REP socket
rep = zmq_socket (ctx, ZMQ_REP);
assert (rep);

// REP socket monitor, all events
rc = zmq_socket_monitor (rep, "inproc://monitor\&.rep", ZMQ_EVENT_ALL);
assert (rc == 0);
rc = pthread_create (&threads [0], NULL, rep_socket_monitor, ctx);
assert (rc == 0);

rc = zmq_bind (rep, addr);
assert (rc == 0);

// Allow some time for event detection
zmq_sleep (1);

// Close the REP socket
rc = zmq_close (rep);
assert (rc == 0);

zmq_term (ctx);
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.sp
\fBzmq\fR(7)
.SH "AUTHORS"
.sp
This 0MQ manual page was written by Lourens Naud\('e <\m[blue]\fBlourens@methodmissing\&.com\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "NOTES"
.IP " 1." 4
lourens@methodmissing.com
.RS 4
\%mailto:lourens@methodmissing.com
.RE