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.87 by root, Fri Sep 11 02:32:23 2009 UTC vs.
Revision 1.100 by root, Fri Oct 2 20:41:56 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent::MP - multi-processing/message-passing framework 3AnyEvent::MP - erlang-style multi-processing/message-passing framework
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::MP; 7 use AnyEvent::MP;
8 8
… …
31 31
32 # create a port on another node 32 # create a port on another node
33 my $port = spawn $node, $initfunc, @initdata; 33 my $port = spawn $node, $initfunc, @initdata;
34 34
35 # monitoring 35 # monitoring
36 mon $port, $cb->(@msg) # callback is invoked on death 36 mon $localport, $cb->(@msg) # callback is invoked on death
37 mon $port, $otherport # kill otherport on abnormal death 37 mon $localport, $otherport # kill otherport on abnormal death
38 mon $port, $otherport, @msg # send message on death 38 mon $localport, $otherport, @msg # send message on death
39 39
40=head1 CURRENT STATUS 40=head1 CURRENT STATUS
41 41
42 bin/aemp - stable. 42 bin/aemp - stable.
43 AnyEvent::MP - stable API, should work. 43 AnyEvent::MP - stable API, should work.
44 AnyEvent::MP::Intro - explains most concepts. 44 AnyEvent::MP::Intro - explains most concepts.
45 AnyEvent::MP::Kernel - mostly stable. 45 AnyEvent::MP::Kernel - mostly stable API.
46 AnyEvent::MP::Global - stable but incomplete, protocol not yet final. 46 AnyEvent::MP::Global - stable API.
47
48stay tuned.
49 47
50=head1 DESCRIPTION 48=head1 DESCRIPTION
51 49
52This module (-family) implements a simple message passing framework. 50This module (-family) implements a simple message passing framework.
53 51
… …
118seed node that blocks for long periods will slow down everybody else. 116seed node that blocks for long periods will slow down everybody else.
119 117
120=item seeds - C<host:port> 118=item seeds - C<host:port>
121 119
122Seeds are transport endpoint(s) (usually a hostname/IP address and a 120Seeds are transport endpoint(s) (usually a hostname/IP address and a
123TCP port) of nodes thta should be used as seed nodes. 121TCP port) of nodes that should be used as seed nodes.
124 122
125The nodes listening on those endpoints are expected to be long-running, 123The nodes listening on those endpoints are expected to be long-running,
126and at least one of those should always be available. When nodes run out 124and at least one of those should always be available. When nodes run out
127of connections (e.g. due to a network error), they try to re-establish 125of connections (e.g. due to a network error), they try to re-establish
128connections to some seednodes again to join the network. 126connections to some seednodes again to join the network.
… …
145 143
146use AE (); 144use AE ();
147 145
148use base "Exporter"; 146use base "Exporter";
149 147
150our $VERSION = $AnyEvent::MP::Kernel::VERSION; 148our $VERSION = 1.21;
151 149
152our @EXPORT = qw( 150our @EXPORT = qw(
153 NODE $NODE *SELF node_of after 151 NODE $NODE *SELF node_of after
154 configure 152 configure
155 snd rcv mon mon_guard kil reg psub spawn cal 153 snd rcv mon mon_guard kil psub spawn cal
156 port 154 port
157); 155);
158 156
159our $SELF; 157our $SELF;
160 158
… …
525delivered again. 523delivered again.
526 524
527Inter-host-connection timeouts and monitoring depend on the transport 525Inter-host-connection timeouts and monitoring depend on the transport
528used. The only transport currently implemented is TCP, and AnyEvent::MP 526used. The only transport currently implemented is TCP, and AnyEvent::MP
529relies on TCP to detect node-downs (this can take 10-15 minutes on a 527relies on TCP to detect node-downs (this can take 10-15 minutes on a
530non-idle connection, and usually around two hours for idle conenctions). 528non-idle connection, and usually around two hours for idle connections).
531 529
532This means that monitoring is good for program errors and cleaning up 530This means that monitoring is good for program errors and cleaning up
533stuff eventually, but they are no replacement for a timeout when you need 531stuff eventually, but they are no replacement for a timeout when you need
534to ensure some maximum latency. 532to ensure some maximum latency.
535 533
… …
567 } 565 }
568 566
569 $node->monitor ($port, $cb); 567 $node->monitor ($port, $cb);
570 568
571 defined wantarray 569 defined wantarray
572 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 570 and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
573} 571}
574 572
575=item $guard = mon_guard $port, $ref, $ref... 573=item $guard = mon_guard $port, $ref, $ref...
576 574
577Monitors the given C<$port> and keeps the passed references. When the port 575Monitors the given C<$port> and keeps the passed references. When the port
… …
729 727
730If an optional time-out (in seconds) is given and it is not C<undef>, 728If an optional time-out (in seconds) is given and it is not C<undef>,
731then the callback will be called without any arguments after the time-out 729then the callback will be called without any arguments after the time-out
732elapsed and the port is C<kil>ed. 730elapsed and the port is C<kil>ed.
733 731
734If no time-out is given, then the local port will monitor the remote port 732If no time-out is given (or it is C<undef>), then the local port will
735instead, so it eventually gets cleaned-up. 733monitor the remote port instead, so it eventually gets cleaned-up.
736 734
737Currently this function returns the temporary port, but this "feature" 735Currently this function returns the temporary port, but this "feature"
738might go in future versions unless you can make a convincing case that 736might go in future versions unless you can make a convincing case that
739this is indeed useful for something. 737this is indeed useful for something.
740 738
… …
776AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 774AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
777== aemp node, Erlang process == aemp port), so many of the documents and 775== aemp node, Erlang process == aemp port), so many of the documents and
778programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 776programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
779sample: 777sample:
780 778
781 http://www.Erlang.se/doc/programming_rules.shtml 779 http://www.erlang.se/doc/programming_rules.shtml
782 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 780 http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
783 http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6 781 http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6
784 http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 782 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
785 783
786Despite the similarities, there are also some important differences: 784Despite the similarities, there are also some important differences:
787 785
788=over 4 786=over 4
789 787
790=item * Node IDs are arbitrary strings in AEMP. 788=item * Node IDs are arbitrary strings in AEMP.
791 789
792Erlang relies on special naming and DNS to work everywhere in the same 790Erlang relies on special naming and DNS to work everywhere in the same
793way. AEMP relies on each node somehow knowing its own address(es) (e.g. by 791way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
794configuration or DNS), but will otherwise discover other odes itself. 792configuration or DNS), and possibly the addresses of some seed nodes, but
793will otherwise discover other nodes (and their IDs) itself.
795 794
796=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 795=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
797uses "local ports are like remote ports". 796uses "local ports are like remote ports".
798 797
799The failure modes for local ports are quite different (runtime errors 798The failure modes for local ports are quite different (runtime errors
… …
824so does not need a queue that can overflow). AEMP sends are immediate, 823so does not need a queue that can overflow). AEMP sends are immediate,
825connection establishment is handled in the background. 824connection establishment is handled in the background.
826 825
827=item * Erlang suffers from silent message loss, AEMP does not. 826=item * Erlang suffers from silent message loss, AEMP does not.
828 827
829Erlang makes few guarantees on messages delivery - messages can get lost 828Erlang implements few guarantees on messages delivery - messages can get
830without any of the processes realising it (i.e. you send messages a, b, 829lost without any of the processes realising it (i.e. you send messages a,
831and c, and the other side only receives messages a and c). 830b, and c, and the other side only receives messages a and c).
832 831
833AEMP guarantees correct ordering, and the guarantee that after one message 832AEMP guarantees correct ordering, and the guarantee that after one message
834is lost, all following ones sent to the same port are lost as well, until 833is lost, all following ones sent to the same port are lost as well, until
835monitoring raises an error, so there are no silent "holes" in the message 834monitoring raises an error, so there are no silent "holes" in the message
836sequence. 835sequence.

Diff Legend

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