--- AnyEvent-MP/MP.pm	2009/08/30 19:52:56	1.71
+++ AnyEvent-MP/MP.pm	2009/08/31 11:11:27	1.74
@@ -13,7 +13,7 @@
    $SELF      # receiving/own port id in rcv callbacks
 
    # initialise the node so it can send/receive messages
-   initialise_node;
+   configure;
 
    # ports are message endpoints
 
@@ -23,12 +23,12 @@
    snd @msg_with_first_element_being_a_port;
 
    # creating/using ports, the simple way
-   my $simple_port = port { my @msg = @_; 0 };
+   my $simple_port = port { my @msg = @_ };
 
    # creating/using ports, tagged message matching
    my $port = port;
-   rcv $port, ping => sub { snd $_[0], "pong"; 0 };
-   rcv $port, pong => sub { warn "pong received\n"; 0 };
+   rcv $port, ping => sub { snd $_[0], "pong" };
+   rcv $port, pong => sub { warn "pong received\n" };
 
    # create a port on another node
    my $port = spawn $node, $initfunc, @initdata;
@@ -140,7 +140,7 @@
 
 our @EXPORT = qw(
    NODE $NODE *SELF node_of after
-   initialise_node
+   configure
    snd rcv mon mon_guard kil reg psub spawn
    port
 );
@@ -157,39 +157,49 @@
 
 The C<NODE> function returns, and the C<$NODE> variable contains, the node
 ID of the node running in the current process. This value is initialised by
-a call to C<initialise_node>.
+a call to C<configure>.
 
 =item $nodeid = node_of $port
 
 Extracts and returns the node ID from a port ID or a node ID.
 
-=item initialise_node $profile_name, key => value...
+=item configure key => value...
 
 Before a node can talk to other nodes on the network (i.e. enter
-"distributed mode") it has to initialise itself - the minimum a node needs
+"distributed mode") it has to configure itself - the minimum a node needs
 to know is its own name, and optionally it should know the addresses of
 some other nodes in the network to discover other nodes.
 
-This function initialises a node - it must be called exactly once (or
+This function configures a node - it must be called exactly once (or
 never) before calling other AnyEvent::MP functions.
 
-The first argument is a profile name. If it is C<undef> or missing, then
-the current nodename will be used instead (i.e. F<uname -n>).
+=over 4
+
+=item step 1, gathering configuration from profiles
+
+The function first looks up a profile in the aemp configuration (see the
+L<aemp> commandline utility). The profile name can be specified via the
+named C<profile> parameter. If it is missing, then the nodename (F<uname
+-n>) will be used as profile name.
 
-The function first looks up the profile in the aemp configuration (see the
-L<aemp> commandline utility). the profile is calculated as follows:
+The profile data is then gathered as follows:
 
 First, all remaining key => value pairs (all of which are conviniently
-undocumented at the moment) will be used. Then they will be overwritten by
-any values specified in the global default configuration (see the F<aemp>
-utility), then the chain of profiles selected, if any. That means that
-the values specified in the profile have highest priority and the values
-specified via C<initialise_node> have lowest priority.
+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<aemp> utility), then the chain of
+profiles chosen by the profile name (and any C<parent> attributes).
+
+That means that the values specified in the profile have highest priority
+and the values specified directly via C<configure> have lowest priority,
+and can only be used to specify defaults.
 
 If the profile specifies a node ID, then this will become the node ID of
 this process. If not, then the profile name will be used as node ID. The
 special node ID of C<anon/> will be replaced by a random node ID.
 
+=item step 2, bind listener sockets
+
 The next step is to look up the binds in the profile, followed by binding
 aemp protocol listeners on all binds specified (it is possible and valid
 to have no binds, meaning that the node cannot be contacted form the
@@ -197,28 +207,42 @@
 binds, but it can still talk to all "normal" nodes).
 
 If the profile does not specify a binds list, then a default of C<*> is
-used.
+used, meaning the node will bind on a dynamically-assigned port on every
+local IP address it finds.
+
+=item step 3, connect to seed nodes
 
-Lastly, the seeds list from the profile is passed to the
+As the last step, the seeds list from the profile is passed to the
 L<AnyEvent::MP::Global> module, which will then use it to keep
-connectivity with at least on of those seed nodes at any point in time.
+connectivity with at least one node at any point in time.
 
-Example: become a distributed node listening on the guessed noderef, or
-the one specified via C<aemp> for the current node. This should be the
-most common form of invocation for "daemon"-type nodes.
+=back
+
+Example: become a distributed node using the locla node name as profile.
+This should be the most common form of invocation for "daemon"-type nodes.
 
-   initialise_node;
+   configure
 
 Example: become an anonymous node. This form is often used for commandline
 clients.
 
-   initialise_node "anon/";
+   configure nodeid => "anon/";
+
+Example: configure a node using a profile called seed, which si suitable
+for a seed node as it binds on all local addresses on a fixed port (4040,
+customary for aemp).
+
+   # use the aemp commandline utility
+   # aemp profile seed nodeid anon/ binds '*:4040'
+
+   # then use it
+   configure profile => "seed";
 
-Example: become a distributed node. If there is no profile of the given
-name, or no binds list was specified, resolve C<localhost:4044> and bind
-on the resulting addresses.
+   # or simply use aemp from the shell again:
+   # aemp run profile seed
 
-   initialise_node "localhost:4044";
+   # or provide a nicer-to-remember nodeid
+   # aemp run profile seed nodeid "$(hostname)"
 
 =item $SELF