--- AnyEvent-MP/MP.pm 2009/08/31 13:18:06 1.75 +++ AnyEvent-MP/MP.pm 2009/09/07 18:42:09 1.82 @@ -41,11 +41,11 @@ bin/aemp - stable. AnyEvent::MP - stable API, should work. - AnyEvent::MP::Intro - uptodate, but incomplete. + AnyEvent::MP::Intro - explains most concepts. AnyEvent::MP::Kernel - mostly stable. - AnyEvent::MP::Global - stable API, protocol not yet final. + AnyEvent::MP::Global - stable but incomplete, protocol not yet final. - stay tuned. +stay tuned. =head1 DESCRIPTION @@ -57,15 +57,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 @@ -162,6 +161,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 @@ -178,12 +179,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 @@ -476,24 +477,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. @@ -503,13 +493,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 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" }; @@ -613,13 +623,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 +659,7 @@ my $port = shift; my $init = shift; + # rcv will create the actual port local $SELF = "$NODE#$port"; eval { &{ load_func $init } @@ -709,7 +726,7 @@ 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), but will otherwise discover other odes itself. =item * Erlang has a "remote ports are like local ports" philosophy, AEMP uses "local ports are like remote ports". @@ -732,7 +749,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). @@ -848,6 +865,9 @@ L - network maintainance and port groups, to find your applications. +L - simple service to display log messages from +all nodes. + L. =head1 AUTHOR