--- AnyEvent-MP/MP.pm	2009/08/06 10:21:48	1.35
+++ AnyEvent-MP/MP.pm	2009/08/07 23:21:48	1.39
@@ -10,24 +10,31 @@
    NODE       # returns this node's noderef
    NODE $port # returns the noderef of the port
 
+   $SELF      # receiving/own port id in rcv callbacks
+
+   # ports are message endpoints
+
+   # sending messages
    snd $port, type => data...;
+   snd $port, @msg;
+   snd @msg_with_first_element_being_a_port;
 
-   $SELF      # receiving/own port id in rcv callbacks
+   # miniports
+   my $miniport = port { my @msg = @_; 0 };
 
-   rcv $port, smartmatch => $cb->($port, @msg);
+   # full ports
+   my $port = port;
+   rcv $port, smartmatch => $cb->(@msg);
+   rcv $port, ping => sub { snd $_[0], "pong"; 0 };
+   rcv $port, pong => sub { warn "pong received\n"; 0 };
 
-   # examples:
-   rcv $port2, ping => sub { snd $_[0], "pong"; 0 };
-   rcv $port1, pong => sub { warn "pong received\n" };
-   snd $port2, ping => $port1;
+   # remote ports
+   my $port = spawn $node, $initfunc, @initdata;
 
    # more, smarter, matches (_any_ is exported by this module)
    rcv $port, [child_died => $pid] => sub { ...
    rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
 
-   # linking two ports, so they both crash together
-   lnk $port1, $port2;
-
    # monitoring
    mon $port, $cb->(@msg)      # callback is invoked on death
    mon $port, $otherport       # kill otherport on abnormal death
@@ -114,7 +121,7 @@
 our @EXPORT = qw(
    NODE $NODE *SELF node_of _any_
    resolve_node initialise_node
-   snd rcv mon kil reg psub
+   snd rcv mon kil reg psub spawn
    port
 );
 
@@ -307,8 +314,10 @@
 
 =item reg $port, $name
 
-Registers the given port under the name C<$name>. If the name already
-exists it is replaced.
+=item reg $name
+
+Registers the given port (or C<$SELF><<< if missing) under the name
+C<$name>. If the name already exists it is replaced.
 
 A port can only be registered under one well known name.
 
@@ -317,9 +326,9 @@
 =cut
 
 sub reg(@) {
-   my ($port, $name) = @_;
+   my $port = @_ > 1 ? shift : $SELF || Carp::croak 'reg: called with one argument only, but $SELF not set,';
 
-   $REG{$name} = $port;
+   $REG{$_[0]} = $port;
 }
 
 =item rcv $port, $callback->(@msg)
@@ -334,7 +343,7 @@
 =item rcv $port, [$smartmatch...] => $callback->(@msg), ...
 
 Register callbacks to be called on matching messages on the given full
-port (after converting it to one if required).
+port (after converting it to one if required) and return the 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
@@ -343,7 +352,7 @@
 The global C<$SELF> (exported by this module) contains C<$port> while
 executing the callback.
 
-Runtime errors wdurign callback execution will result in the port being
+Runtime errors during callback execution will result in the port being
 C<kil>ed.
 
 If the match is an array reference, then it will be matched against the
@@ -357,6 +366,22 @@
 element is a string identifying the message. The one-string-only match is
 also the most efficient match (by far).
 
+Example: create a port and bind receivers on it in one go.
+
+  my $port = rcv port,
+     msg1 => sub { ...; 0 },
+     msg2 => sub { ...; 0 },
+  ;
+
+Example: create a port, bind receivers and send it in a message elsewhere
+in one go:
+
+   snd $otherport, reply =>
+      rcv port,
+         msg1 => sub { ...; 0 },
+         ...
+   ;
+
 =cut
 
 sub rcv($@) {
@@ -472,22 +497,37 @@
 
 =item $guard = mon $port, $cb->(@reason)
 
-=item $guard = mon $port, $otherport
+=item $guard = mon $port, $rcvport
+
+=item $guard = mon $port
 
-=item $guard = mon $port, $otherport, @msg
+=item $guard = mon $port, $rcvport, @msg
 
-Monitor the given port and do something when the port is killed.
+Monitor the given port and do something when the port is killed, and
+optionally return a guard that can be used to stop monitoring again.
 
-In the first form, the callback is simply called with any number
-of C<@reason> elements (no @reason means that the port was deleted
+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<must> never die >>, so use
 C<eval> if unsure.
 
-In the second form, the other port will be C<kil>'ed with C<@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 C<@msg, @reason> will be C<snd>.
+In the second form (another port given), the other port (C<$rcvport)
+will be C<kil>'ed with C<@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.
+
+The third form (kill self) is the same as the second form, except that
+C<$rvport> defaults to C<$SELF>.
+
+In the last form (message), a message of the form C<@msg, @reason> will be
+C<snd>.
+
+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
+to the other node goes down permanently). When monitoring a port locally
+these problems do not exist.
 
 Example: call a given callback when C<$port> is killed.
 
@@ -495,9 +535,9 @@
 
 Example: kill ourselves when C<$port> is killed abnormally.
 
-   mon $port, $self;
+   mon $port;
 
-Example: send us a restart message another C<$port> is killed.
+Example: send us a restart message when another C<$port> is killed.
 
    mon $port, $self => "restart";
 
@@ -508,12 +548,12 @@
 
    my $node = $NODE{$noderef} || add_node $noderef;
 
-   my $cb = shift;
+   my $cb = @_ ? $_[0] : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
 
    unless (ref $cb) {
       if (@_) {
          # send a kill info message
-         my (@msg) = ($cb, @_);
+         my (@msg) = @_;
          $cb = sub { snd @msg, @_ };
       } else {
          # simply kill other port
@@ -549,19 +589,11 @@
 sub mon_guard {
    my ($port, @refs) = @_;
 
+   #TODO: mon-less form?
+
    mon $port, sub { 0 && @refs }
 }
 
-=item 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.
-
 =item kil $port[, @reason]
 
 Kill the specified port with the given C<@reason>.
@@ -578,6 +610,76 @@
 Transport/communication errors are reported as C<< transport_error =>
 $message >>.
 
+=cut
+
+=item $port = spawn $node, $initfunc[, @initdata]
+
+Creates a port on the node C<$node> (which can also be a port ID, in which
+case it's the node where that port resides).
+
+The port ID of the newly created port is return immediately, and it is
+permissible to immediately start sending messages or monitor the port.
+
+After the port has been created, the init function is
+called. This function must be a fully-qualified function name
+(e.g. C<MyApp::Chat::Server::init>).
+
+If the function doesn't exist, then the node tries to C<require>
+the package, then the package above the package and so on (e.g.
+C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
+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.
+
+A common idiom is to pass your own port, monitor the spawned port, and
+in the init function, monitor the original port. This two-way monitoring
+ensures that both ports get cleaned up when there is a problem.
+
+Example: spawn a chat server port on C<$othernode>.
+
+   # this node, executed from within a port context:
+   my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
+   mon $server;
+
+   # init function on C<$othernode>
+   sub connect {
+      my ($srcport) = @_;
+
+      mon $srcport;
+
+      rcv $SELF, sub {
+         ...
+      };
+   }
+
+=cut
+
+sub _spawn {
+   my $port = shift;
+   my $init = shift;
+
+   local $SELF = "$NODE#$port";
+   eval {
+      &{ load_func $init }
+   };
+   _self_die if $@;
+}
+
+sub spawn(@) {
+   my ($noderef, undef) = split /#/, shift, 2;
+
+   my $id = "$RUNIQ." . $ID++;
+
+   $_[0] =~ /::/
+      or Carp::croak "spawn init function must be a fully-qualified name, caught";
+
+   ($NODE{$noderef} || add_node $noderef)
+      ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
+
+   "$noderef#$id"
+}
+
 =back
 
 =head1 NODE MESSAGES
@@ -719,12 +821,19 @@
 Erlang, as one can choose between automatic kill, exit message or callback
 on a per-process basis.
 
-=item * Erlang has different semantics for monitoring and linking, AEMP has the same.
+=item * Erlang tries to hide remote/local connections, AEMP does not.
 
 Monitoring in Erlang is not an indicator of process death/crashes,
-as linking is (except linking is unreliable in Erlang). In AEMP, the
-semantics of monitoring and linking are identical, linking is simply
-two-way monitoring with automatic kill.
+as linking is (except linking is unreliable in Erlang).
+
+In AEMP, you don't "look up" registered port names or send to named ports
+that might or might not be persistent. Instead, you normally spawn a port
+on the remote node. The init function monitors the you, and you monitor
+the remote port. Since both monitors are local to the node, they are much
+more reliable.
+
+This also saves round-trips and avoids sending messages to the wrong port
+(hard to do in Erlang).
 
 =back