--- AnyEvent-MP/MP.pm 2009/08/31 11:08:25 1.73 +++ AnyEvent-MP/MP.pm 2009/10/02 14:12:16 1.99 @@ -1,21 +1,20 @@ =head1 NAME -AnyEvent::MP - multi-processing/message-passing framework +AnyEvent::MP - erlang-style multi-processing/message-passing framework =head1 SYNOPSIS use AnyEvent::MP; - $NODE # contains this node's noderef - NODE # returns this node's noderef - NODE $port # returns the noderef of the port + $NODE # contains this node's node ID + NODE # returns this node's node ID $SELF # receiving/own port id in rcv callbacks # initialise the node so it can send/receive messages configure; - # ports are message endpoints + # ports are message destinations # sending messages snd $port, type => data...; @@ -34,19 +33,17 @@ my $port = spawn $node, $initfunc, @initdata; # monitoring - mon $port, $cb->(@msg) # callback is invoked on death - mon $port, $otherport # kill otherport on abnormal death - mon $port, $otherport, @msg # send message on death + mon $localport, $cb->(@msg) # callback is invoked on death + mon $localport, $otherport # kill otherport on abnormal death + mon $localport, $otherport, @msg # send message on death =head1 CURRENT STATUS bin/aemp - stable. AnyEvent::MP - stable API, should work. - AnyEvent::MP::Intro - uptodate, but incomplete. - AnyEvent::MP::Kernel - mostly stable. - AnyEvent::MP::Global - stable API, protocol not yet final. - - stay tuned. + AnyEvent::MP::Intro - explains most concepts. + AnyEvent::MP::Kernel - mostly stable API. + AnyEvent::MP::Global - stable API. =head1 DESCRIPTION @@ -58,15 +55,14 @@ For an introduction to this module family, see the L manual page and the examples under F. -At the moment, this module family is a bit underdocumented. - =head1 CONCEPTS =over 4 =item port -A port is something you can send messages to (with the C function). +Not to be confused with a TCP port, a "port" is something you can send +messages to (with the C function). Ports allow you to register C handlers that can match all or just some messages. Messages send to ports will not be queued, regardless of @@ -87,7 +83,7 @@ (no listening ports). Private nodes cannot talk to other private nodes currently. -=item node ID - C<[a-za-Z0-9_\-.:]+> +=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*> A node ID is a string that uniquely identifies the node within a network. Depending on the configuration used, node IDs can look like a @@ -101,20 +97,33 @@ endpoints - binds. Currently, only standard C specifications can be used, which specify TCP ports to listen on. -=item seeds - C +=item seed nodes When a node starts, it knows nothing about the network. To teach the node about the network it first has to contact some other node within the network. This node is called a seed. -Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes -are expected to be long-running, and at least one of those should always -be available. When nodes run out of connections (e.g. due to a network -error), they try to re-establish connections to some seednodes again to -join the network. +Apart from the fact that other nodes know them as seed nodes and they have +to have fixed listening addresses, seed nodes are perfectly normal nodes - +any node can function as a seed node for others. + +In addition to discovering the network, seed nodes are also used to +maintain the network and to connect nodes that otherwise would have +trouble connecting. They form the backbone of an AnyEvent::MP network. + +Seed nodes are expected to be long-running, and at least one seed node +should always be available. They should also be relatively responsive - a +seed node that blocks for long periods will slow down everybody else. -Apart from being sued for seeding, seednodes are not special in any way - -every public node can be a seednode. +=item seeds - C + +Seeds are transport endpoint(s) (usually a hostname/IP address and a +TCP port) of nodes that should be used as seed nodes. + +The nodes listening on those endpoints are expected to be long-running, +and at least one of those should always be available. When nodes run out +of connections (e.g. due to a network error), they try to re-establish +connections to some seednodes again to join the network. =back @@ -136,12 +145,12 @@ use base "Exporter"; -our $VERSION = $AnyEvent::MP::Kernel::VERSION; +our $VERSION = 1.2; our @EXPORT = qw( NODE $NODE *SELF node_of after configure - snd rcv mon mon_guard kil reg psub spawn + snd rcv mon mon_guard kil psub spawn cal port ); @@ -163,6 +172,8 @@ Extracts and returns the node ID from a port ID or a node ID. +=item configure $profile, key => value... + =item configure key => value... Before a node can talk to other nodes on the network (i.e. enter @@ -179,12 +190,12 @@ The function first looks up a profile in the aemp configuration (see the L commandline utility). The profile name can be specified via the -named C parameter. If it is missing, then the nodename (F) will be used as profile name. +named C parameter or can simply be the first parameter). If it is +missing, then the nodename (F) will be used as profile name. The profile data is then gathered as follows: -First, all remaining key => value pairs (all of which are conviniently +First, all remaining key => value pairs (all of which are conveniently undocumented at the moment) will be interpreted as configuration data. Then they will be overwritten by any values specified in the global default configuration (see the F utility), then the chain of @@ -218,7 +229,7 @@ =back -Example: become a distributed node using the locla node name as profile. +Example: become a distributed node using the local node name as profile. This should be the most common form of invocation for "daemon"-type nodes. configure @@ -233,7 +244,7 @@ customary for aemp). # use the aemp commandline utility - # aemp profile seed setnodeid anon/ setbinds '*:4040' + # aemp profile seed nodeid anon/ binds '*:4040' # then use it configure profile => "seed"; @@ -374,9 +385,9 @@ sub rcv($@) { my $port = shift; - my ($noderef, $portid) = split /#/, $port, 2; + my ($nodeid, $portid) = split /#/, $port, 2; - $NODE{$noderef} == $NODE{""} + $NODE{$nodeid} == $NODE{""} or Carp::croak "$port: rcv can only be called on local ports, caught"; while (@_) { @@ -477,24 +488,13 @@ messages to it were lost, and optionally return a guard that can be used to stop monitoring again. -C effectively guarantees that, in the absence of hardware failures, -after starting the monitor, either all messages sent to the port will -arrive, or the monitoring action will be invoked after possible message -loss has been detected. No messages will be lost "in between" (after -the first lost message no further messages will be received by the -port). After the monitoring action was invoked, further messages might get -delivered again. - -Note that monitoring-actions are one-shot: once messages are lost (and a -monitoring alert was raised), they are removed and will not trigger again. - In the first form (callback), the callback is simply called with any number of C<@reason> elements (no @reason means that the port was deleted "normally"). Note also that I<< the callback B never die >>, so use C if unsure. In the second form (another port given), the other port (C<$rcvport>) -will be C'ed with C<@reason>, iff a @reason was specified, i.e. on +will be C'ed with C<@reason>, if 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. @@ -504,13 +504,33 @@ In the last form (message), a message of the form C<@msg, @reason> will be C. +Monitoring-actions are one-shot: once messages are lost (and a monitoring +alert was raised), they are removed and will not trigger again. + As a rule of thumb, monitoring requests should always monitor a port from a local port (or callback). The reason is that kill messages might get lost, just like any other message. Another less obvious reason is that -even monitoring requests can get lost (for exmaple, when the connection +even monitoring requests can get lost (for example, when the connection to the other node goes down permanently). When monitoring a port locally these problems do not exist. +C effectively guarantees that, in the absence of hardware failures, +after starting the monitor, either all messages sent to the port will +arrive, or the monitoring action will be invoked after possible message +loss has been detected. No messages will be lost "in between" (after +the first lost message no further messages will be received by the +port). After the monitoring action was invoked, further messages might get +delivered again. + +Inter-host-connection timeouts and monitoring depend on the transport +used. The only transport currently implemented is TCP, and AnyEvent::MP +relies on TCP to detect node-downs (this can take 10-15 minutes on a +non-idle connection, and usually around two hours for idle connections). + +This means that monitoring is good for program errors and cleaning up +stuff eventually, but they are no replacement for a timeout when you need +to ensure some maximum latency. + Example: call a given callback when C<$port> is killed. mon $port, sub { warn "port died because of <@_>\n" }; @@ -526,9 +546,9 @@ =cut sub mon { - my ($noderef, $port) = split /#/, shift, 2; + my ($nodeid, $port) = split /#/, shift, 2; - my $node = $NODE{$noderef} || add_node $noderef; + my $node = $NODE{$nodeid} || add_node $nodeid; my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; @@ -547,7 +567,7 @@ $node->monitor ($port, $cb); defined wantarray - and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } + and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) }) } =item $guard = mon_guard $port, $ref, $ref... @@ -614,13 +634,19 @@ exists or it runs out of package names. The init function is then called with the newly-created port as context -object (C<$SELF>) and the C<@initdata> values as arguments. +object (C<$SELF>) and the C<@initdata> values as arguments. It I +call one of the C functions to set callbacks on C<$SELF>, otherwise +the port might not get created. A common idiom is to pass a local port, immediately monitor the spawned port, and in the remote init function, immediately monitor the passed local port. This two-way monitoring ensures that both ports get cleaned up when there is a problem. +C guarantees that the C<$initfunc> has no visible effects on the +caller before C returns (by delaying invocation when spawn is +called for the local node). + Example: spawn a chat server port on C<$othernode>. # this node, executed from within a port context: @@ -644,6 +670,7 @@ my $port = shift; my $init = shift; + # rcv will create the actual port local $SELF = "$NODE#$port"; eval { &{ load_func $init } @@ -652,16 +679,16 @@ } sub spawn(@) { - my ($noderef, undef) = split /#/, shift, 2; + my ($nodeid, undef) = split /#/, shift, 2; my $id = "$RUNIQ." . $ID++; $_[0] =~ /::/ or Carp::croak "spawn init function must be a fully-qualified name, caught"; - snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; + snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_; - "$noderef#$id" + "$nodeid#$id" } =item after $timeout, @msg @@ -688,6 +715,58 @@ }; } +=item cal $port, @msg, $callback[, $timeout] + +A simple form of RPC - sends a message to the given C<$port> with the +given contents (C<@msg>), but adds a reply port to the message. + +The reply port is created temporarily just for the purpose of receiving +the reply, and will be Ced when no longer needed. + +A reply message sent to the port is passed to the C<$callback> as-is. + +If an optional time-out (in seconds) is given and it is not C, +then the callback will be called without any arguments after the time-out +elapsed and the port is Ced. + +If no time-out is given (or it is C), then the local port will +monitor the remote port instead, so it eventually gets cleaned-up. + +Currently this function returns the temporary port, but this "feature" +might go in future versions unless you can make a convincing case that +this is indeed useful for something. + +=cut + +sub cal(@) { + my $timeout = ref $_[-1] ? undef : pop; + my $cb = pop; + + my $port = port { + undef $timeout; + kil $SELF; + &$cb; + }; + + if (defined $timeout) { + $timeout = AE::timer $timeout, 0, sub { + undef $timeout; + kil $port; + $cb->(); + }; + } else { + mon $_[0], sub { + kil $port; + $cb->(); + }; + } + + push @_, $port; + &snd; + + $port +} + =back =head1 AnyEvent::MP vs. Distributed Erlang @@ -697,10 +776,10 @@ programming techniques employed by Erlang apply to AnyEvent::MP. Here is a sample: - http://www.Erlang.se/doc/programming_rules.shtml - http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 - http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6 - http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 + http://www.erlang.se/doc/programming_rules.shtml + http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 + http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6 + http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 Despite the similarities, there are also some important differences: @@ -710,7 +789,8 @@ Erlang relies on special naming and DNS to work everywhere in the same way. AEMP relies on each node somehow knowing its own address(es) (e.g. by -configuraiton or DNS), but will otherwise discover other odes itself. +configuration or DNS), and possibly the addresses of some seed nodes, but +will otherwise discover other nodes (and their IDs) itself. =item * Erlang has a "remote ports are like local ports" philosophy, AEMP uses "local ports are like remote ports". @@ -733,7 +813,7 @@ needs a queue. AEMP is event based, queuing messages would serve no useful purpose. For the same reason the pattern-matching abilities of AnyEvent::MP are more limited, as there is little need to be able to -filter messages without dequeing them. +filter messages without dequeuing them. (But see L for a more Erlang-like process model on top of AEMP). @@ -745,9 +825,9 @@ =item * Erlang suffers from silent message loss, AEMP does not. -Erlang makes few guarantees on messages delivery - messages can get lost -without any of the processes realising it (i.e. you send messages a, b, -and c, and the other side only receives messages a and c). +Erlang implements few guarantees on messages delivery - messages can get +lost without any of the processes realising it (i.e. you send messages a, +b, and c, and the other side only receives messages a and c). AEMP guarantees correct ordering, and the guarantee that after one message is lost, all following ones sent to the same port are lost as well, until @@ -849,6 +929,9 @@ L - network maintainance and port groups, to find your applications. +L - simple service to display log messages from +all nodes. + L. =head1 AUTHOR