AnyEvent-MP/MP/Intro.pod

=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<AnyEvent::MP>
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<JSON> 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<AnyEvent::MP> 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<tag> in L<AnyEvent::MP>, as some API functions
(C<rcv>) 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<passed>? They are I<passed> to I<ports>. A I<port> 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<port> belongs
to a I<node>, and a I<node> is just the UNIX process that runs your
L<AnyEvent::MP> application.

Each I<node> is distinguished from other I<nodes> running on the same or
another host in a network by its I<node ID>. A I<node ID> is simply a
unique string chosen manually or assigned by L<AnyEvent::MP> in some way
(UNIX nodename, random string...).

Here is a diagram about how I<nodes>, I<ports> and UNIX processes relate
to each other. The setup consists of two nodes (more are of course
possible): Node C<A> (in UNIX process 7066) with the ports C<ABC> and
C<DEF>. And the node C<B> (in UNIX process 8321) with the ports C<FOO> and
C<BAR>.


  |- PID: 7066 -|                  |- PID: 8321 -|
  |             |                  |             |
  | Node ID: A  |                  | Node ID: B  |
  |             |                  |             |
  |   Port ABC =|= <----\ /-----> =|= Port FOO   |
  |             |        X         |             |
  |   Port DEF =|= <----/ \-----> =|= Port BAR   |
  |             |                  |             |
  |-------------|                  |-------------|

The strings for the I<port IDs> here are just for illustrative
purposes: Even though I<ports> in L<AnyEvent::MP> are also identified by
strings, they can't be choosen manually and are assigned by the system
dynamically. These I<port IDs> 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<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

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>.

The example should print: C<Ending with: 123>, 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<AnyEvent::MP>: First there is the C<port> function which will create a
I<port> and will return it's I<port ID>, a simple string.

This I<port ID> 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<nodes> 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<port> to send the reply to - messages in
L<AnyEvent::MP> have a destination, but no source).

The next function is C<rcv>:

   rcv $port, test => sub { ... };

It installs a receiver callback on the I<port> 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<test>, specifies a I<tag> to
match. This means that whenever a message with the first element being
the string C<test> is received, the callback is called with the remaining
parts of that message.

Messages can be sent with the C<snd> 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<port> with the I<port
ID> stored in C<$port>. Since in this case the receiver has a I<tag> match
on C<test> 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<condition variable> 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<AnyEvent::Intro> 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<shared secret>: for two L<AnyEvent::MP>
I<nodes> to be able to communicate with each other over the network it is
necessary to setup the same I<shared secret> 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<aemp> 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<aemp setsecret>) and for increased security
requirements you can even create (or configure) a TLS certificate (F<aemp
gencert>), 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<nodes>
that want to connect to each other have the same I<shared secret> (or
successfully verify the TLS certificate of the other side, in which case
no shared secret is required).

B<If something does not work as expected, and for example tcpdump shows
that the connections are closed almost immediately, you should make sure
that F<~/.perl-anyevent-mp> 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<aemp> 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;

   configure nodeid => "eg_receiver", binds => ["*:4040"];

   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<AnyEvent::MP::Global>. This module provides us with a I<global
registry>, which lets us register ports in groups that are visible on all
I<nodes> in a network.

What is this useful for? Well, the I<port IDs> are random-looking strings,
assigned by L<AnyEvent::MP>. We cannot know those I<port IDs> in advance,
so we don't know which I<port ID> to send messages to, especially when the
message is to be passed between different I<nodes> (or UNIX processes). To
find the right I<port> of another I<node> in the network we will need
to communicate this somehow to the sender. And exactly that is what
L<AnyEvent::MP::Global> 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<configure> and the Network

Now, let's have a look at the new function, C<configure>:

   configure nodeid => "eg_receiver", binds => ["*:4040"];

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!

All of this (and more) can be passed to the C<configure> function - later
we will see how we can do all this without even passing anything to
C<configure>!

The first parameter, C<nodeid>, specified the node ID (in this case
C<eg_receiver> - the default is to use the node name of the current host,
but for this example we want to be able to run many nodes on the same
machine). Node IDs need to be unique within the network and can be almost
any string - if you don't care, you can specify a node ID of C<anon/>
which will then be replaced by a random node name.

The second parameter, C<binds>, specifies a list of C<address:port> pairs
to bind TCP listeners on. The special "address" of C<*> means to bind on
every local IP address.

The reason to bind on a TCP port is not just that other nodes can connect
to us: if no binds are specified, the node will still bind on a dynamic
port on all local addresses - but in this case we won't know the port, and
cannot tell other nodes to connect to it as seed node.

A I<seed> is a (fixed) TCP address of some other node in the network. To
explain the need for seeds we have to look at the topology of a typical
L<AnyEvent::MP> network. The topology is called a I<fully connected mesh>,
here an example with 4 nodes:

   N1--N2
   | \/ |
   | /\ |
   N3--N4

Now imagine another node - C<N5> - wants to connect itself to that network:

   N1--N2
   | \/ |    N5
   | /\ |
   N3--N4

The new node needs to know the I<binds> of all nodes already
connected. Exactly this is what the I<seeds> are for: Let's assume that
the new node (C<N5>) uses the TCP address of the node C<N2> as seed.  This
cuases it to connect to C<N2>:

   N1--N2____
   | \/ |    N5
   | /\ |
   N3--N4

C<N2> then tells C<N5> about the I<binds> of the other nodes it is
connected to, and C<N5> creates the rest of the connections:

    /--------\
   N1--N2____|
   | \/ |    N5
   | /\ |   /|
   N3--N4--- |
    \________/

All done: C<N5> is now happily connected to the rest of the network.

Of course, this process takes time, during which the node is already
running. This also means it takes time until the node is fully connected,
and global groups and other information is available. The best way to deal
with this is to either retry regularly until you found the resource you
were looking for, or to only start services on demand after a node has
become available.

=head3 Registering the Receiver

Coming back to our example, we have now introduced the basic purpose of
L<AnyEvent::MP::Global> and C<configure> 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<port> function has already been discussed. It simply creates a new
I<port> and returns the I<port ID>. The C<register> function, however,
is new: The first argument is the I<port ID> that we want to add to a
I<global group>, and its second argument is the name of that I<global
group>.

You can choose the name of such a I<global group> freely (prefixing your
package name is highly recommended!). The purpose of such a group is to
store a set of I<port IDs>. This set is made available throughout the
L<AnyEvent::MP> 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<global
group> 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<test>. 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;

   configure nodeid => "eg_sender", seeds => ["*:4040"];

   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<configure> serves the same purpose as in the
receiver, but instead of specifying binds we specify a list of seeds -
which happens to be the same as the binds used by the receiver, which
becomes our seed node.

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<find> function of
L<AnyEvent::MP::Global>. It searches in the global group named
C<eg_receivers> for ports. If none are found, it returns C<undef>, 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<find> returns an array reference that contains the I<port ID> of
the receiver I<port(s)>.

We then just send a message with a tag and the current time to every
I<port> in the global group.

=head3 Splitting Network Configuration and Application Code

Ok, so far, this works. In the real world, however, the person configuring
your application to run on a specific network (the end user or network
administrator) is often different to the person coding the application.

Or to put it differently: the arguments passed to configure are usually
provided not by the programmer, but by whoeever is deplying the program.

To make this easy, AnyEvent::MP supports a simple configuration database,
using profiles, which can be managed using the F<aemp> command-line
utility.

When you change both programs above to simply call

   configure;

then AnyEvent::MP tries to look up a profile using the current node name
in its configuration database, falling back to some global default.

You can run "generic" nodes using the F<aemp> utility as well, and we will
exploit this in the following way: we configure a profile "seed" and run
a node using it, whose sole purpose is to be a seed node for our example
programs.

We bind the seed node to port 4040 on all interfaces:

   aemp profile seed setbinds "*:4040"

And we configure all nodes to use this as seed node (this only works when
running on the same host, for multiple machines you would provide the IP
address or hostname of the node running the seed):

   aemp setseeds "*:4040"

Then we run the seed node:

   aemp run profile seed

After that, we can start as many other nodes as we want, and they will all
use our generic seed node to discover each other.

In fact, starting many receivers nicely illustrates that the time sender
can have multiple receivers.

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<AnyEvent>

L<AnyEvent::Handle>

L<AnyEvent::MP>

L<AnyEvent::MP::Global>

=head1 AUTHOR

  Robin Redeker <elmex@ta-sa.org>

Revision:	1.28
Committed:	Mon Aug 31 11:07:58 2009 UTC (17 years ago) by root
Branch:	MAIN
Changes since 1.27:	+88 -82 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.4	=head1 Message Passing for the Non-Blocked Mind
2	elmex	1.1
3	root	1.8	=head1 Introduction and Terminology
4	elmex	1.1
5	root	1.4	This is a tutorial about how to get the swing of the new L<AnyEvent::MP>
6	root	1.23	module, which allows programs to transparently pass messages within the
7			process and to other processes on the same or a different host.
8	elmex	1.1
9	root	1.23	What kind of messages? Basically a message here means a list of Perl
10	root	1.15	strings, numbers, hashes and arrays, anything that can be expressed as a
11	root	1.23	L<JSON> text (as JSON is used by default in the protocol). Here are two
12			examples:
13	elmex	1.1
14	root	1.23	write_log => 1251555874, "action was successful.\n"
15			123, ["a", "b", "c"], { foo => "bar" }
16	elmex	1.21
17	root	1.23	When using L<AnyEvent::MP> it is customary to use a descriptive string as
18			first element of a message, that indictes the type of the message. This
19			element is called a I<tag> in L<AnyEvent::MP>, as some API functions
20			(C<rcv>) support matching it directly.
21
22			Supposedly you want to send a ping message with your current time to
23			somewhere, this is how such a message might look like (in Perl syntax):
24
25			ping => 1251381636
26
27			Now that we know what a message is, to which entities are those
28			messages being I<passed>? They are I<passed> to I<ports>. A I<port> is
29			a destination for messages but also a context to execute code: when
30			a runtime error occurs while executing code belonging to a port, the
31			exception will be raised on the port and can even travel to interested
32			parties on other nodes, which makes supervision of distributed processes
33			easy.
34
35			How do these ports relate to things you know? Each I<port> belongs
36			to a I<node>, and a I<node> is just the UNIX process that runs your
37			L<AnyEvent::MP> application.
38
39			Each I<node> is distinguished from other I<nodes> running on the same or
40			another host in a network by its I<node ID>. A I<node ID> is simply a
41			unique string chosen manually or assigned by L<AnyEvent::MP> in some way
42			(UNIX nodename, random string...).
43
44			Here is a diagram about how I<nodes>, I<ports> and UNIX processes relate
45			to each other. The setup consists of two nodes (more are of course
46			possible): Node C<A> (in UNIX process 7066) with the ports C<ABC> and
47			C<DEF>. And the node C<B> (in UNIX process 8321) with the ports C<FOO> and
48			C<BAR>.
49	elmex	1.17
50
51			\|- PID: 7066 -\| \|- PID: 8321 -\|
52			\| \| \| \|
53			\| Node ID: A \| \| Node ID: B \|
54			\| \| \| \|
55			\| Port ABC =\|= <----\ /-----> =\|= Port FOO \|
56			\| \| X \| \|
57			\| Port DEF =\|= <----/ \-----> =\|= Port BAR \|
58			\| \| \| \|
59			\|-------------\| \|-------------\|
60
61	root	1.23	The strings for the I<port IDs> here are just for illustrative
62			purposes: Even though I<ports> in L<AnyEvent::MP> are also identified by
63			strings, they can't be choosen manually and are assigned by the system
64			dynamically. These I<port IDs> are unique within a network and can also be
65			used to identify senders or as message tags for instance.
66
67			The next sections will explain the API of L<AnyEvent::MP> by going through
68			a few simple examples. Later some more complex idioms are introduced,
69			which are hopefully useful to solve some real world problems.
70	root	1.8
71	elmex	1.16	=head1 Passing Your First Message
72
73	root	1.24	As a start lets have a look at the messaging API. The following example
74			is just a demo to show the basic elements of message passing with
75			L<AnyEvent::MP>.
76
77			The example should print: C<Ending with: 123>, in a rather complicated
78			way, by passing some message to a port.
79	elmex	1.16
80			use AnyEvent;
81			use AnyEvent::MP;
82
83			my $end_cv = AnyEvent->condvar;
84
85			my $port = port;
86
87			rcv $port, test => sub {
88			my ($data) = @_;
89			$end_cv->send ($data);
90			};
91
92			snd $port, test => 123;
93
94			print "Ending with: " . $end_cv->recv . "\n";
95
96	root	1.24	It already uses most of the essential functions inside
97			L<AnyEvent::MP>: First there is the C<port> function which will create a
98			I<port> and will return it's I<port ID>, a simple string.
99
100			This I<port ID> can be used to send messages to the port and install
101			handlers to receive messages on the port. Since it is a simple string
102			it can be safely passed to other I<nodes> in the network when you want
103			to refer to that specific port (usually used for RPC, where you need
104			to tell the other end which I<port> to send the reply to - messages in
105			L<AnyEvent::MP> have a destination, but no source).
106	elmex	1.17
107	root	1.24	The next function is C<rcv>:
108	elmex	1.16
109	elmex	1.17	rcv $port, test => sub { ... };
110	elmex	1.16
111	root	1.24	It installs a receiver callback on the I<port> that specified as the first
112			argument (it only works for "local" ports, i.e. ports created on the same
113			node). The next argument, in this example C<test>, specifies a I<tag> to
114			match. This means that whenever a message with the first element being
115			the string C<test> is received, the callback is called with the remaining
116	elmex	1.17	parts of that message.
117
118	root	1.24	Messages can be sent with the C<snd> function, which is used like this in
119			the example above:
120	elmex	1.17
121			snd $port, test => 123;
122
123	root	1.24	This will send the message C<'test', 123> to the I<port> with the I<port
124			ID> stored in C<$port>. Since in this case the receiver has a I<tag> match
125			on C<test> it will call the callback with the first argument being the
126			number C<123>.
127
128			The callback is a typicall AnyEvent idiom: the callback just passes
129			that number on to the I<condition variable> C<$end_cv> which will then
130			pass the value to the print. Condition variables are out of the scope
131			of this tutorial and not often used with ports, so please consult the
132	elmex	1.17	L<AnyEvent::Intro> about them.
133
134	root	1.24	Passing messages inside just one process is boring. Before we can move on
135			and do interprocess message passing we first have to make sure some things
136			have been set up correctly for our nodes to talk to each other.
137	elmex	1.17
138			=head1 System Requirements and System Setup
139
140	root	1.25	Before we can start with real IPC we have to make sure some things work on
141			your system.
142	elmex	1.17
143	root	1.25	First we have to setup a I<shared secret>: for two L<AnyEvent::MP>
144			I<nodes> to be able to communicate with each other over the network it is
145			necessary to setup the same I<shared secret> for both of them, so they can
146			prove their trustworthyness to each other.
147	elmex	1.17
148			The easiest way is to set this up is to use the F<aemp> utility:
149
150			aemp gensecret
151
152	root	1.25	This creates a F<$HOME/.perl-anyevent-mp> config file and generates a
153			random shared secret. You can copy this file to any other system and
154			then communicate over the network (via TCP) with it. You can also select
155			your own shared secret (F<aemp setsecret>) and for increased security
156			requirements you can even create (or configure) a TLS certificate (F<aemp
157			gencert>), causing connections to not just be securely authenticated, but
158			also to be encrypted and protected against tinkering.
159
160			Connections will only be successfully established when the I<nodes>
161			that want to connect to each other have the same I<shared secret> (or
162			successfully verify the TLS certificate of the other side, in which case
163			no shared secret is required).
164	elmex	1.17
165			B<If something does not work as expected, and for example tcpdump shows
166			that the connections are closed almost immediately, you should make sure
167			that F<~/.perl-anyevent-mp> is the same on all hosts/user accounts that
168			you try to connect with each other!>
169	elmex	1.16
170	root	1.25	Thats is all for now, you will find some more advanced fiddling with the
171			C<aemp> utility later.
172
173	elmex	1.18
174			=head1 Passing Messages Between Processes
175
176			=head2 The Receiver
177
178	root	1.25	Lets split the previous example up into two programs: one that contains
179			the sender and one for the receiver. First the receiver application, in
180			full:
181	elmex	1.18
182			use AnyEvent;
183			use AnyEvent::MP;
184			use AnyEvent::MP::Global;
185
186	root	1.28	configure nodeid => "eg_receiver", binds => ["*:4040"];
187	elmex	1.18
188			my $port = port;
189
190			AnyEvent::MP::Global::register $port, "eg_receivers";
191
192			rcv $port, test => sub {
193			my ($data, $reply_port) = @_;
194
195			print "Received data: " . $data . "\n";
196			};
197
198			AnyEvent->condvar->recv;
199
200			=head3 AnyEvent::MP::Global
201
202	root	1.25	Now, that wasn't too bad, was it? Ok, let's step through the new functions
203			and modules that have been used.
204
205			For starters, there is now an additional module being
206			used: L<AnyEvent::MP::Global>. This module provides us with a I<global
207			registry>, which lets us register ports in groups that are visible on all
208			I<nodes> in a network.
209
210			What is this useful for? Well, the I<port IDs> are random-looking strings,
211			assigned by L<AnyEvent::MP>. We cannot know those I<port IDs> in advance,
212			so we don't know which I<port ID> to send messages to, especially when the
213			message is to be passed between different I<nodes> (or UNIX processes). To
214			find the right I<port> of another I<node> in the network we will need
215			to communicate this somehow to the sender. And exactly that is what
216			L<AnyEvent::MP::Global> provides.
217
218			Especially in larger, more anonymous networks this is handy: imagine you
219			have a few database backends, a few web frontends and some processing
220			distributed over a number of hosts: all of these would simply register
221			themselves in the appropriate group, and your web frontends can start to
222			find some database backend.
223	elmex	1.18
224	root	1.28	=head3 C<configure> and the Network
225	elmex	1.18
226	root	1.28	Now, let's have a look at the new function, C<configure>:
227	elmex	1.18
228	root	1.28	configure nodeid => "eg_receiver", binds => ["*:4040"];
229	elmex	1.18
230			Before we are able to send messages to other nodes we have to initialise
231	root	1.26	ourself to become a "distributed node". Initialising a node means naming
232			the node, optionally binding some TCP listeners so that other nodes can
233			contact it and connecting to a predefined set of seed addresses so the
234			node can discover the existing network - and the existing network can
235			discover the node!
236
237	root	1.28	All of this (and more) can be passed to the C<configure> function - later
238			we will see how we can do all this without even passing anything to
239			C<configure>!
240
241			The first parameter, C<nodeid>, specified the node ID (in this case
242			C<eg_receiver> - the default is to use the node name of the current host,
243			but for this example we want to be able to run many nodes on the same
244			machine). Node IDs need to be unique within the network and can be almost
245			any string - if you don't care, you can specify a node ID of C<anon/>
246			which will then be replaced by a random node name.
247
248			The second parameter, C<binds>, specifies a list of C<address:port> pairs
249			to bind TCP listeners on. The special "address" of C<*> means to bind on
250			every local IP address.
251
252			The reason to bind on a TCP port is not just that other nodes can connect
253			to us: if no binds are specified, the node will still bind on a dynamic
254			port on all local addresses - but in this case we won't know the port, and
255			cannot tell other nodes to connect to it as seed node.
256
257			A I<seed> is a (fixed) TCP address of some other node in the network. To
258			explain the need for seeds we have to look at the topology of a typical
259			L<AnyEvent::MP> network. The topology is called a I<fully connected mesh>,
260			here an example with 4 nodes:
261	elmex	1.18
262			N1--N2
263			\| \/ \|
264			\| /\ \|
265			N3--N4
266
267	root	1.28	Now imagine another node - C<N5> - wants to connect itself to that network:
268	elmex	1.18
269			N1--N2
270			\| \/ \| N5
271			\| /\ \|
272			N3--N4
273
274	root	1.26	The new node needs to know the I<binds> of all nodes already
275			connected. Exactly this is what the I<seeds> are for: Let's assume that
276			the new node (C<N5>) uses the TCP address of the node C<N2> as seed. This
277			cuases it to connect to C<N2>:
278	elmex	1.18
279			N1--N2____
280			\| \/ \| N5
281			\| /\ \|
282			N3--N4
283
284	root	1.26	C<N2> then tells C<N5> about the I<binds> of the other nodes it is
285			connected to, and C<N5> creates the rest of the connections:
286	elmex	1.18
287			/--------\
288			N1--N2____\|
289			\| \/ \| N5
290			\| /\ \| /\|
291			N3--N4--- \|
292			\________/
293
294	root	1.26	All done: C<N5> is now happily connected to the rest of the network.
295	elmex	1.18
296	root	1.28	Of course, this process takes time, during which the node is already
297			running. This also means it takes time until the node is fully connected,
298			and global groups and other information is available. The best way to deal
299			with this is to either retry regularly until you found the resource you
300			were looking for, or to only start services on demand after a node has
301			become available.
302	elmex	1.19
303	root	1.28	=head3 Registering the Receiver
304	elmex	1.19
305	root	1.27	Coming back to our example, we have now introduced the basic purpose of
306	root	1.28	L<AnyEvent::MP::Global> and C<configure> and its use of profiles. We
307	root	1.27	also set up our profiles for later use and now we will finally continue
308			talking about the receiver.
309	elmex	1.19
310	root	1.27	Let's look at the next line(s):
311	elmex	1.19
312			my $port = port;
313			AnyEvent::MP::Global::register $port, "eg_receivers";
314
315	root	1.27	The C<port> function has already been discussed. It simply creates a new
316			I<port> and returns the I<port ID>. The C<register> function, however,
317	root	1.28	is new: The first argument is the I<port ID> that we want to add to a
318	root	1.27	I<global group>, and its second argument is the name of that I<global
319	elmex	1.19	group>.
320
321	root	1.27	You can choose the name of such a I<global group> freely (prefixing your
322			package name is highly recommended!). The purpose of such a group is to
323			store a set of I<port IDs>. This set is made available throughout the
324	root	1.28	L<AnyEvent::MP> network, so that each node can see which ports belong to
325			that group.
326	root	1.27
327			Later we will see how the sender looks for the ports in this I<global
328			group> to send messages to them.
329
330			The last step in the example is to set up a receiver callback for those
331			messages, just as was discussed in the first example. We again match
332			for the tag C<test>. The difference is that this time we don't exit the
333			application after receiving the first message. Instead we continue to wait
334			for new messages indefinitely.
335	elmex	1.19
336	elmex	1.20	=head2 The Sender
337	root	1.8
338	root	1.27	Ok, now let's take a look at the sender code:
339	root	1.4
340	elmex	1.1	use AnyEvent;
341			use AnyEvent::MP;
342	elmex	1.20	use AnyEvent::MP::Global;
343	elmex	1.1
344	root	1.28	configure nodeid => "eg_sender", seeds => ["*:4040"];
345	elmex	1.1
346	elmex	1.20	my $find_timer =
347			AnyEvent->timer (after => 0, interval => 1, cb => sub {
348			my $ports = AnyEvent::MP::Global::find "eg_receivers"
349			or return;
350
351			snd $_, test => time
352			for @$ports;
353			});
354	elmex	1.1
355			AnyEvent->condvar->recv;
356
357	root	1.28	It's even less code. The C<configure> serves the same purpose as in the
358			receiver, but instead of specifying binds we specify a list of seeds -
359			which happens to be the same as the binds used by the receiver, which
360			becomes our seed node.
361	root	1.10
362	root	1.27	Next we set up a timer that repeatedly (every second) calls this chunk of
363			code:
364	elmex	1.1
365	elmex	1.20	my $ports = AnyEvent::MP::Global::find "eg_receivers"
366			or return;
367	elmex	1.2
368	elmex	1.20	snd $_, test => time
369			for @$ports;
370	elmex	1.1
371	root	1.27	The only new function here is the C<find> function of
372			L<AnyEvent::MP::Global>. It searches in the global group named
373			C<eg_receivers> for ports. If none are found, it returns C<undef>, which
374			makes our code return instantly and wait for the next round, as nobody is
375			interested in our message.
376
377			As soon as the receiver application has connected and the information
378			about the newly added port in the receiver has propagated to the sender
379			node, C<find> returns an array reference that contains the I<port ID> of
380			the receiver I<port(s)>.
381
382			We then just send a message with a tag and the current time to every
383			I<port> in the global group.
384
385	root	1.28	=head3 Splitting Network Configuration and Application Code
386
387			Ok, so far, this works. In the real world, however, the person configuring
388			your application to run on a specific network (the end user or network
389			administrator) is often different to the person coding the application.
390
391			Or to put it differently: the arguments passed to configure are usually
392			provided not by the programmer, but by whoeever is deplying the program.
393
394			To make this easy, AnyEvent::MP supports a simple configuration database,
395			using profiles, which can be managed using the F<aemp> command-line
396			utility.
397
398			When you change both programs above to simply call
399
400			configure;
401
402			then AnyEvent::MP tries to look up a profile using the current node name
403			in its configuration database, falling back to some global default.
404
405			You can run "generic" nodes using the F<aemp> utility as well, and we will
406			exploit this in the following way: we configure a profile "seed" and run
407			a node using it, whose sole purpose is to be a seed node for our example
408			programs.
409
410			We bind the seed node to port 4040 on all interfaces:
411
412			aemp profile seed setbinds "*:4040"
413
414			And we configure all nodes to use this as seed node (this only works when
415			running on the same host, for multiple machines you would provide the IP
416			address or hostname of the node running the seed):
417
418			aemp setseeds "*:4040"
419
420			Then we run the seed node:
421
422			aemp run profile seed
423
424			After that, we can start as many other nodes as we want, and they will all
425			use our generic seed node to discover each other.
426	root	1.27
427	root	1.28	In fact, starting many receivers nicely illustrates that the time sender
428			can have multiple receivers.
429	elmex	1.7
430	root	1.27	That's all for now - next time we will teach you about monitoring by
431			writing a simple chat client and server :)
432	elmex	1.7
433	elmex	1.1	=head1 SEE ALSO
434
435			L<AnyEvent>
436
437			L<AnyEvent::Handle>
438
439			L<AnyEvent::MP>
440
441	elmex	1.20	L<AnyEvent::MP::Global>
442
443	elmex	1.1	=head1 AUTHOR
444
445			Robin Redeker <elmex@ta-sa.org>
446	root	1.4