AnyEvent-MP
view release on metacpan or search on metacpan
Revision history for AnyEvent::MP
TODO: testsuite
TODO: intro: maybe simple job pool example?
TODO: intro: mention watchdog...
TODO: maybe disbale warnings by default?
TODO: listener-scopes (10.0.0.1:4040@vpn) and connect-scopes ("vpn,public")
TODO: document env-variable usage
TODO: make node objects responsible for keepalive?
faq: can't se anything
faq: all is asynch
faq: how to interface to non-perl nodes?
TODO: check gproto, nproto, on connect
TODO: limiting reconnecting speed when unreachable? somehow use same interval timers as for seeding and keepalive?
TODO: multiple profiles? also some default profiles?
This should be the most common form of invocation for "daemon"-type nodes.
configure
Example: become a semi-anonymous node. This form is often used for
commandline clients.
configure nodeid => "myscript/%n/%u";
Example: configure a node using a profile called seed, which is suitable
for a seed node as it binds on all local addresses on a fixed port (4040,
customary for aemp).
# use the aemp commandline utility
# aemp profile seed binds '*:4040'
# then use it
configure profile => "seed";
# or simply use aemp from the shell again:
# aemp run profile seed
# or provide a nicer-to-remember nodeid
# aemp run profile seed nodeid "$(hostname)"
MP/Intro.pod view on Meta::CPAN
To help troubleshooting any issues, there are two environment variables
that you can set. The first, C<AE_VERBOSE> sets the logging level of
L<AnyEvent::Log>, which AnyEvent::MP uses. The default is C<4>, which
means nothing much is printed. You can increase it to C<8> or C<9> to get
more verbose output. This is example output when starting a node (somewhat
abridged to get shorter lines):
2012-03-22 01:41:43.59 debug AE::Util: using Guard module to implement guards.
2012-03-22 01:41:43.62 debug AE::MP::Kernel: node cerebro/slwK2LEq7O starting up.
2012-03-22 01:41:43.62 debug AE::MP::Kernel: node listens on [10.0.0.1:52110].
2012-03-22 01:41:43.62 trace AE::MP::Kernel: trying connect to seed node 10.0.0.19:4040.
2012-03-22 01:41:43.66 trace AE::MP::Transport: 10.0.0.19:4040 connected as rain.
2012-03-22 01:41:43.66 info AE::MP::Kernel: rain is up.
A lot of info, but at least you can see that it does something. To only
get info about AnyEvent::MP, you can use C<AE_LOG=AnyEvent::MP=+log> in
your environment.
The other environment variable that can be useful is
C<AE_MP_TRACE>, which, when set to a true value, will cause
most messages that are sent or received to be printed. For example, F<aemp
restart rijk> might output these message exchanges:
SND rijk <- [null,"eval","AnyEvent::Watchdog::Util::restart; ()","aemp/cerebro/z4kUPp2JT4#b"]
SND rain <- [null,"g_slave",{"'l":{"aemp/cerebro/z4kUPp2JT4":["10.0.0.1:48168"]}}]
SND rain <- [null,"g_find","rijk"]
RCV rain -> ["","g_found","rijk",["10.0.0.23:4040"]]
RCV rijk -> ["b",""]
=head1 PART 1: 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;
configure nodeid => "eg_receiver/%u", binds => ["*:4040"];
my $port = port;
db_set eg_receivers => $port;
rcv $port, test => sub {
my ($data, $reply_port) = @_;
print "Received data: " . $data . "\n";
};
AnyEvent->condvar->recv;
Now, that wasn't too bad, was it? OK, let's go through the new functions
that have been used.
=head3 C<configure> and Joining and Maintaining the Network
First let's have a look at C<configure>:
configure nodeid => "eg_receiver/%u", binds => ["*:4040"];
Before we are able to send messages to other nodes we have to configure
the node to become a "networked node". Configuring a node means naming
the node and binding some TCP listeners so that other nodes can contact
it. The choice on whether a process becomes a networked node or not must
be done before doing anything else with AnyEvent::MP.
Additionally, to actually link all nodes in a network together, you should
specify a number of seed addresses, which will be used by the node to
connect itself into an existing network, as we will see shortly.
MP/Intro.pod view on Meta::CPAN
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;
configure nodeid => "eg_sender/%u", seeds => ["*:4040"];
my $guard = db_mon eg_receivers => sub {
my ($family, $a, $c, $d) = @_;
return unless %$family;
# now there are some receivers, send them a message
snd $_ => test => time
for keys %$family;
};
MP/Intro.pod view on Meta::CPAN
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 binds "*: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 replace the C<*>
by the IP address or hostname of the node running the seed), by changing
the global settings shared between all profiles:
aemp seeds "*: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. The reason we can
start our existing programs even though they specify "incompatible"
parameters to C<configure> is that the configuration file (by default)
takes precedence over any arguments passed to C<configure>.
MP/Transport.pm view on Meta::CPAN
After this, packets get exchanged using the chosen framing protocol. It is
quite possible that both sides use a different framing protocol.
=head2 FULL EXAMPLE
This is an actual protocol dump of a handshake, followed by a single data
packet. The greater than/less than lines indicate the direction of the
transfer only.
> aemp;0;anon/57Cs1CggVJjzYaQp13XXg4;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;provider=AE-0.8;timeout=12;peeraddr=10.0.0.17:4040
> yLgdG1ov/02shVkVQer3wzeuywZK+oraTdEQBmIqWHaegxSGDG4g+HqogLQbvdypFOsoDWJ1Sh4ImV4DMhvUBwTK
< aemp;0;ruth;tls_md6_64_256,hmac_md6_64_256,tls_anon,cleartext;json,storable;provider=AE-0.8;timeout=12;peeraddr=10.0.0.1:37108
< +xMQXP8ElfNmuvEhsmcp+s2wCJOuQAsPxSg3d2Ewhs6gBnJz+ypVdWJ/wAVrXqlIJfLeVS/CBy4gEGkyWHSuVb1L
> hmac_md6_64_256;5ad913855742ae5a03a5aeb7eafa4c78629de136bed6acd73eea36c9e98df44a;json
< hmac_md6_64_256;84cd590976f794914c2ca26dac3a207a57a6798b9171289c114de07cf0c20401;json
< ["","AnyEvent::MP::_spawn","57Cs1CggVJjzYaQp13XXg4.c","AnyEvent::MP::Global::connect",0,"anon/57Cs1CggVJjzYaQp13XXg4"]
...
configure
Example: become a semi-anonymous node. This form is often used for
commandline clients.
configure nodeid => "myscript/%n/%u";
Example: configure a node using a profile called seed, which is
suitable for a seed node as it binds on all local addresses on a
fixed port (4040, customary for aemp).
# use the aemp commandline utility
# aemp profile seed binds '*:4040'
# then use it
configure profile => "seed";
# or simply use aemp from the shell again:
# aemp run profile seed
# or provide a nicer-to-remember nodeid
# aemp run profile seed nodeid "$(hostname)"
The F<aemp> utility works like F<cvs>, F<svn> or other commands: the first
argument defines which operation (subcommand) is requested, after which
arguments for this operation are expected. When a subcommand does not eat
all remaining arguments, the remaining arguments will again be interpreted
as subcommand and so on.
This means you can chain multiple commands, which is handy for profile
configuration, e.g.:
aemp gensecret profile xyzzy binds 4040,4041 nodeid anon/
Please note that all C<setxxx> subcommands have an alias without the
C<set> prefix.
All configuration data is stored in a human-readable (JSON) config file
stored in F<~/.perl-anyevent-mp> (or F<%appdata%/perl-anyevent-mp> on
loser systems, or wherever C<$ENV{PERL_ANYEVENT_MP_RC}> points to). Feel
free to look at it or edit it, the format is relatively simple.
=head2 SPECIFYING ARGUMENTS
interpreted as a UTF-8 encoded JSON text. The resulting array replaces all
arguments.
Otherwise, if I<any> argument starts with one of C<[>, C<{> or C<">, then
it is interpreted as UTF-8 encoded JSON text (or a single value in case of
C<">), and the resulting reference or scalar replaces the argument.
This allows you, for example, to specify binds in F<aemp run> (using POSIX
shell syntax):
aemp run binds '["*:4040"]'
=head2 RUNNING A NODE
This can be used to run a node - together with some services, this makes
it unnecessary to write any wrapper programs.
=over 4
=item run <configure_args>...
Note that the C<*>, C<*:*> or C<*:port> patterns are very useful here.
Example: bind on a ephemeral port on all local interfaces.
aemp setbinds "*"
Example: bind on a random port on all local interfaces.
aemp setbinds "*:*"
Example: resolve "doomed.mydomain" and try to bind on port C<4040> of all
IP addressess returned.
aep setbinds doomed.mydomain:4040
=item delbinds
Removes the bind list again, which means it is inherited again from it's
parent profile, or stays unset.
=item addbind <host:port>
Adds a single bind address.
( run in 1.071 second using v1.01-cache-2.11-cpan-39bf76dae61 )