NAME

AnyEvent::MP - multi-processing/message-passing framework

SYNOPSIS

   use AnyEvent::MP;

   $NODE      # contains this node's noderef
   NODE       # returns this node's noderef
   NODE $port # returns the noderef of the port

   snd $port, type => data...;

   $SELF      # receiving/own port id in rcv callbacks

   rcv $port, smartmatch => $cb->($port, @msg);

   # examples:
   rcv $port2, ping => sub { snd $_[0], "pong"; 0 };
   rcv $port1, pong => sub { warn "pong received\n" };
   snd $port2, ping => $port1;

   # more, smarter, matches (_any_ is exported by this module)
   rcv $port, [child_died => $pid] => sub { ...
   rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3

DESCRIPTION

This module (-family) implements a simple message passing framework.

Despite its simplicity, you can securely message other processes running on the same or other hosts.

For an introduction to this module family, see the AnyEvent::MP::Intro manual page.

At the moment, this module family is severly broken and underdocumented, so do not use. This was uploaded mainly to reserve the CPAN namespace - stay tuned! The basic API should be finished, however.

CONCEPTS

port

A port is something you can send messages to with the snd function, and you can register rcv handlers with. All rcv handlers will receive messages they match, messages will not be queued.

port id - noderef#portname

A port id is always the noderef, a hash-mark (#) as separator, followed by a port name (a printable string of unspecified format).

node

A node is a single process containing at least one port - the node port. You can send messages to node ports to let them create new ports, among other things.

Initially, nodes are either private (single-process only) or hidden (connected to a master node only). Only when they epxlicitly "become public" can you send them messages from unrelated other nodes.

noderef - host:port,host:port..., id@noderef, id

A noderef is a string that either uniquely identifies a given node (for private and hidden nodes), or contains a recipe on how to reach a given node (for public nodes).

VARIABLES/FUNCTIONS

$thisnode = NODE / $NODE

The NODE function returns, and the $NODE variable contains the noderef of the local node. The value is initialised by a call to become_public or become_slave, after which all local port identifiers become invalid.

$noderef = node_of $portid

Extracts and returns the noderef from a portid or a noderef.

$SELF

Contains the current port id while executing rcv callbacks or psub blocks.

SELF, %SELF, @SELF...

Due to some quirks in how perl exports variables, it is impossible to just export $SELF, all the symbols called SELF are exported by this module, but only $SELF is currently used.

snd $portid, type => @data

snd $portid, @msg

Send the given message to the given port ID, which can identify either a local or a remote port, and can be either a string or soemthignt hat stringifies a sa port ID (such as a port object :).

While the message can be about anything, it is highly recommended to use a string as first element (a portid, or some word that indicates a request type etc.).

The message data effectively becomes read-only after a call to this function: modifying any argument is not allowed and can cause many problems.

The type of data you can transfer depends on the transport protocol: when JSON is used, then only strings, numbers and arrays and hashes consisting of those are allowed (no objects). When Storable is used, then anything that Storable can serialise and deserialise is allowed, and for the local node, anything can be passed.

kil $portid[, @reason]

Kill the specified port with the given @reason.

If no @reason is specified, then the port is killed "normally" (linked ports will not be kileld, or even notified).

Otherwise, linked ports get killed with the same reason (second form of mon, see below).

Runtime errors while evaluating rcv callbacks or inside psub blocks will be reported as reason die => $@.

Transport/communication errors are reported as transport_error => $message.

$guard = mon $portid, $cb->(@reason)

$guard = mon $portid, $otherport

$guard = mon $portid, $otherport, @msg

Monitor the given port and do something when the port is killed.

In the first form, the callback is simply called with any number of @reason elements (no @reason means that the port was deleted "normally"). Note also that the callback must never die, so use eval if unsure.

In the second form, the other port will be kil'ed with @reason, iff a @reason was specified, i.e. on "normal" kils nothing happens, while under all other conditions, the other port is killed with the same reason.

In the last form, a message of the form @msg, @reason will be snd.

Example: call a given callback when $port is killed.

   mon $port, sub { warn "port died because of <@_>\n" };

Example: kill ourselves when $port is killed abnormally.

   mon $port, $self;

Example: send us a restart message another $port is killed.

   mon $port, $self => "restart";

$guard = mon_guard $port, $ref, $ref...

Monitors the given $port and keeps the passed references. When the port is killed, the references will be freed.

Optionally returns a guard that will stop the monitoring.

This function is useful when you create e.g. timers or other watchers and want to free them when the port gets killed:

  $port->rcv (start => sub {
     my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub {
        undef $timer if 0.9 < rand;
     });
  });

lnk $port1, $port2

Link two ports. This is simply a shorthand for:

   mon $port1, $port2;
   mon $port2, $port1;

It means that if either one is killed abnormally, the other one gets killed as well.

$local_port = port

Create a new local port object that supports message matching.

$portid = port { my @msg = @_; $finished }

Creates a "mini port", that is, a very lightweight port without any pattern matching behind it, and returns its ID.

The block will be called for every message received on the port. When the callback returns a true value its job is considered "done" and the port will be destroyed. Otherwise it will stay alive.

The message will be passed as-is, no extra argument (i.e. no port id) will be passed to the callback.

If you need the local port id in the callback, this works nicely:

   my $port; $port = miniport {
      snd $otherport, reply => $port;
   };

reg $portid, $name

Registers the given port under the name $name. If the name already exists it is replaced.

A port can only be registered under one well known name.

A port automatically becomes unregistered when it is killed.

rcv $portid, tagstring => $callback->(@msg), ...

rcv $portid, $smartmatch => $callback->(@msg), ...

rcv $portid, [$smartmatch...] => $callback->(@msg), ...

Register callbacks to be called on matching messages on the given port.

The callback has to return a true value when its work is done, after which is will be removed, or a false value in which case it will stay registered.

The global $SELF (exported by this module) contains $portid while executing the callback.

Runtime errors wdurign callback execution will result in the port being kiled.

If the match is an array reference, then it will be matched against the first elements of the message, otherwise only the first element is being matched.

Any element in the match that is specified as _any_ (a function exported by this module) matches any single element of the message.

While not required, it is highly recommended that the first matching element is a string identifying the message. The one-string-only match is also the most efficient match (by far).

$closure = psub { BLOCK }

Remembers $SELF and creates a closure out of the BLOCK. When the closure is executed, sets up the environment in the same way as in rcv callbacks, i.e. runtime errors will cause the port to get kiled.

This is useful when you register callbacks from rcv callbacks:

   rcv delayed_reply => sub {
      my ($delay, @reply) = @_;
      my $timer = AE::timer $delay, 0, psub {
         snd @reply, $SELF;
      };
   };

FUNCTIONS FOR NODES

become_public endpoint...

Tells the node to become a public node, i.e. reachable from other nodes.

If no arguments are given, or the first argument is undef, then AnyEvent::MP tries to bind on port 4040 on all IP addresses that the local nodename resolves to.

Otherwise the first argument must be an array-reference with transport endpoints ("ip:port", "hostname:port") or port numbers (in which case the local nodename is used as hostname). The endpoints are all resolved and will become the node reference.

NODE MESSAGES

Nodes understand the following messages sent to them. Many of them take arguments called @reply, which will simply be used to compose a reply message - $reply[0] is the port to reply to, $reply[1] the type and the remaining arguments are simply the message data.

lookup => $name, @reply

Replies with the port ID of the specified well-known port, or undef.

devnull => ...

Generic data sink/CPU heat conversion.

relay => $port, @msg

Simply forwards the message to the given port.

eval => $string[ @reply]

Evaluates the given string. If @reply is given, then a message of the form @reply, $@, @evalres is sent.

Example: crash another node.

   snd $othernode, eval => "exit";

time => @reply

Replies the the current node time to @reply.

Example: tell the current node to send the current time to $myport in a timereply message.

   snd $NODE, time => $myport, timereply => 1, 2;
   # => snd $myport, timereply => 1, 2, <time>

SEE ALSO

AnyEvent.

AUTHOR

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