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

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC vs.
Revision 1.52 by root, Wed Mar 21 01:14:12 2012 UTC

 The C<peval> function temporarily replaces C<$SELF> by the given C<$port>
 and then executes the given sub in a port context.
 =head3 Network Errors and the AEMP Guarantee
-I mentioned another important source of monitoring failures: network
+Earlier we mentioned another important source of monitoring failures:
-problems. When a node loses connection to another node, it will invoke all
+network problems. When a node loses connection to another node, it will
-monitoring actions as if the port was killed, even if it is possible that
+invoke all monitoring actions, just as if the port was killed, I<even if
-the port is still happily alive on another node (not being able to talk to
+it is possible that the port is still happily alive on another node> (not
-a node means we have no clue what's going on with it, it could be crashed,
+being able to talk to a node means we have no clue what's going on with
-but also still running without knowing we lost the connection).
+it, it could be crashed, but also still running without knowing we lost
+the connection).
-So another way to view monitors is "notify me when some of my messages
+So another way to view monitors is: "notify me when some of my messages
 couldn't be delivered". AEMP has a guarantee about message delivery to a
 port:  After starting a monitor, any message sent to a port will either
 be delivered, or, when it is lost, any further messages will also be lost
 until the monitoring action is invoked. After that, further messages
 I<might> get delivered again.
 This doesn't sound like a very big guarantee, but it is kind of the best
-you can get while staying sane: Specifically, it means that there will
+you can get while staying sane: Specifically, it means that there will be
-be no "holes" in the message sequence: all messages sent are delivered
+no "holes" in the message sequence: all messages sent are delivered in
-in order, without any missing in between, and when some were lost, you
+order, without any of them missing in between, and when some were lost,
-I<will> be notified of that, so you can take recovery action.
+you I<will> be notified of that, so you can take recovery action.
 And, obviously, the guarantee only works in the presence of
 correctly-working hardware, and no relevant bugs inside AEMP itself.
 =head3 Supervising
 OK, so how is this crashing-everything-stuff going to make applications
-I<more> stable? Well, in fact, the goal is not really to make them more
+I<more> stable? Well, in fact, the goal is not really to make them
-stable, but to make them more resilient against actual errors and
+more stable, but to make them more resilient against actual errors
-crashes. And this is not done by crashing I<everything>, but by crashing
+and crashes. And this is not done by crashing I<everything>, but by
-everything except a I<supervisor>.
+crashing everything except a I<supervisor> that then cleans up and sgtarts
+everything again.
 A supervisor is simply some code that ensures that an application (or a
 part of it) is running, and if it crashes, is restarted properly. That is,
 it supervises a service by starting and restarting it, as necessary.
    };
 And finally, the server registers itself in the server group, so that
 clients can find it:
-   grp_reg eg_chat_server => $server;
+   db_set eg_chat_server => $server;
 Well, well... and where is this supervisor stuff? Well... we cheated,
 it's not there. To not overcomplicate the example, we only put it into
 the..... CLIENT!
 expected as the only command line argument) in C<$nick>, for further
 usage.
 The next relevant thing is... finally... the supervisor:
-#todo#d#
    sub server_connect {
-      my $servernodes = grp_get "eg_chat_server"
+      my $db_mon;
-         or return after 1, \&server_connect;
+      $db_mon = db_mon eg_chat_server => sub {
+         return unless %{ $_[0] };
+         undef $db_mon; # stop monitoring
-This looks up the server in the C<eg_chat_server> global group. If it
+This monitors the C<eg_chat_server> database family. It waits until a
-cannot find it (which is likely when the node is just starting up),
+chat server becomes available. When that happens, it "connects" to it
-it will wait a second and then retry. This "wait a bit and retry"
+by creating a client port that receives and prints chat messages, and
-is an important pattern, as distributed programming means lots of
+monitoring it:
-things are going on asynchronously. In practise, one should use a more
-intelligent algorithm, to possibly warn after an excessive number of
-retries. Hopefully future versions of AnyEvent::MP will offer some
-predefined supervisors, for now you will have to code it on your own.
-Next it creates a local port for the server to send messages to, and
-monitors it. When the port is killed, it will print "disconnected" and
-tell the supervisor function to retry again.
       $client = port { print "\r  \r@_\n> " };
       mon $client, sub {
          print "\rdisconnected @_\n";
          &server_connect;
       };
+If the client port dies (for whatever reason), the "supervisor" will start
+looking for a server again - the semantics of C<db_mon> ensure that it
+will immediately find it if there is a server port.
-Then everything is ready: the client will send a C<join> message with it's
+After this, everything is ready: the client will send a C<join> message
-local port to the server, and start monitoring it:
+with its local port to the server, and start monitoring it:
-      $server = $servernodes->[0];
+      $server = (keys %{ $_[0] })[0];
       snd $server, join => $client, $nick;
       mon $server, $client;
    }
-The monitor will ensure that if the server crashes or goes away, the
+This second monitor will ensure that, when the server port crashes or goes
-client will be killed as well. This tells the user that the client was
+away (e.g. due to network problems), the client port will be killed as
-disconnected, and will then start to connect the server again.
+well. This tells the user that the client was disconnected, and will then
+start to connect the server again.
 The rest of the program deals with the boring details of actually invoking
 the supervisor function to start the whole client process and handle the
 actual terminal input, sending it to the server.
+Now... the "supervisor" in this example is a bit of a cheat - it doesn't
+really clean up much (because the cleanup done by AnyEvent::MP suffices),
+and there isn't much of a restarting action either - if the server isn't
+there because it crashed, well, it isn't there.
+In the real world, one would often add a timeout that would trigger when
+the server couldn't be found within some time limit, and then complain,
+or even try to start a new server. Or the supervisor would have to do
+some real cleanups, such as rolling back database transactions when the
+database thread crashes. For this simple chat server, however, this simple
+supervisor works fine. Hopefully future versions of AnyEvent::MP will
+offer some predefined supervisors, for now you will have to code it on
+your own.
 You should now try to start the server and one or more clients in different
 terminal windows (and the seed node):
    perl eg/chat_client nick1
 sides can take corrective action. Exceptions are "servers" that serve
 multiple clients at once and might only wish to clean up, and supervisors,
 who of course should not normally get killed (unless they, too, have a
 supervisor).
-If you often think in object-oriented terms, then treat a port as an
+If you often think in object-oriented terms, then you can think of a port
-object, C<port> is the constructor, the receive callbacks set by C<rcv>
+as an object: C<port> is the constructor, the receive callbacks set by
-act as methods, the C<kil> function becomes the explicit destructor and
+C<rcv> act as methods, the C<kil> function becomes the explicit destructor
-C<mon> installs a destructor hook. Unlike conventional object oriented
+and C<mon> installs a destructor hook. Unlike conventional object oriented
-programming, it can make sense to exchange ports more freely (for example,
+programming, it can make sense to exchange port IDs more freely (for
-to monitor one port from another).
+example, to monitor one port from another), because it is cheap to send
+port IDs over the network, and AnyEvent::MP blurs the distinction between
+local and remote ports.
-There is ample room for improvement: the server should probably remember
+Lastly, there is ample room for improvement in this example: the server
-the nickname in the C<join> handler instead of expecting it in every chat
+should probably remember the nickname in the C<join> handler instead of
-message, it should probably monitor itself, and the client should not try
+expecting it in every chat message, it should probably monitor itself, and
-to send any messages unless a server is actually connected.
+the client should not try to send any messages unless a server is actually
+connected.
 =head1 PART 3: TIMTOWTDI: Virtual Connections
 The chat system developed in the previous sections is very "traditional"
 in a way: you start some server(s) and some clients statically and they
 start talking to each other.
 Sometimes applications work more like "services": They can run on almost
-any node and talks to itself on other nodes. The L<AnyEvent::MP::Global>
+any node and even talk to copies of themselves on other nodes in case they
-service for example monitors nodes joining the network and starts itself
+are distributed. The L<AnyEvent::MP::Global> service for example monitors
-automatically on other nodes (if it isn't running already).
+nodes joining the network and sometimes even starts itself on other nodes.
-A good way to design such applications is to put them into a module and
+One good way to design such services is to put them into a module and
-create "virtual connections" to other nodes - we call this the "bridge
+create "virtual connections" to other nodes. We call this the "bridge
-head" method, because you start by creating a remote port (the bridge
+head" method, because you start by I<creating a remote port> (the bridge
 head) and from that you start to bootstrap your application.
-Since that sounds rather theoretical, let's redesign the chat server and
+Since that sounds rather theoretical, let us redesign the chat server and
 client using this design method.
-Here is the server:
+As usual, we start with the full program - here is the server:
    use common::sense;
    use AnyEvent::MP;
-   use AnyEvent::MP::Global;
    configure;
-   grp_reg eg_chat_server2 => $NODE;
+   db_set eg_chat_server2 => $NODE;
    my %clients;
    sub msg {
       print "relaying: $_[0]\n";
    sub client_connect {
       my ($client, $nick) = @_;
       mon $client;
-      mon $client, sub {
+      mon $client, psub {
          delete $clients{$client};
          msg "$nick (quits, @_)";
       };
       $clients{$client} = $client;
    warn "server ready.\n";
    AnyEvent->condvar->recv;
 It starts out not much different then the previous example, except that
-this time, we register the node port in the global group and not any port
+this time, we register the node port in the database and not a port we
-we created - the clients only want to know which node the server should be
+created - the clients only want to know which node the server should
+be running on, and there can only be one such server (or service) per
-running on. In fact, they could also use some kind of election mechanism,
+node. In fact, the clients could also use some kind of election mechanism,
-to find the node with lowest load or something like that.
+to find the node with lowest node ID, or lowest load, or something like
+that.
-The more interesting change is that indeed no server port is created -
+The much more interesting difference to the previous server is that
-the server consists only of code, and "does" nothing by itself. All it
+indeed no server port is created - the server consists only of code,
-does is define a function C<client_connect>, which expects a client port
+and "does" nothing by itself. All it "does" is to define a function
-and a nick name as arguments. It then monitors the client port and binds
+named C<client_connect>, which expects a client port and a nick name as
-a receive callback on C<$SELF>, which expects messages that in turn are
+arguments. It then monitors the client port and binds a receive callback
-broadcast to all clients.
+on C<$SELF>, which expects messages that in turn are 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>
+away" clean-up action.
-action.
-C<$SELF> is a good hint that something interesting is going on. And
+The last line, the C<rcv $SELF>, is a good hint that something interesting
-indeed, when looking at the client code, there is a new function,
+is going on. And indeed, when looking at the client code, you can see a
-C<spawn>:
+new function, C<spawn>:
+#todo#
    use common::sense;
    use AnyEvent::MP;
    use AnyEvent::MP::Global;
       $server = spawn $servernodes->[0], "::client_connect", $client, $nick;
       mon $server, $client;
 And of course the first thing after creating it is monitoring it.
-The C<spawn> function creates a new port on a remote node and returns
+Phew, let's go through this in slow motion: the C<spawn> function creates
-its port ID. After creating the port it calls a function on the remote
+a new port on a remote node and returns its port ID. After creating
-node, passing any remaining arguments to it, and - most importantly -
+the port it calls a function on the remote node, passing any remaining
-executes the function within the context of the new port, so it can be
+arguments to it, and - most importantly - executes the function within
-manipulated by referring to C<$SELF>. The init function can reside in a
+the context of the new port, so it can be manipulated by referring to
-module (actually it normally I<should> reside in a module) - AnyEvent::MP
+C<$SELF>. The init function can reside in a module (actually it normally
-will automatically load the module if the function isn't defined.
+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 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
 cleaned up on connection loss. When the remote node comes up again and our
 monitoring message can be delivered, it will instantly fail because the
 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 it on the local node, and monitor "the other
+creating a port using C<spawn>, monitor it on the local node, and monitor
-side" from the remote node, and all will be cleaned up just fine.
+"the other 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.

Diff Legend

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

Comparing AnyEvent-MP/MP/Intro.pod (file contents): Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC vs. Revision 1.52 by root, Wed Mar 21 01:14:12 2012 UTC

Diff Legend

Comparing AnyEvent-MP/MP/Intro.pod (file contents):
Revision 1.51 by root, Wed Mar 21 00:14:25 2012 UTC vs.
Revision 1.52 by root, Wed Mar 21 01:14:12 2012 UTC