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.77 by elmex, Thu Sep 3 07:57:30 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
… …
182named C<profile> parameter. If it is missing, then the nodename (F<uname 179named C<profile> parameter. If it is missing, then the nodename (F<uname
183-n>) will be used as profile name. 180-n>) will be used as profile name.
184 181
185The profile data is then gathered as follows: 182The profile data is then gathered as follows:
186 183
187First, all remaining key => value pairs (all of which are conviniently 184First, all remaining key => value pairs (all of which are conveniently
188undocumented at the moment) will be interpreted as configuration 185undocumented at the moment) will be interpreted as configuration
189data. Then they will be overwritten by any values specified in the global 186data. Then they will be overwritten by any values specified in the global
190default configuration (see the F<aemp> utility), then the chain of 187default configuration (see the F<aemp> utility), then the chain of
191profiles chosen by the profile name (and any C<parent> attributes). 188profiles chosen by the profile name (and any C<parent> attributes).
192 189
… …
372 369
373=cut 370=cut
374 371
375sub rcv($@) { 372sub rcv($@) {
376 my $port = shift; 373 my $port = shift;
377 my ($noderef, $portid) = split /#/, $port, 2; 374 my ($nodeid, $portid) = split /#/, $port, 2;
378 375
379 $NODE{$noderef} == $NODE{""} 376 $NODE{$nodeid} == $NODE{""}
380 or Carp::croak "$port: rcv can only be called on local ports, caught"; 377 or Carp::croak "$port: rcv can only be called on local ports, caught";
381 378
382 while (@_) { 379 while (@_) {
383 if (ref $_[0]) { 380 if (ref $_[0]) {
384 if (my $self = $PORT_DATA{$portid}) { 381 if (my $self = $PORT_DATA{$portid}) {
… …
492number of C<@reason> elements (no @reason means that the port was deleted 489number 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 490"normally"). Note also that I<< the callback B<must> never die >>, so use
494C<eval> if unsure. 491C<eval> if unsure.
495 492
496In the second form (another port given), the other port (C<$rcvport>) 493In 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 494will 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 495"normal" kils nothing happens, while under all other conditions, the other
499port is killed with the same reason. 496port is killed with the same reason.
500 497
501The third form (kill self) is the same as the second form, except that 498The third form (kill self) is the same as the second form, except that
502C<$rvport> defaults to C<$SELF>. 499C<$rvport> defaults to C<$SELF>.
… …
505C<snd>. 502C<snd>.
506 503
507As a rule of thumb, monitoring requests should always monitor a port from 504As 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 505a local port (or callback). The reason is that kill messages might get
509lost, just like any other message. Another less obvious reason is that 506lost, just like any other message. Another less obvious reason is that
510even monitoring requests can get lost (for exmaple, when the connection 507even monitoring requests can get lost (for example, when the connection
511to the other node goes down permanently). When monitoring a port locally 508to the other node goes down permanently). When monitoring a port locally
512these problems do not exist. 509these problems do not exist.
513 510
514Example: call a given callback when C<$port> is killed. 511Example: call a given callback when C<$port> is killed.
515 512
… …
524 mon $port, $self => "restart"; 521 mon $port, $self => "restart";
525 522
526=cut 523=cut
527 524
528sub mon { 525sub mon {
529 my ($noderef, $port) = split /#/, shift, 2; 526 my ($nodeid, $port) = split /#/, shift, 2;
530 527
531 my $node = $NODE{$noderef} || add_node $noderef; 528 my $node = $NODE{$nodeid} || add_node $nodeid;
532 529
533 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 530 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
534 531
535 unless (ref $cb) { 532 unless (ref $cb) {
536 if (@_) { 533 if (@_) {
… …
650 }; 647 };
651 _self_die if $@; 648 _self_die if $@;
652} 649}
653 650
654sub spawn(@) { 651sub spawn(@) {
655 my ($noderef, undef) = split /#/, shift, 2; 652 my ($nodeid, undef) = split /#/, shift, 2;
656 653
657 my $id = "$RUNIQ." . $ID++; 654 my $id = "$RUNIQ." . $ID++;
658 655
659 $_[0] =~ /::/ 656 $_[0] =~ /::/
660 or Carp::croak "spawn init function must be a fully-qualified name, caught"; 657 or Carp::croak "spawn init function must be a fully-qualified name, caught";
661 658
662 snd_to_func $noderef, "AnyEvent::MP::_spawn" => $id, @_; 659 snd_to_func $nodeid, "AnyEvent::MP::_spawn" => $id, @_;
663 660
664 "$noderef#$id" 661 "$nodeid#$id"
665} 662}
666 663
667=item after $timeout, @msg 664=item after $timeout, @msg
668 665
669=item after $timeout, $callback 666=item after $timeout, $callback
… …
708 705
709=item * Node IDs are arbitrary strings in AEMP. 706=item * Node IDs are arbitrary strings in AEMP.
710 707
711Erlang relies on special naming and DNS to work everywhere in the same 708Erlang 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 709way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
713configuraiton or DNS), but will otherwise discover other odes itself. 710configuration or DNS), but will otherwise discover other odes itself.
714 711
715=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 712=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
716uses "local ports are like remote ports". 713uses "local ports are like remote ports".
717 714
718The failure modes for local ports are quite different (runtime errors 715The failure modes for local ports are quite different (runtime errors
… …
731 728
732Erlang uses processes that selectively receive messages, and therefore 729Erlang uses processes that selectively receive messages, and therefore
733needs a queue. AEMP is event based, queuing messages would serve no 730needs a queue. AEMP is event based, queuing messages would serve no
734useful purpose. For the same reason the pattern-matching abilities of 731useful purpose. For the same reason the pattern-matching abilities of
735AnyEvent::MP are more limited, as there is little need to be able to 732AnyEvent::MP are more limited, as there is little need to be able to
736filter messages without dequeing them. 733filter messages without dequeuing them.
737 734
738(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP). 735(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
739 736
740=item * Erlang sends are synchronous, AEMP sends are asynchronous. 737=item * Erlang sends are synchronous, AEMP sends are asynchronous.
741 738

Diff Legend

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