[ViewVC] Diff of: cvs/AnyEvent-MP/MP.pm

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.43 by root, Sun Aug 9 16:08:16 2009 UTC vs.
Revision 1.49 by root, Thu Aug 13 15:29:58 2009 UTC

    $NODE      # contains this node's noderef
    NODE       # returns this node's noderef
    NODE $port # returns the noderef of the port
    $SELF      # receiving/own port id in rcv callbacks
+   # initialise the node so it can send/receive messages
+   initialise_node;                  # -OR-
+   initialise_node "localhost:4040"; # -OR-
+   initialise_node "slave/", "localhost:4040"
    # ports are message endpoints
    # sending messages
    snd $port, type => data...;
    snd $port, @msg;
    snd @msg_with_first_element_being_a_port;
-   # miniports
+   # creating/using miniports
    my $miniport = port { my @msg = @_; 0 };
-   # full ports
+   # creating/using 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 };
-   # 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
+   # create a port on another node
+   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
+=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.
 Despite its simplicity, you can securely message other processes running
 For an introduction to this module family, see the L<AnyEvent::MP::Intro>
 manual page.
 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
 =over 4
 =cut
 package AnyEvent::MP;
-use AnyEvent::MP::Base;
+use AnyEvent::MP::Kernel;
 use common::sense;
 use Carp ();
 use AE ();
 use base "Exporter";
-our $VERSION = $AnyEvent::MP::Base::VERSION;
+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 spawn
 it should know the noderefs of some other nodes in the network.
 This function initialises a node - it must be called exactly once (or
 never) before calling other AnyEvent::MP functions.
-All arguments are noderefs, which can be either resolved or unresolved.
+All arguments (optionally except for the first) are noderefs, which can be
+either resolved or unresolved.
+The first argument will be looked up in the configuration database first
+(if it is C<undef> then the current nodename will be used instead) to find
+the relevant configuration profile (see L<aemp>). If none is found then
+the default configuration is used. The configuration supplies additional
+seed/master nodes and can override the actual noderef.
 There are two types of networked nodes, public nodes and slave nodes:
 =over 4
 =item public nodes
-For public nodes, C<$noderef> must either be a (possibly unresolved)
+For public nodes, C<$noderef> (supplied either directly to
-noderef, in which case it will be resolved, or C<undef> (or missing), in
+C<initialise_node> or indirectly via a profile or the nodename) must be a
-which case the noderef will be guessed.
+noderef (possibly unresolved, in which case it will be resolved).
-Afterwards, the node will bind itself on all endpoints and try to connect
+After resolving, the node will bind itself on all endpoints and try to
-to all additional C<$seednodes> that are specified. Seednodes are optional
+connect to all additional C<$seednodes> that are specified. Seednodes are
-and can be used to quickly bootstrap the node into an existing network.
+optional and can be used to quickly bootstrap the node into an existing
+network.
 =item slave nodes
-When the C<$noderef> is the special string C<slave/>, then the node will
+When the C<$noderef> (either as given or overriden by the config file)
+is the special string C<slave/>, then the node will become a slave
-become a slave node. Slave nodes cannot be contacted from outside and will
+node. Slave nodes cannot be contacted from outside and will route most of
-route most of their traffic to the master node that they attach to.
+their traffic to the master node that they attach to.
-At least one additional noderef is required: The node will try to connect
+At least one additional noderef is required (either by specifying it
-to all of them and will become a slave attached to the first node it can
+directly or because it is part of the configuration profile): The node
-successfully connect to.
+will try to connect to all of them and will become a slave attached to the
+first node it can successfully connect to.
 =back
 This function will block until all nodes have been resolved and, for slave
 nodes, until it has successfully established a connection to a master
 server.
-Example: become a public node listening on the default node.
+Example: become a public 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.
    initialise_node;
+Example: become a slave node to any of the the seednodes specified via
+C<aemp>.  This form is often used for commandline clients.
+   initialise_node "slave/";
+Example: become a slave node to any of the specified master servers. This
+form is also often used for commandline clients.
+   initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
 Example: become a public node, and try to contact some well-known master
 servers to become part of the network.
    initialise_node undef, "master1", "master2";
    initialise_node 4041;
 Example: become a public node, only visible on localhost port 4044.
-   initialise_node "locahost:4044";
+   initialise_node "localhost:4044";
-Example: become a slave node to any of the specified master servers.
-   initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
 =item $cv = resolve_node $noderef
 Takes an unresolved node reference that may contain hostnames and
 abbreviated IDs, resolves all of them and returns a resolved node
 This also saves round-trips and avoids sending messages to the wrong port
 (hard to do in Erlang).
 =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>.
 =head1 AUTHOR

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent-MP/MP.pm (file contents): Revision 1.43 by root, Sun Aug 9 16:08:16 2009 UTC vs. Revision 1.49 by root, Thu Aug 13 15:29:58 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.43 by root, Sun Aug 9 16:08:16 2009 UTC vs.
Revision 1.49 by root, Thu Aug 13 15:29:58 2009 UTC