ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-MP/MP.pm
(Generate patch)

Comparing AnyEvent-MP/MP.pm (file contents):
Revision 1.72 by root, Mon Aug 31 10:07:04 2009 UTC vs.
Revision 1.80 by root, Fri Sep 4 22:30:29 2009 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::MP; 7 use AnyEvent::MP;
8 8
9 $NODE # contains this node's noderef 9 $NODE # contains this node's node ID
10 NODE # returns this node's noderef 10 NODE # returns this node's node ID
11 NODE $port # returns the noderef of the port
12 11
13 $SELF # receiving/own port id in rcv callbacks 12 $SELF # receiving/own port id in rcv callbacks
14 13
15 # initialise the node so it can send/receive messages 14 # initialise the node so it can send/receive messages
16 configure; 15 configure;
17 16
18 # ports are message endpoints 17 # ports are message destinations
19 18
20 # sending messages 19 # sending messages
21 snd $port, type => data...; 20 snd $port, type => data...;
22 snd $port, @msg; 21 snd $port, @msg;
23 snd @msg_with_first_element_being_a_port; 22 snd @msg_with_first_element_being_a_port;
24 23
25 # creating/using ports, the simple way 24 # creating/using ports, the simple way
26 my $simple_port = port { my @msg = @_; 0 }; 25 my $simple_port = port { my @msg = @_ };
27 26
28 # creating/using ports, tagged message matching 27 # creating/using ports, tagged message matching
29 my $port = port; 28 my $port = port;
30 rcv $port, ping => sub { snd $_[0], "pong"; 0 }; 29 rcv $port, ping => sub { snd $_[0], "pong" };
31 rcv $port, pong => sub { warn "pong received\n"; 0 }; 30 rcv $port, pong => sub { warn "pong received\n" };
32 31
33 # create a port on another node 32 # create a port on another node
34 my $port = spawn $node, $initfunc, @initdata; 33 my $port = spawn $node, $initfunc, @initdata;
35 34
36 # monitoring 35 # monitoring
… …
40 39
41=head1 CURRENT STATUS 40=head1 CURRENT STATUS
42 41
43 bin/aemp - stable. 42 bin/aemp - stable.
44 AnyEvent::MP - stable API, should work. 43 AnyEvent::MP - stable API, should work.
45 AnyEvent::MP::Intro - uptodate, but incomplete. 44 AnyEvent::MP::Intro - explains most concepts.
46 AnyEvent::MP::Kernel - mostly stable. 45 AnyEvent::MP::Kernel - mostly stable.
47 AnyEvent::MP::Global - stable API, protocol not yet final. 46 AnyEvent::MP::Global - stable but incomplete, protocol not yet final.
48 47
49 stay tuned. 48stay tuned.
50 49
51=head1 DESCRIPTION 50=head1 DESCRIPTION
52 51
53This module (-family) implements a simple message passing framework. 52This module (-family) implements a simple message passing framework.
54 53
… …
56on the same or other hosts, and you can supervise entities remotely. 55on the same or other hosts, and you can supervise entities remotely.
57 56
58For an introduction to this module family, see the L<AnyEvent::MP::Intro> 57For an introduction to this module family, see the L<AnyEvent::MP::Intro>
59manual page and the examples under F<eg/>. 58manual page and the examples under F<eg/>.
60 59
61At the moment, this module family is a bit underdocumented.
62
63=head1 CONCEPTS 60=head1 CONCEPTS
64 61
65=over 4 62=over 4
66 63
67=item port 64=item port
68 65
69A port is something you can send messages to (with the C<snd> function). 66Not to be confused with a TCP port, a "port" is something you can send
67messages to (with the C<snd> function).
70 68
71Ports allow you to register C<rcv> handlers that can match all or just 69Ports allow you to register C<rcv> handlers that can match all or just
72some messages. Messages send to ports will not be queued, regardless of 70some messages. Messages send to ports will not be queued, regardless of
73anything was listening for them or not. 71anything was listening for them or not.
74 72
… …
161 159
162=item $nodeid = node_of $port 160=item $nodeid = node_of $port
163 161
164Extracts and returns the node ID from a port ID or a node ID. 162Extracts and returns the node ID from a port ID or a node ID.
165 163
164=item configure $profile, key => value...
165
166=item configure key => value... 166=item configure key => value...
167 167
168Before a node can talk to other nodes on the network (i.e. enter 168Before a node can talk to other nodes on the network (i.e. enter
169"distributed mode") it has to configure itself - the minimum a node needs 169"distributed mode") it has to configure itself - the minimum a node needs
170to know is its own name, and optionally it should know the addresses of 170to know is its own name, and optionally it should know the addresses of
… …
177 177
178=item step 1, gathering configuration from profiles 178=item step 1, gathering configuration from profiles
179 179
180The function first looks up a profile in the aemp configuration (see the 180The function first looks up a profile in the aemp configuration (see the
181L<aemp> commandline utility). The profile name can be specified via the 181L<aemp> commandline utility). The profile name can be specified via the
182named C<profile> parameter. If it is missing, then the nodename (F<uname 182named C<profile> parameter or can simply be the first parameter). If it is
183-n>) will be used as profile name. 183missing, then the nodename (F<uname -n>) will be used as profile name.
184 184
185The profile data is then gathered as follows: 185The profile data is then gathered as follows:
186 186
187First, all remaining key => value pairs (all of which are conviniently 187First, all remaining key => value pairs (all of which are conveniently
188undocumented at the moment) will be interpreted as configuration 188undocumented at the moment) will be interpreted as configuration
189data. Then they will be overwritten by any values specified in the global 189data. Then they will be overwritten by any values specified in the global
190default configuration (see the F<aemp> utility), then the chain of 190default configuration (see the F<aemp> utility), then the chain of
191profiles chosen by the profile name (and any C<parent> attributes). 191profiles chosen by the profile name (and any C<parent> attributes).
192 192
… …
231Example: configure a node using a profile called seed, which si suitable 231Example: configure a node using a profile called seed, which si suitable
232for a seed node as it binds on all local addresses on a fixed port (4040, 232for a seed node as it binds on all local addresses on a fixed port (4040,
233customary for aemp). 233customary for aemp).
234 234
235 # use the aemp commandline utility 235 # use the aemp commandline utility
236 # aemp profile seed setnodeid anon/ setbinds '*:4040' 236 # aemp profile seed nodeid anon/ binds '*:4040'
237 237
238 # then use it 238 # then use it
239 configure profile => "seed"; 239 configure profile => "seed";
240 240
241 # or simply use aemp from the shell again: 241 # or simply use aemp from the shell again:
… …
372 372
373=cut 373=cut
374 374
375sub rcv($@) { 375sub rcv($@) {
376 my $port = shift; 376 my $port = shift;
377 my ($noderef, $portid) = split /#/, $port, 2; 377 my ($nodeid, $portid) = split /#/, $port, 2;
378 378
379 $NODE{$noderef} == $NODE{""} 379 $NODE{$nodeid} == $NODE{""}
380 or Carp::croak "$port: rcv can only be called on local ports, caught"; 380 or Carp::croak "$port: rcv can only be called on local ports, caught";
381 381
382 while (@_) { 382 while (@_) {
383 if (ref $_[0]) { 383 if (ref $_[0]) {
384 if (my $self = $PORT_DATA{$portid}) { 384 if (my $self = $PORT_DATA{$portid}) {
… …
475 475
476Monitor the given port and do something when the port is killed or 476Monitor the given port and do something when the port is killed or
477messages to it were lost, and optionally return a guard that can be used 477messages to it were lost, and optionally return a guard that can be used
478to stop monitoring again. 478to stop monitoring again.
479 479
480In the first form (callback), the callback is simply called with any
481number of C<@reason> elements (no @reason means that the port was deleted
482"normally"). Note also that I<< the callback B<must> never die >>, so use
483C<eval> if unsure.
484
485In the second form (another port given), the other port (C<$rcvport>)
486will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
487"normal" kils nothing happens, while under all other conditions, the other
488port is killed with the same reason.
489
490The third form (kill self) is the same as the second form, except that
491C<$rvport> defaults to C<$SELF>.
492
493In the last form (message), a message of the form C<@msg, @reason> will be
494C<snd>.
495
496Monitoring-actions are one-shot: once messages are lost (and a monitoring
497alert was raised), they are removed and will not trigger again.
498
499As a rule of thumb, monitoring requests should always monitor a port from
500a local port (or callback). The reason is that kill messages might get
501lost, just like any other message. Another less obvious reason is that
502even monitoring requests can get lost (for example, when the connection
503to the other node goes down permanently). When monitoring a port locally
504these problems do not exist.
505
480C<mon> effectively guarantees that, in the absence of hardware failures, 506C<mon> effectively guarantees that, in the absence of hardware failures,
481after starting the monitor, either all messages sent to the port will 507after starting the monitor, either all messages sent to the port will
482arrive, or the monitoring action will be invoked after possible message 508arrive, or the monitoring action will be invoked after possible message
483loss has been detected. No messages will be lost "in between" (after 509loss has been detected. No messages will be lost "in between" (after
484the first lost message no further messages will be received by the 510the first lost message no further messages will be received by the
485port). After the monitoring action was invoked, further messages might get 511port). After the monitoring action was invoked, further messages might get
486delivered again. 512delivered again.
487 513
488Note that monitoring-actions are one-shot: once messages are lost (and a 514Inter-host-connection timeouts and monitoring depend on the transport
489monitoring alert was raised), they are removed and will not trigger again. 515used. The only transport currently implemented is TCP, and AnyEvent::MP
516relies on TCP to detect node-downs (this can take 10-15 minutes on a
517non-idle connection, and usually around two hours for idle conenctions).
490 518
491In the first form (callback), the callback is simply called with any 519This means that monitoring is good for program errors and cleaning up
492number of C<@reason> elements (no @reason means that the port was deleted 520stuff eventually, but they are no replacement for a timeout when you need
493"normally"). Note also that I<< the callback B<must> never die >>, so use 521to ensure some maximum latency.
494C<eval> if unsure.
495
496In the second form (another port given), the other port (C<$rcvport>)
497will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
498"normal" kils nothing happens, while under all other conditions, the other
499port is killed with the same reason.
500
501The third form (kill self) is the same as the second form, except that
502C<$rvport> defaults to C<$SELF>.
503
504In the last form (message), a message of the form C<@msg, @reason> will be
505C<snd>.
506
507As a rule of thumb, monitoring requests should always monitor a port from
508a local port (or callback). The reason is that kill messages might get
509lost, just like any other message. Another less obvious reason is that
510even monitoring requests can get lost (for exmaple, when the connection
511to the other node goes down permanently). When monitoring a port locally
512these problems do not exist.
513 522
514Example: call a given callback when C<$port> is killed. 523Example: call a given callback when C<$port> is killed.
515 524
516 mon $port, sub { warn "port died because of <@_>\n" }; 525 mon $port, sub { warn "port died because of <@_>\n" };
517 526
… …
524 mon $port, $self => "restart"; 533 mon $port, $self => "restart";
525 534
526=cut 535=cut
527 536
528sub mon { 537sub mon {
529 my ($noderef, $port) = split /#/, shift, 2; 538 my ($nodeid, $port) = split /#/, shift, 2;
530 539
531 my $node = $NODE{$noderef} || add_node $noderef; 540 my $node = $NODE{$nodeid} || add_node $nodeid;
532 541
533 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 542 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
534 543
535 unless (ref $cb) { 544 unless (ref $cb) {
536 if (@_) { 545 if (@_) {
… …
619A common idiom is to pass a local port, immediately monitor the spawned 628A common idiom is to pass a local port, immediately monitor the spawned
620port, and in the remote init function, immediately monitor the passed 629port, and in the remote init function, immediately monitor the passed
621local port. This two-way monitoring ensures that both ports get cleaned up 630local port. This two-way monitoring ensures that both ports get cleaned up
622when there is a problem. 631when there is a problem.
623 632
633C<spawn> guarantees that the C<$initfunc> has no visible effects on the
634caller before C<spawn> returns (by delaying invocation when spawn is
635called for the local node).
636
624Example: spawn a chat server port on C<$othernode>. 637Example: spawn a chat server port on C<$othernode>.
625 638
626 # this node, executed from within a port context: 639 # this node, executed from within a port context:
627 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 640 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
628 mon $server; 641 mon $server;
… …
650 }; 663 };
651 _self_die if $@; 664 _self_die if $@;
652} 665}
653 666
654sub spawn(@) { 667sub spawn(@) {
655 my ($noderef, undef) = split /#/, shift, 2; 668 my ($nodeid, undef) = split /#/, shift, 2;
656 669
657 my $id = "$RUNIQ." . $ID++; 670 my $id = "$RUNIQ." . $ID++;
658 671
659 $_[0] =~ /::/ 672 $_[0] =~ /::/
660 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 673 or Carp::croak "spawn init function must be a fully-qualified name, caught";
661 674
662 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 675 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
663 676
664 "$noderef#$id" 677 "$nodeid#$id"
665} 678}
666 679
667=item after $timeout, @msg 680=item after $timeout, @msg
668 681
669=item after $timeout, $callback 682=item after $timeout, $callback
… …
708 721
709=item * Node IDs are arbitrary strings in AEMP. 722=item * Node IDs are arbitrary strings in AEMP.
710 723
711Erlang relies on special naming and DNS to work everywhere in the same 724Erlang relies on special naming and DNS to work everywhere in the same
712way. AEMP relies on each node somehow knowing its own address(es) (e.g. by 725way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
713configuraiton or DNS), but will otherwise discover other odes itself. 726configuration or DNS), but will otherwise discover other odes itself.
714 727
715=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 728=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
716uses "local ports are like remote ports". 729uses "local ports are like remote ports".
717 730
718The failure modes for local ports are quite different (runtime errors 731The failure modes for local ports are quite different (runtime errors
… …
731 744
732Erlang uses processes that selectively receive messages, and therefore 745Erlang uses processes that selectively receive messages, and therefore
733needs a queue. AEMP is event based, queuing messages would serve no 746needs a queue. AEMP is event based, queuing messages would serve no
734useful purpose. For the same reason the pattern-matching abilities of 747useful purpose. For the same reason the pattern-matching abilities of
735AnyEvent::MP are more limited, as there is little need to be able to 748AnyEvent::MP are more limited, as there is little need to be able to
736filter messages without dequeing them. 749filter messages without dequeuing them.
737 750
738(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 751(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
739 752
740=item * Erlang sends are synchronous, AEMP sends are asynchronous. 753=item * Erlang sends are synchronous, AEMP sends are asynchronous.
741 754

Diff Legend

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