=head1 Message Passing for the Non-Blocked Mind =head1 Introduction and Terminology This is a tutorial about how to get the swing of the new L module, which allows programs to transparently pass messages within the process and to other processes on the same or a different host. What kind of messages? Basically a message here means a list of Perl strings, numbers, hashes and arrays, anything that can be expressed as a L text (as JSON is used by default in the protocol). Here are two examples: write_log => 1251555874, "action was successful.\n" 123, ["a", "b", "c"], { foo => "bar" } When using L it is customary to use a descriptive string as first element of a message, that indictes the type of the message. This element is called a I in L, as some API functions (C) support matching it directly. Supposedly you want to send a ping message with your current time to somewhere, this is how such a message might look like (in Perl syntax): ping => 1251381636 Now that we know what a message is, to which entities are those messages being I? They are I to I. A I is a destination for messages but also a context to execute code: when a runtime error occurs while executing code belonging to a port, the exception will be raised on the port and can even travel to interested parties on other nodes, which makes supervision of distributed processes easy. How do these ports relate to things you know? Each I belongs to a I, and a I is just the UNIX process that runs your L application. Each I is distinguished from other I running on the same or another host in a network by its I. A I is simply a unique string chosen manually or assigned by L in some way (UNIX nodename, random string...). Here is a diagram about how I, I and UNIX processes relate to each other. The setup consists of two nodes (more are of course possible): Node C (in UNIX process 7066) with the ports C and C. And the node C (in UNIX process 8321) with the ports C and C. |- PID: 7066 -| |- PID: 8321 -| | | | | | Node ID: A | | Node ID: B | | | | | | Port ABC =|= <----\ /-----> =|= Port FOO | | | X | | | Port DEF =|= <----/ \-----> =|= Port BAR | | | | | |-------------| |-------------| The strings for the I here are just for illustrative purposes: Even though I in L are also identified by strings, they can't be choosen manually and are assigned by the system dynamically. These I are unique within a network and can also be used to identify senders or as message tags for instance. The next sections will explain the API of L 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 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. The example should print: C, in a rather complicated way, by passing some message to a port. use AnyEvent; use AnyEvent::MP; my $end_cv = AnyEvent->condvar; my $port = port; rcv $port, test => sub { my ($data) = @_; $end_cv->send ($data); }; snd $port, test => 123; print "Ending with: " . $end_cv->recv . "\n"; It already uses most of the essential functions inside L: First there is the C function which will create a I and will return it's I, a simple string. This I can be used to send messages to the port and install handlers to receive messages on the port. Since it is a simple string it can be safely passed to other I in the network when you want to refer to that specific port (usually used for RPC, where you need to tell the other end which I to send the reply to - messages in L have a destination, but no source). The next function is C: rcv $port, test => sub { ... }; It installs a receiver callback on the I that specified as the first argument (it only works for "local" ports, i.e. ports created on the same node). The next argument, in this example C, specifies a I to match. This means that whenever a message with the first element being the string C is received, the callback is called with the remaining parts of that message. Messages can be sent with the C function, which is used like this in the example above: snd $port, test => 123; This will send the message C<'test', 123> to the I with the I stored in C<$port>. Since in this case the receiver has a I match on C it will call the callback with the first argument being the number C<123>. The callback is a typicall AnyEvent idiom: the callback just passes that number on to the I C<$end_cv> which will then pass the value to the print. Condition variables are out of the scope of this tutorial and not often used with ports, so please consult the L about them. 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 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: for two L I to be able to communicate with each other over the network it is necessary to setup the same I for both of them, so they can prove their trustworthyness to each other. The easiest way is to set this up is to use the F utility: aemp gensecret This creates a F<$HOME/.perl-anyevent-mp> config file and generates a random shared secret. You can copy this file to any other system and then communicate over the network (via TCP) with it. You can also select your own shared secret (F) and for increased security requirements you can even create (or configure) a TLS certificate (F), causing connections to not just be securely authenticated, but also to be encrypted and protected against tinkering. Connections will only be successfully established when the I that want to connect to each other have the same I (or successfully verify the TLS certificate of the other side, in which case no shared secret is required). B is the same on all hosts/user accounts that you try to connect with each other!> Thats is all for now, you will find some more advanced fiddling with the C utility later. =head1 Passing Messages Between Processes =head2 The Receiver Lets split the previous example up into two programs: one that contains the sender and one for the receiver. First the receiver application, in full: use AnyEvent; use AnyEvent::MP; use AnyEvent::MP::Global; initialise_node "eg_simple_receiver"; my $port = port; AnyEvent::MP::Global::register $port, "eg_receivers"; rcv $port, test => sub { my ($data, $reply_port) = @_; print "Received data: " . $data . "\n"; }; AnyEvent->condvar->recv; =head3 AnyEvent::MP::Global Now, that wasn't too bad, was it? Ok, let's step through the new functions and modules that have been used. For starters, there is now an additional module being used: L. This module provides us with a I, which lets us register ports in groups that are visible on all I in a network. What is this useful for? Well, the I are random-looking strings, assigned by L. We cannot know those I in advance, so we don't know which I to send messages to, especially when the message is to be passed between different I (or UNIX processes). To find the right I of another I in the network we will need to communicate this somehow to the sender. And exactly that is what L provides. Especially in larger, more anonymous networks this is handy: imagine you have a few database backends, a few web frontends and some processing distributed over a number of hosts: all of these would simply register themselves in the appropriate group, and your web frontends can start to find some database backend. =head3 C And The Network Now, let's have a look at the new function, C: initialise_node "eg_simple_receiver"; Before we are able to send messages to other nodes we have to initialise ourself to become a "distributed node". Initialising a node means naming the node, optionally binding some TCP listeners so that other nodes can contact it and connecting to a predefined set of seed addresses so the node can discover the existing network - and the existing network can discover the node! The first argument, the string C<"eg_simple_receiver">, is the so-called I to use: A profile holds some information about the application that is going to be a node in an L network. Customarily you don't specify a profile name at all: in this case, AnyEvent::MP will use the POSIX nodename. The profile allows you to set the I that your application will use (the node ID defaults to the profile name if not specified). You can also set I in the profile, meaning that you can define TCP ports that the application will listen on for incoming connections from other nodes of the network. You should also configure I in the profile: A I is just a TCP address of some other node in the network. To explain this a bit more detailed we have to look at the topology of an L network. The topology is called a I, here an example with 4 nodes: N1--N2 | \/ | | /\ | N3--N4 Now imagine another I C. wants to connect itself to that network: N1--N2 | \/ | N5 | /\ | N3--N4 The new node needs to know the I of all nodes already connected. Exactly this is what the I are for: Let's assume that the new node (C) uses the TCP address of the node C as seed. This cuases it to connect to C: N1--N2____ | \/ | N5 | /\ | N3--N4 C then tells C about the I of the other nodes it is connected to, and C creates the rest of the connections: /--------\ N1--N2____| | \/ | N5 | /\ | /| N3--N4--- | \________/ All done: C is now happily connected to the rest of the network. =head3 Setting Up The Profiles Ok, so much to the profile. Now let's setup the C I for later use. For the receiver we just give the receiver a I: aemp profile eg_simple_receiver setbinds localhost:12266 We use C in the example, but in the real world, you usually want to use the "real" IP address of your node, so hosts can connect to it. Of course, you can specify many binds, and it is also perfectly useful to run multiple nodes on the same host. Just keep in mind that other nodes will try to I to those addresses, and this better succeeds if you want your network to be in good working conditions. While we are at it, we setup the I for the sender in the second part of this example, too. We will call the sender I C. For the sender we set up a I pointing to the receiver: aemp profile eg_simple_sender setseeds localhost:12266 aemp profile eg_simple_sender setbinds You might wonder why we setup I to be empty here: actually, the the I in the I is not the complete truth: If you don't configure any I for a node profile it will parse and try to resolve the node ID to find addresses to bind to. In this case we pretend that we do not want this and epxlicitly specify an empty binds list, so the node will not actually listen on any TCP ports. Nodes without listeners will not be able to send messages to other nodes without listeners, but they can still talk to all other nodes. For this example, as well as in many cases in the real world, we can live with this restriction, and this makes it easier to avoid DNS (assuming your setup is broken, eliminating one potential problem :). Whee, setting up nodes can be complicated at first, but you only have to do it once per network, and you can leave this boring task to the admins or end-users that want to use your stuff :) =head3 Registering The Receiver Coming back to our example, we have now introduced the basic purpose of L and C and its use of profiles. We also set up our profiles for later use and now we will finally continue talking about the receiver. Let's look at the next line(s): my $port = port; AnyEvent::MP::Global::register $port, "eg_receivers"; The C function has already been discussed. It simply creates a new I and returns the I. The C function, however, is new: The first argument is the I that we want to add to a I, and its second argument is the name of that I. You can choose the name of such a I freely (prefixing your package name is highly recommended!). The purpose of such a group is to store a set of I. This set is made available throughout the whole L network, so that each node can see which ports belong to that group. Later we will see how the sender looks for the ports in this I to send messages to them. The last step in the example is to set up a receiver callback for those messages, just as was discussed in the first example. We again match for the tag C. The difference is that this time we don't exit the application after receiving the first message. Instead we continue to wait for new messages indefinitely. =head2 The Sender Ok, now let's take a look at the sender code: use AnyEvent; use AnyEvent::MP; use AnyEvent::MP::Global; initialise_node "eg_simple_sender"; my $find_timer = AnyEvent->timer (after => 0, interval => 1, cb => sub { my $ports = AnyEvent::MP::Global::find "eg_receivers" or return; snd $_, test => time for @$ports; }); AnyEvent->condvar->recv; It's even less code. The C serves the same purpose as in the receiver, we just specify a different profile, the profile we set up without the binds. Next we set up a timer that repeatedly (every second) calls this chunk of code: my $ports = AnyEvent::MP::Global::find "eg_receivers" or return; snd $_, test => time for @$ports; The only new function here is the C function of L. It searches in the global group named C for ports. If none are found, it returns C, which makes our code return instantly and wait for the next round, as nobody is interested in our message. As soon as the receiver application has connected and the information about the newly added port in the receiver has propagated to the sender node, C returns an array reference that contains the I of the receiver I. We then just send a message with a tag and the current time to every I in the global group. =head3 Multiple Receivers You can even run multiple receivers - the only problem is that they will use the same node ID. To avoid this problem, you can either not specify a profile name at all and rely on DNS and your POSIX node name, or you can use a special feature called "anonymous nodes": aemp profile eg_simple_receiver setnodeid anon/ The special name C will be replaced by a random string each time the node starts. This way you can start many receivers (they do not bind on a TCP port, so cnanot collide with each other), and all of them will receive the central time signal. That's all for now - next time we will teach you about monitoring by writing a simple chat client and server :) =head1 SEE ALSO L L L L =head1 AUTHOR Robin Redeker