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

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.38 by root, Mon Aug 31 18:45:05 2009 UTC vs.
Revision 1.39 by root, Mon Aug 31 22:14:43 2009 UTC

 The next sections will explain the API of L<AnyEvent::MP> by going through
 a few simple examples. Later some more complex idioms are introduced,
 which are hopefully useful to solve some real world problems.
-=head1 Passing Your First Message
+=head2 Passing Your First Message
 As a start lets have a look at the messaging API. The following example
 is just a demo to show the basic elements of message passing with
 L<AnyEvent::MP>.
 Passing messages inside just one process is boring. Before we can move on
 and do interprocess message passing we first have to make sure some things
 have been set up correctly for our nodes to talk to each other.
-=head1 System Requirements and System Setup
+=head2 System Requirements and System Setup
 Before we can start with real IPC we have to make sure some things work on
 your system.
 First we have to setup a I<shared secret>: for two L<AnyEvent::MP>
    warn "server ready.\n";
    AnyEvent->condvar->recv;
-It starts not much different, except that this time, we register the node
+It starts out not much different then the previous example, except that
-port and not any special port - the clients only want to know which node
+this time, we register the node port in the global group and not any port
-the server should be running, and in fact, they could also sue some kind
+we created - the clients only want to know which node the server should be
-of election mechanism or similar.
+running on. In fact, they could also use some kind of election mechanism,
+to find the node with lowest load or something like that.
-The interesting change is that no port is created - the server is all
+The more interesting change is that indeed no server port is created -
-code, and does nothing. All it does is define a function C<client_connect>
+the server consists only of code, and "does" nothing by itself. All it
-that expects a client port and a nick as arguments. It then monitors the
+does is define a function C<client_connect>, which expects a client port
-client port and binds a receive callback on C<$SELF> that expects messages
+and a nick name as arguments. It then monitors the client port and binds
+a receive callback on C<$SELF>, which expects messages that in turn are
-to broadcast to all clients.
+broadcast to all clients.
 The two C<mon> calls are a bit tricky - the first C<mon> is a shorthand
 for C<mon $client, $SELF>. The second does the normal "client has gone
 away" clean-up action. Both could actually be rolled into one C<mon>
 action.
-C<$SELF> is a good hint that something interetsing is going on. And
+C<$SELF> is a good hint that something interesting is going on. And
-indeed, when looking at the client, there is a new function, C<spawn>:
+indeed, when looking at the client code, there is a new function,
+C<spawn>:
    use common::sense;
    use AnyEvent::MP;
    use AnyEvent::MP::Global;
    print "> ";
    AnyEvent->condvar->recv;
 The client is quite similar to the previous one, but instead of contacting
-the server port (which no longer exists), it C<spawn>s a new port on the
+the server I<port> (which no longer exists), it C<spawn>s (creates) a new
-server I<node>:
+the server I<port on node>:
       $server = spawn $servernodes->[0], "::client_connect", $client, $nick;
       mon $server, $client;
-And of course immediately monitors it. The C<spawn> function creates a new
+And of course the first thing after creating it is monitoring it.
-port on a remote node and returns its port ID. After creating the port it
-calls a function on the remote node, passing any remaining arguments to
-it, and - most importantly - within the context of the new port. The init
-function can reside in a module (actually it normally I<should> reside
-in a module) - AnyEvent::MP will automatically load the module if the
-function isn't defined.
+The C<spawn> function creates a new port on a remote node and returns
+its port ID. After creating the port it calls a function on the remote
+node, passing any remaining arguments to it, and - most importantly -
+executes the function within the context of the new port, so it can be
+manipulated by refering to C<$SELF>. The init function can reside in a
+module (actually it normally I<should> reside in a module) - AnyEvent::MP
+will automatically load the module if the function isn't defined.
-The C<spawn> function returns immediately, which means you can immediately
+The C<spawn> function returns immediately, which means you can instantly
 send messages to the port, long before the remote node has even heard
 of our request to create a port on it. In fact, the remote node might
 not even be running. Despite these troubling facts, everything should
 work just fine: if the node isn't running (or the init function throws an
 exception), then the monitor will trigger because the port doesn't exist.
 If the spawn message gets delivered, but the monitoring message is not
-because of network problems (monitoring, after all, is implemented by
+because of network problems (extremely unlikely, but monitoring, after
-passing a message, and messages can get lost), then this connection loss
+all, is implemented by passing a message, and messages can get lost), then
-will eventually trigger the monitoring action. On the remote node (which
+this connection loss will eventually trigger the monitoring action. On the
-reciprocally monitors the client) the port will also be cleaned up on
+remote node (which in return monitors the client) the port will also be
-connection loss. When the node comes up and our monitoring message can be
+cleaned up on connection loss. When the remote node comes up again and our
-delivered it will instantly fail because the port has been cleaned up in
+monitoring message can be delivered, it will instantly fail because the
-the meantime.
+port has been cleaned up in the meantime.
 If your head is spinning by now, that's fine - just keep in mind, after
-creating a port, monitor "the other side" from it, and all will be cleaned
+creating a port, monitor it on the local node, and monitor "the other
-up just fine.
+side" from the remote node, and all will be cleaned up just fine.
 =head2 Services
 Above it was mentioned that C<spawn> automatically loads modules, and this
 can be exploited in various ways.
 AnyEvent::MP::Global), then you can configure this service statically:
    aemp profile mysrvnode services mymod::service::
    aemp run profile mysrvnode
-And the module will automatically be started in the node, as specifying a
+And the module will automatically be loaded in the node, as specifying a
 module name (with C<::>-suffix) will simply load the module, which is then
 free to do whatever it wants.
 Of course, you can also do it in the much more standard way by writing
 a module (e.g. C<BK::Backend::IRC>), installing it as part of a module
 distribution and then configure nodes, for example, if I want to run the
 Bummskraut IRC backend on a machine named "ruth", I could do this:
    aemp profile ruth addservice BK::Backend::IRC::
-And any F<aemp run> on that host will automaticlaly have the bummskraut
+And any F<aemp run> on that host will automaticllay have the bummskraut
 irc backend running.
 That's plenty of possibilities you can use - it's all up to you how you
 structure your application.

Diff Legend

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

Comparing AnyEvent-MP/MP/Intro.pod (file contents): Revision 1.38 by root, Mon Aug 31 18:45:05 2009 UTC vs. Revision 1.39 by root, Mon Aug 31 22:14:43 2009 UTC

Diff Legend

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.38 by root, Mon Aug 31 18:45:05 2009 UTC vs.
Revision 1.39 by root, Mon Aug 31 22:14:43 2009 UTC