NAME

POEx::ZMQ3::Role::Sockets - Add ZeroMQ sockets to a class

SYNOPSIS

  ## A 'REP' (reply) server that pongs mindlessly, given a ping.
  ## (Call ->start() from a POE-enabled class/app.)
  package MyZMQServer;
  use Moo;
  use ZMQ::Constants ':all';

  with 'POEx::ZMQ3::Role::Sockets';

  sub start {
    my ($self) = @_;
    $self->create_zmq_socket( 'my_server', ZMQ_REP );
    $self->bind_zmq_socket( 'my_server', "tcp://127.0.0.1:$port" );
  }

  sub stop {
    my ($self) = @_;
    $self->clear_all_zmq_sockets;
  }

  sub zmq_message_ready {
    my ($self, $zsock_alias, $zmq_msg, $raw_data) = @_;
    $self->write_zmq_socket( $zsock_alias, "PONG!" )
      if $raw_data =~ /^PING/i;
  }

DESCRIPTION

A Moo::Role giving its consuming class POE-enabled asynchronous ZeroMQ sockets via ZMQ::LibZMQ3.

Methods usually die with a stack trace on failure. (See Try::Tiny if this is not quite what you wanted.)

See http://www.zeromq.org for more about ZeroMQ.

This module has been tested against zeromq-3.2.2 and ZMQ::LibZMQ3-1.03 . =head2 Overrides

These methods should be overriden in your consuming class:

zmq_message_ready

  sub zmq_message_ready {
    my ($self, $zsock_alias, $zmq_msg, $raw_data) = @_;
    . . .
  }

Required.

The zmq_message_ready method should be defined in the consuming class to handle a received message.

Arguments are the ZMQ socket's alias, the ZMQ::LibZMQ3 message object, and the raw data retrieved from the message object, respectively.

zmq_socket_cleared

  sub zmq_socket_cleared {
    my ($self, $zsock_alias) = @_;
    . . .
  }

Optional.

Indicates a ZMQ socket has been cleared.

Attributes

context

The context attribute is the ZeroMQ context object as created by "zmq_init" in ZMQ::LibZMQ3.

These objects can be shared, so long as they are reset/reconstructed in any forked copies.

Methods

create_zmq_socket

  my $zsock = $self->create_zmq_socket( $zsock_alias, $zsock_type_constant );

Creates (and begins watching) a ZeroMQ socket. Expects an (arbitrary) alias and a valid ZMQ::Constants socket type constant or a string mapping to such:

  ## Same:
  $self->create_zmq_socket( $zsock_alias, 'PUB' );
  use ZMQ::Constants ':all';
  $self->create_zmq_socket( $zsock_alias, ZMQ_PUB );

See the man page for zmq_socket for details.

If a POE::Session to manage ZMQ sockets did not previously exist, one is spawned when create_zmq_socket is called.

bind_zmq_socket

  $self->bind_zmq_socket( $zsock_alias, $endpoint );

Binds a "listening" socket type to a specified endpoint.

For example:

  $self->bind_zmq_socket( 'my_serv', 'tcp://127.0.0.1:5552' );

See the man pages for zmq_bind and zmq_connect for details.

connect_zmq_socket

  $self->connect_zmq_socket( $zsock_alias, $target );

Connects a "client" socket type to a specified target endpoint.

See the man pages for zmq_connect and zmq_bind for details.

Note that ZeroMQ manages its own actual connections; a successful call to zmq_connect does not necessarily mean a persistent connection is open. See the ZeroMQ documentation for details.

clear_zmq_socket

  $self->clear_zmq_socket( $zsock_alias );

Shut down a specified socket.

clear_all_zmq_sockets

  $self->clear_all_zmq_sockets;

Shut down all sockets.

get_zmq_socket

  my $zsock = $self->get_zmq_socket( $zsock_alias );

Retrieve the actual ZeroMQ socket object for the given alias.

Only useful for darker forms of magic.

set_zmq_sockopt

  $self->set_zmq_sockopt( $zsock_alias, @params );

Calls zmq_setsockopt to set options on the specified ZMQ socket.

Most options should be set between socket creation and any initial "connect_zmq_socket" or "bind_zmq_socket" call. See the man page.

write_zmq_socket

  $self->write_zmq_socket( $zsock_alias, $data );

Write raw data or a ZeroMQ message object to the specified socket alias.

Optional extra params can be passed on to zmq_sendmsg.

SEE ALSO

ZMQ::LibZMQ3

http://www.zeromq.org

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>