zpoller(3)
==========

NAME
----
zpoller - trivial socket poller class

SYNOPSIS
--------
----
//  Create new poller
CZMQ_EXPORT zpoller_t *
    zpoller_new (void *reader, ...);

//  Destroy a poller
CZMQ_EXPORT void
    zpoller_destroy (zpoller_t **self_p);

//  Poll the registered readers for I/O, return first socket that has input.
//  This means the order that sockets are defined in the poll list affects
//  their priority. If you need a balanced poll, use the low level zmq_poll
//  method directly.
CZMQ_EXPORT void *
    zpoller_wait (zpoller_t *self, int timeout);

//  Return true if the last zpoller_wait () call ended because the timeout
//  expired, without any error.
CZMQ_EXPORT bool
    zpoller_expired (zpoller_t *self);

//  Return true if the last zpoller_wait () call ended because the process
//  was interrupted, or the parent context was destroyed.
CZMQ_EXPORT bool
    zpoller_terminated (zpoller_t *self);

//  Self test of this class
CZMQ_EXPORT int
    zpoller_test (bool verbose);
----

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

The zpoller class provides a minimalist interface to ZeroMQ's zmq_poll 
API, for the very common case of reading from a number of sockets.
It does not provide polling for output, nor polling on file handles.
If you need either of these, use the zmq_poll API directly.


EXAMPLE
-------
.From zpoller_test method
----
    zctx_t *ctx = zctx_new ();
    
    //  Create a few sockets
    void *vent = zsocket_new (ctx, ZMQ_PUSH);
    int rc = zsocket_bind (vent, "tcp://*:9000");
    assert (rc != -1);
    void *sink = zsocket_new (ctx, ZMQ_PULL);
    rc = zsocket_connect (sink, "tcp://localhost:9000");
    assert (rc != -1);
    void *bowl = zsocket_new (ctx, ZMQ_PULL);
    void *dish = zsocket_new (ctx, ZMQ_PULL);
    
    //  Set-up poller
    zpoller_t *poller = zpoller_new (bowl, sink, dish, NULL);
    assert (poller);

    zstr_send (vent, "Hello, World");
    
    //  We expect a message only on the sink
    void *which = zpoller_wait (poller, -1);
    assert (which == sink);
    assert (zpoller_expired (poller) == false);
    assert (zpoller_terminated (poller) == false);
    char *message = zstr_recv (which);
    assert (streq (message, "Hello, World"));
    free (message);
    
    //  Destroy poller and context
    zpoller_destroy (&poller);
    zctx_destroy (&ctx);
----

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