--- AnyEvent-MP/MP.pm	2009/08/07 16:47:23	1.37
+++ AnyEvent-MP/MP.pm	2009/08/13 01:57:10	1.47
@@ -10,16 +10,26 @@
    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 { ...
@@ -30,6 +40,15 @@
    mon $port, $otherport       # kill otherport on abnormal death
    mon $port, $otherport, @msg # send message on death
 
+=head1 CURRENT STATUS
+
+   AnyEvent::MP            - stable API, should work
+   AnyEvent::MP::Intro     - outdated
+   AnyEvent::MP::Kernel    - WIP
+   AnyEvent::MP::Transport - mostly stable
+
+   stay tuned.
+
 =head1 DESCRIPTION
 
 This module (-family) implements a simple message passing framework.
@@ -42,7 +61,7 @@
 
 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.
+stay tuned!
 
 =head1 CONCEPTS
 
@@ -97,7 +116,7 @@
 
 package AnyEvent::MP;
 
-use AnyEvent::MP::Base;
+use AnyEvent::MP::Kernel;
 
 use common::sense;
 
@@ -107,11 +126,12 @@
 
 use base "Exporter";
 
-our $VERSION = '0.1';
+our $VERSION = $AnyEvent::MP::Kernel::VERSION;
+
 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
 );
 
@@ -342,7 +362,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
@@ -493,15 +513,24 @@
 
 =item $guard = mon $port, $rcvport, @msg
 
-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.
+Monitor the given port and do something when the port is killed or
+messages to it were lost, and optionally return a guard that can be used
+to stop monitoring again.
+
+C<mon> effectively guarantees that, in the absence of hardware failures,
+that 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.
 
 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 (another port given), the other port (C<$rcvport)
+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.
@@ -538,12 +567,12 @@
 
    my $node = $NODE{$noderef} || add_node $noderef;
 
-   my $cb = @_ ? $_[0] : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
+   my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
 
    unless (ref $cb) {
       if (@_) {
          # send a kill info message
-         my (@msg) = @_;
+         my (@msg) = ($cb, @_);
          $cb = sub { snd @msg, @_ };
       } else {
          # simply kill other port
@@ -600,6 +629,77 @@
 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>). To specify a function in the main
+program, use C<::name>.
+
+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
@@ -757,6 +857,41 @@
 
 =back
 
+=head1 RATIONALE
+
+=over 4
+
+=item Why strings for ports and noderefs, why not objects?
+
+We considered "objects", but found that the actual number of methods
+thatc an be called are very low. Since port IDs and noderefs travel over
+the network frequently, the serialising/deserialising would add lots of
+overhead, as well as having to keep a proxy object.
+
+Strings can easily be printed, easily serialised etc. and need no special
+procedures to be "valid".
+
+And a a miniport consists of a single closure stored in a global hash - it
+can't become much cheaper.
+
+=item Why favour JSON, why not real serialising format such as Storable?
+
+In fact, any AnyEvent::MP node will happily accept Storable as framing
+format, but currently there is no way to make a node use Storable by
+default.
+
+The default framing protocol is JSON because a) JSON::XS is many times
+faster for small messages and b) most importantly, after years of
+experience we found that object serialisation is causing more problems
+than it gains: Just like function calls, objects simply do not travel
+easily over the network, mostly because they will always be a copy, so you
+always have to re-think your design.
+
+Keeping your messages simple, concentrating on data structures rather than
+objects, will keep your messages clean, tidy and efficient.
+
+=back
+
 =head1 SEE ALSO
 
 L<AnyEvent>.