NAME
    ZeroMQ - A ZeroMQ2 wrapper for Perl

SYNOPSIS
        # echo server
        use ZeroMQ qw/:all/;

        my $cxt = ZeroMQ::Context->new;
        my $sock = $cxt->socket(ZMQ_REP);
        $sock->bind($addr);
  
        my $msg;
        foreach (1..$roundtrip_count) {
            $msg = $sock->recv();
            $sock->send($msg);
        }

        # custom serialization
        ZeroMQ::register_read_type(myformat => sub { ... });
        ZeroMQ::register_write_type(myformat => sub { .. });

        $socket->send_as( myformat => $data ); # serialize using above callback
        my $thing = $socket->recv_as( "myformat" );

    See the eg/ directory for full examples.

DESCRIPTION
    The "ZeroMQ" module is a wrapper of the 0MQ message passing library for
    Perl. It's a thin wrapper around the C API. Please read
    <http://zeromq.org> for more details on ZeroMQ.

    Loading "ZeroMQ" will make the ZeroMQ::Context, ZeroMQ::Socket, and
    ZeroMQ::Message classes available as well.

BASIC USAGE
    To start using ZeroMQ, you need to create a context object, then as many
    ZeroMQ::Socket as you need:

        my $ctxt = ZeroMQ::Context->new;
        my $socket = $ctxt->socket( ... options );

    You need to call "bind()" or "connect()" on the socket, depending on
    your usage. For example on a typical server-client model you would write
    on the server side:

        $socket->bind( "tcp://127.0.0.1:9999" );

    and on the client side:

        $socket->connect( "tcp://127.0.0.1:9999" );

    The underlying zeromq library offers TCP, multicast, in-process, and ipc
    connection patterns. Read the zeromq manual for more details on other
    ways to setup the socket.

    When sending data, you can either pass a ZeroMQ::Message object or a
    Perl string.

        # the following two send() calls are equivalent
        my $msg = ZeroMQ::Message->new( "a simple message" );
        $socket->send( $msg );
        $socket->send( "a simple message" );

    In most cases using ZeroMQ::Message is redundunt, so you will most
    likely use the string version.

    To receive, simply call "recv()" on the socket

        my $msg = $socket->recv;

    The received message is an instance of ZeroMQ::Message object, and you
    can access the content held in the message via the "data()" method:

        my $data = $msg->data;

SERIALIZATION
    ZeroMQ.pm comes with a simple serialization/deserialization mechanism.

    To serialize, use "register_write_type()" to register a name and an
    associated callback to serialize the data. For example, for JSON we do
    the following (this is already done for you in ZeroMQ.pm if you have
    JSON.pm installed):

        use JSON ();
        ZeroMQ::register_write_type('json' => \&JSON::encode_json);
        ZeroMQ::register_read_type('json' => \&JSON::decode_json);

    Then you can use "send_as()" and "recv_as()" to specify the
    serialization type as the first argument:

        my $ctxt = ZeroMQ::Context->new();
        my $sock = $ctxt->socket( ZMQ_REQ );

        $sock->send_as( json => $complex_perl_data_structure );

    The otherside will receive a JSON encoded data. The receivind side can
    be written as:

        my $ctxt = ZeroMQ::Context->new();
        my $sock = $ctxt->socket( ZMQ_REP );

        my $complex_perl_data_structure = $sock->recv_as( 'json' );

    If you have JSON.pm (must be 2.00 or above), then the JSON serializer /
    deserializer is automatically enabled. If you want to tweak the
    serializer option, do something like this:

        my $coder = JSON->new->utf8->pretty; # pretty print
        ZeroMQ::register_write_type( json => sub { $coder->encode($_[0]) } );
        ZeroMQ::register_read_type( json => sub { $coder->decode($_[0]) } );

    Note that this will have a GLOBAL effect. If you want to change only
    your application, use a name that's different from 'json'.

ASYNCHRONOUS I/O WITH ZEROMQ
    By default ZeroMQ comes with its own poll() mechanism that can handle
    non-blocking sockets. You can use this by creating a ZeroMQ::PollItem
    object:

        my $pi = ZeroMQ::PollItem->new;
        $pi->add( $zmq_socket, ZMQ_POLLIN, sub {
            ....
        } );

    Unfortunately this custom polling scheme doesn't play too well with
    AnyEvent. In the near future the zeromq library is believed to come with
    some API to expose the file descriptor underneath the socket objects --
    when that happens, we will be able to easily integrate it to AnyEvent.
    Stay tuned!

NOTES ON MULTI-PROCESS and MULTI-THREADED USAGE
    ZeroMQ works on both multi-process and multi-threaded use cases, but you
    need to be careful bout sharing ZeroMQ objects.

    For multi-process environments, you should not be sharing the context
    object. Create separate contexts for each process, and therefore you
    shouldn't be sharing the socket objects either.

    For multi-thread environemnts, you can share the same context object.
    However you cannot share sockets.

FUNCTIONS
  version()
    Returns the version of the underlying zeromq library that is being
    linked. In scalar context, returns a dotted version string. In list
    context, returns a 3-element list of the version numbers:

        my $version_string = ZeroMQ::version();
        my ($major, $minor, $patch) = ZeroMQ::version();

  device($type, $sock1, $sock2)
  register_read_type($name, \&callback)
    Register a read callback for a given $name. This is used in "recv_as()".
    The callback receives the data received from the socket.

  register_write_type($name, \&callback)
    Register a write callback for a given $name. This is used in "send_as()"
    The callback receives the Perl structure given to "send_as()"

EXPORTS
    You may choose to import one or more (using the ":all" import tag)
    constants into your namespace by supplying arguments to the "use ZeroMQ"
    call as shown in the synopsis above.

    The exportable constants are:

  ":socket" - Socket types and socket options
    ZMQ_PAIR
    ZMQ_PUB
    ZMQ_SUB
    ZMQ_REQ
    ZMQ_REP
    ZMQ_XREQ
    ZMQ_XREP
    ZMQ_PULL
    ZMQ_PUSH
    ZMQ_UPSTREAM
    ZMQ_DOWNSTREAM
    ZMQ_NOBLOCK
    ZMQ_SNDMORE
    ZMQ_HWM
    ZMQ_SWAP
    ZMQ_AFFINITY
    ZMQ_IDENTITY
    ZMQ_SUBSCRIBE
    ZMQ_UNSUBSCRIBE
    ZMQ_RATE
    ZMQ_RECOVERY_IVL
    ZMQ_MCAST_LOOP
    ZMQ_SNDBUF
    ZMQ_RCVBUF
    ZMQ_RCVMORE
    ZMQ_POLLIN
    ZMQ_POLLOUT
    ZMQ_POLLERR

  ":device" - Device types
    ZMQ_QUEUE
    ZMQ_FORWARDER
    ZMQ_STREAMER

  ":message" - Message Options
    ZMQ_MAX_VSM_SIZE
    ZMQ_DELIMITER
    ZMQ_VSM
    ZMQ_MSG_MORE
    ZMQ_MSG_SHARED

  miscellaneous
    ZMQ_HAUSNUMERO

CAVEATS
    This is an early release. Proceed with caution, please report (or better
    yet: fix) bugs you encounter. Tested againt 0MQ 2.0.8.

SEE ALSO
    ZeroMQ::Context, ZeroMQ::Socket, ZeroMQ::Message

    <http://zeromq.org>

AUTHOR
    Daisuke Maki "<daisuke@endeworks.jp>"

    Steffen Mueller, "<smueller@cpan.org>"

COPYRIGHT AND LICENSE
    The ZeroMQ module is

    Copyright (C) 2010 by Daisuke Maki

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.0 or, at
    your option, any later version of Perl 5 you may have available.

