NAME

AnyEvent::MP::DataConn - create socket connections between nodes

SYNOPSIS

   use AnyEvent::MP::DataConn;

DESCRIPTION

This module can be used to create socket connections between the local and a remote node in the aemp network. The socket can be used freely for any purpose, and in most cases, this mechanism is a good way to transport big chunks of binary data.

The connections created by this module use the same security mechanisms as normal AEMP connections (secure authentication, optional use of TLS), and in fact, use the same listening port as AEMP connections, so when two nodes can reach each other via the normal aemp protocol, they can create data connections as well, no extra ports or firewall rules are required.

The protocol used is, however, not the AEMP transport protocol, so this will only work between nodes implementing the "aemp-dataconn" protocol extension.

FUNCTIONS

AnyEvent::MP::DataConn::connect_to $node, $timeout, $initfunc, @initdata, $cb->($handle)

Creates a socket connection between the local node and the node $node (which can also be specified as a port). One of the nodes must have listening ports ("binds").

When the connection could be successfully created, the $initfunc will be called with the given @initdata on the remote node (similar to snd_to_func or spawn), and the AnyEvent::Handle object representing the remote connection end as additional argument.

Also, the callback given as last argument will be called with the AnyEvent::Handle object for the local side.

The AnyEvent::Handle objects will be in a "quiescent" state - you could rip out the file handle and forget about it, but it is recommended to use it, as the security settings might have called for a TLS connection. If you opt to use it, you at least have to set an on_error callback.

In case of any error (timeout etc.), nothing will be called on the remote side, and the local port will be kil'ed with an AnyEvent::MP::DataConn => "error message" kill reason.

The timeout should be large enough to cover at least four network round-trips and one message round-trip.

Example: on node1, establish a connection to node2 and send a line of text, one node2, provide a receiver function.

   # node1, code executes in some port context
   AnyEvent::MP::DataConn::connect_to "node2", 5, "pkg::receiver", 1, sub {
      my ($hdl) = @_;
      warn "connection established, sending line.\n"
      $hdl->push_write ("blabla\n")
   };

   # node2
   sub pkg::receiver {
      my ($one, $hdl) = @_;
      warn "connection established, wait for a line...\n"

      $hdl->push_read (line => sub {
         warn "received a line: $_[1]\n";
         undef $hdl;
      });
   }

SEE ALSO

AnyEvent::MP.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/