--- AnyEvent-MP/MP.pm 2009/09/03 20:16:36 1.78 +++ AnyEvent-MP/MP.pm 2009/09/22 14:14:29 1.93 @@ -1,6 +1,6 @@ =head1 NAME -AnyEvent::MP - multi-processing/message-passing framework +AnyEvent::MP - erlang-style multi-processing/message-passing framework =head1 SYNOPSIS @@ -33,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 - explains most concepts. - AnyEvent::MP::Kernel - mostly stable. - AnyEvent::MP::Global - stable API, protocol not yet final. - - stay tuned. + AnyEvent::MP::Kernel - mostly stable API. + AnyEvent::MP::Global - stable API. =head1 DESCRIPTION @@ -63,7 +61,8 @@ =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 @@ -84,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 @@ -98,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. + +=item seeds - C + +Seeds are transport endpoint(s) (usually a hostname/IP address and a +TCP port) of nodes thta should be used as seed nodes. -Apart from being sued for seeding, seednodes are not special in any way - -every public node can be a seednode. +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 @@ -138,7 +150,7 @@ 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 ); @@ -217,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 @@ -476,17 +488,6 @@ 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 @@ -503,6 +504,9 @@ 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 @@ -510,6 +514,23 @@ 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 conenctions). + +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" }; @@ -546,6 +567,7 @@ $node->monitor ($port, $cb); defined wantarray + and $cb += 0 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } } @@ -613,13 +635,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: @@ -643,6 +671,7 @@ my $port = shift; my $init = shift; + # rcv will create the actual port local $SELF = "$NODE#$port"; eval { &{ load_func $init } @@ -687,6 +716,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, 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 @@ -848,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