/ 
ZeroMQ-0.02
River stage one • 6 direct dependents • 7 total dependents
/ ZeroMQ

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 );

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.

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:

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'.

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:

EXPORTS

: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.7.

Use of the inproc:// transport layer doesn't seem to work between two perl ithreads. This may be due to the fact that right now, context aren't shared between ithreads and inproc works only within a single context. Try another transport layer until contexts can be shared.

SEE ALSO

ZeroMQ::Context, ZeroMQ::Socket, ZeroMQ::Message

http://zeromq.org

AUTHOR

Steffen Mueller, <smueller@cpan.org>

Daisuke Maki <daisuke@endeworks.jp>

COPYRIGHT AND LICENSE

The ZeroMQ module is

Copyright (C) 2010 by Steffen Mueller

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.