zmonitor(3)
===========

NAME
----
zmonitor - socket event monitor

SYNOPSIS
--------
----
//  Create a new socket monitor
CZMQ_EXPORT zmonitor_t *
    zmonitor_new (zctx_t *ctx, void *socket, int events);

//  Destroy a socket monitor
CZMQ_EXPORT void
    zmonitor_destroy (zmonitor_t **self_p);

//  Receive a status message from the monitor; if no message arrives within
//  500 msec, or the call was interrupted, returns NULL.
CZMQ_EXPORT zmsg_t *
    zmonitor_recv (zmonitor_t *self);

//  Get the ZeroMQ socket, for polling 
CZMQ_EXPORT void *
    zmonitor_socket (zmonitor_t *self);

//  Enable verbose tracing of commands and activity
CZMQ_EXPORT void
    zmonitor_set_verbose (zmonitor_t *self, bool verbose);

// Self test of this class
CZMQ_EXPORT void
    zmonitor_test (bool verbose);

----

DESCRIPTION
-----------

The zmonitor class provides an API for obtaining socket events such as
connected, listen, disconnected, etc. Socket events are only available
for sockets connecting or bound to ipc:// and tcp:// endpoints.

This class wraps the ZMQ socket monitor API, see zmq_socket_monitor for
details. Currently this class requires libzmq v4.0 or later and is empty
on older versions of libzmq.

EXAMPLE
-------
.From zmonitor_test method
----
    zctx_t *ctx = zctx_new ();
    bool result;

    void *sink = zsocket_new (ctx, ZMQ_PULL);
    zmonitor_t *sinkmon = zmonitor_new (ctx,
        sink, ZMQ_EVENT_LISTENING | ZMQ_EVENT_ACCEPTED);
    zmonitor_set_verbose (sinkmon, verbose);

    //  Check sink is now listening
    zsocket_bind (sink, "tcp://*:5555");
    result = s_check_event (sinkmon, ZMQ_EVENT_LISTENING);
    assert (result);

    void *source = zsocket_new (ctx, ZMQ_PUSH);
    zmonitor_t *sourcemon = zmonitor_new (ctx,
        source, ZMQ_EVENT_CONNECTED | ZMQ_EVENT_DISCONNECTED);
    zmonitor_set_verbose (sourcemon, verbose);
    zsocket_connect (source, "tcp://localhost:5555");

    //  Check source connected to sink
    result = s_check_event (sourcemon, ZMQ_EVENT_CONNECTED);
    assert (result);

    //  Check sink accepted connection
    result = s_check_event (sinkmon, ZMQ_EVENT_ACCEPTED);
    assert (result);

    //  Destroy sink to trigger a disconnect event on the source
    //  PH: disabled since this causes an access violation in
    //  zmonitor_destroy as the socket is no longer valid.
//     zsocket_destroy (ctx, sink);
//     result = s_check_event (sourcemon, ZMQ_EVENT_DISCONNECTED);
//     assert (result);

    zmonitor_destroy (&sinkmon);
    zmonitor_destroy (&sourcemon);
    zctx_destroy (&ctx);
----

SEE ALSO
--------
linkczmq:czmq[7]
