ZMQx::Class::Socket - A ZMQ Socket


version 0.006




Returns the underlying ZMQ::FFI::SocketBase socket. You probably won't need to call this method yourself.

When a process containg a socket is forked, a new instance of the socket will be set up for the child process.

    $socket->bind( $address );

Bind a socket to an address. Use this for the "server" side, which usually is the more stable part of your infrastructure.

bind will die if it cannot bind.


    $socket->connect( $address );

Connect the socket to an address. Use this for the "client" side.

connect will die if it cannot connect.


    use ZMQ::Constants qw( ZMQ_LINGER );
    $socket->setsockopt( ZMQ_LINGER, 100 );

Set a socket options using a constant. You will need to load the constant from ZMQ::Constants.


    use ZMQ::Constants qw( ZMQ_LINGER );
    $socket->getsockopt( ZMQ_LINGER );

Get a socket option value using a constant. You will need to load the constant from ZMQ::Constants.


    my $rv = $socket->send( \@message );
    my $rv = $socket->send( \@message, ZMQ_DONTWAIT );
    my $rv = $socket->send( $message );

Send a message over the socket.

The message can either be a plain string or an ARRAYREF which will be send as a multipart message (with one message per array element). send will automatically set ZMQ_SENDMORE for multipart messages.

You can pass flags to send. Currently the only flag is ZMQ_DONTWAIT.

send returns the number of bytes sent in the message, and throws an exception on error.


    $socket->send_bytes( \@message );
    $socket->send_bytes( \@message, ZMQ_DONTWAIT );
    $socket->send_bytes( $message );

send_bytes sends raw bytes over the socket. The message can be a plain scalar or an array of scalars. All must hold bytes - ie code points between 0 and 255. If you want strings you should either encode from Unicode yourself first, or use send() instead. You probably need to use send_bytes if you are sending multi-part messages with ZMQ routing information.


    my $msg = $socket->receive;
    my $msg = $socket->receive('blocking;);

receive will get the next message from the socket, if there is one.

You can use the blocking mode (by passing a true value to receive) to block the process until a message has been received (NOT a wise move if you are connected to a lot of clients! Use AnyEvent in this case)

The message will always be a ARRAYREF containing one element per message part.

Returns undef if no message can be received.

See t/30_anyevent.t for some examples

NOTE: If more than one message is waiting to be received you still only get one AnyEvent notification, using receive in a while loop will get you all messages.


    my $msg = $socket->receive_bytes;
    my $msg = $socket->receive_bytes('blocking;);

receive_bytes will get the next message from the socket as bytes. If you want to receive a String (unicode), then you want to use receive_string.


    my $msg = $socket->receive_string
    my $msg = $socket->receive_string('blocking');

    my $msg = $socket->receive_string($blocking, [ $encoding ]);

Receive a String message and decode it via "Encode::decode('utf8', XX)" or an optional encoding. Sending data over a wire means sending bytes. Bytes do not know anything about encoding. If you want to send encoded strings, use this receive_string method to receive them correctly.

If you want to use an explicit encoding you need to set the $blocking variable to true or false.


  my $watcher = $socket->anyevent_watcher( sub {
      while (my $msg = $socket->receive) {
          # do something with msg
  } );

Set up an AnyEvent watcher that will call the passed sub when a new incoming message is received on the socket.

Note that the $socket object isn't passed to the callback. You can only access the $socket thanks to closures.

Please note that you will have to load AnyEvent in your code!


Thomas Klausner <>


This software is copyright (c) 2013 by Validad AG.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.