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.74 by root, Mon Aug 31 11:11:27 2009 UTC vs.
Revision 1.78 by root, Thu Sep 3 20:16:36 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;
… …
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 API, protocol not yet final.
48 47
49 stay tuned. 48 stay tuned.
50 49
… …
55Despite its simplicity, you can securely message other processes running 54Despite its simplicity, you can securely message other processes running
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
61At the moment, this module family is a bit underdocumented.
62 59
63=head1 CONCEPTS 60=head1 CONCEPTS
64 61
65=over 4 62=over 4
66 63
… …
161 158
162=item $nodeid = node_of $port 159=item $nodeid = node_of $port
163 160
164Extracts and returns the node ID from a port ID or a node ID. 161Extracts and returns the node ID from a port ID or a node ID.
165 162
163=item configure $profile, key => value...
164
166=item configure key => value... 165=item configure key => value...
167 166
168Before a node can talk to other nodes on the network (i.e. enter 167Before 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 168"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 169to know is its own name, and optionally it should know the addresses of
… …
177 176
178=item step 1, gathering configuration from profiles 177=item step 1, gathering configuration from profiles
179 178
180The function first looks up a profile in the aemp configuration (see the 179The function first looks up a profile in the aemp configuration (see the
181L<aemp> commandline utility). The profile name can be specified via the 180L<aemp> commandline utility). The profile name can be specified via the
182named C<profile> parameter. If it is missing, then the nodename (F<uname 181named C<profile> parameter or can simply be the first parameter). If it is
183-n>) will be used as profile name. 182missing, then the nodename (F<uname -n>) will be used as profile name.
184 183
185The profile data is then gathered as follows: 184The profile data is then gathered as follows:
186 185
187First, all remaining key => value pairs (all of which are conviniently 186First, all remaining key => value pairs (all of which are conveniently
188undocumented at the moment) will be interpreted as configuration 187undocumented at the moment) will be interpreted as configuration
189data. Then they will be overwritten by any values specified in the global 188data. Then they will be overwritten by any values specified in the global
190default configuration (see the F<aemp> utility), then the chain of 189default configuration (see the F<aemp> utility), then the chain of
191profiles chosen by the profile name (and any C<parent> attributes). 190profiles chosen by the profile name (and any C<parent> attributes).
192 191
… …
372 371
373=cut 372=cut
374 373
375sub rcv($@) { 374sub rcv($@) {
376 my $port = shift; 375 my $port = shift;
377 my ($noderef, $portid) = split /#/, $port, 2; 376 my ($nodeid, $portid) = split /#/, $port, 2;
378 377
379 $NODE{$noderef} == $NODE{""} 378 $NODE{$nodeid} == $NODE{""}
380 or Carp::croak "$port: rcv can only be called on local ports, caught"; 379 or Carp::croak "$port: rcv can only be called on local ports, caught";
381 380
382 while (@_) { 381 while (@_) {
383 if (ref $_[0]) { 382 if (ref $_[0]) {
384 if (my $self = $PORT_DATA{$portid}) { 383 if (my $self = $PORT_DATA{$portid}) {
… …
492number of C<@reason> elements (no @reason means that the port was deleted 491number of C<@reason> elements (no @reason means that the port was deleted
493"normally"). Note also that I<< the callback B<must> never die >>, so use 492"normally"). Note also that I<< the callback B<must> never die >>, so use
494C<eval> if unsure. 493C<eval> if unsure.
495 494
496In the second form (another port given), the other port (C<$rcvport>) 495In 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 496will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
498"normal" kils nothing happens, while under all other conditions, the other 497"normal" kils nothing happens, while under all other conditions, the other
499port is killed with the same reason. 498port is killed with the same reason.
500 499
501The third form (kill self) is the same as the second form, except that 500The third form (kill self) is the same as the second form, except that
502C<$rvport> defaults to C<$SELF>. 501C<$rvport> defaults to C<$SELF>.
… …
505C<snd>. 504C<snd>.
506 505
507As a rule of thumb, monitoring requests should always monitor a port from 506As 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 507a local port (or callback). The reason is that kill messages might get
509lost, just like any other message. Another less obvious reason is that 508lost, just like any other message. Another less obvious reason is that
510even monitoring requests can get lost (for exmaple, when the connection 509even monitoring requests can get lost (for example, when the connection
511to the other node goes down permanently). When monitoring a port locally 510to the other node goes down permanently). When monitoring a port locally
512these problems do not exist. 511these problems do not exist.
513 512
514Example: call a given callback when C<$port> is killed. 513Example: call a given callback when C<$port> is killed.
515 514
… …
524 mon $port, $self => "restart"; 523 mon $port, $self => "restart";
525 524
526=cut 525=cut
527 526
528sub mon { 527sub mon {
529 my ($noderef, $port) = split /#/, shift, 2; 528 my ($nodeid, $port) = split /#/, shift, 2;
530 529
531 my $node = $NODE{$noderef} || add_node $noderef; 530 my $node = $NODE{$nodeid} || add_node $nodeid;
532 531
533 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 532 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
534 533
535 unless (ref $cb) { 534 unless (ref $cb) {
536 if (@_) { 535 if (@_) {
… …
650 }; 649 };
651 _self_die if $@; 650 _self_die if $@;
652} 651}
653 652
654sub spawn(@) { 653sub spawn(@) {
655 my ($noderef, undef) = split /#/, shift, 2; 654 my ($nodeid, undef) = split /#/, shift, 2;
656 655
657 my $id = "$RUNIQ." . $ID++; 656 my $id = "$RUNIQ." . $ID++;
658 657
659 $_[0] =~ /::/ 658 $_[0] =~ /::/
660 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 659 or Carp::croak "spawn init function must be a fully-qualified name, caught";
661 660
662 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 661 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
663 662
664 "$noderef#$id" 663 "$nodeid#$id"
665} 664}
666 665
667=item after $timeout, @msg 666=item after $timeout, @msg
668 667
669=item after $timeout, $callback 668=item after $timeout, $callback
… …
708 707
709=item * Node IDs are arbitrary strings in AEMP. 708=item * Node IDs are arbitrary strings in AEMP.
710 709
711Erlang relies on special naming and DNS to work everywhere in the same 710Erlang 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 711way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
713configuraiton or DNS), but will otherwise discover other odes itself. 712configuration or DNS), but will otherwise discover other odes itself.
714 713
715=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 714=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
716uses "local ports are like remote ports". 715uses "local ports are like remote ports".
717 716
718The failure modes for local ports are quite different (runtime errors 717The failure modes for local ports are quite different (runtime errors
… …
731 730
732Erlang uses processes that selectively receive messages, and therefore 731Erlang uses processes that selectively receive messages, and therefore
733needs a queue. AEMP is event based, queuing messages would serve no 732needs a queue. AEMP is event based, queuing messages would serve no
734useful purpose. For the same reason the pattern-matching abilities of 733useful purpose. For the same reason the pattern-matching abilities of
735AnyEvent::MP are more limited, as there is little need to be able to 734AnyEvent::MP are more limited, as there is little need to be able to
736filter messages without dequeing them. 735filter messages without dequeuing them.
737 736
738(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 737(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
739 738
740=item * Erlang sends are synchronous, AEMP sends are asynchronous. 739=item * Erlang sends are synchronous, AEMP sends are asynchronous.
741 740

Diff Legend

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