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.88 by root, Fri Sep 11 15:02:17 2009 UTC vs.
Revision 1.99 by root, Fri Oct 2 14:12:16 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.
… …
116seed node that blocks for long periods will slow down everybody else. 116seed node that blocks for long periods will slow down everybody else.
117 117
118=item seeds - C<host:port> 118=item seeds - C<host:port>
119 119
120Seeds are transport endpoint(s) (usually a hostname/IP address and a 120Seeds are transport endpoint(s) (usually a hostname/IP address and a
121TCP port) of nodes thta should be used as seed nodes. 121TCP port) of nodes that should be used as seed nodes.
122 122
123The nodes listening on those endpoints are expected to be long-running, 123The nodes listening on those endpoints are expected to be long-running,
124and 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
125of 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
126connections to some seednodes again to join the network. 126connections to some seednodes again to join the network.
… …
143 143
144use AE (); 144use AE ();
145 145
146use base "Exporter"; 146use base "Exporter";
147 147
148our $VERSION = $AnyEvent::MP::Kernel::VERSION; 148our $VERSION = 1.2;
149 149
150our @EXPORT = qw( 150our @EXPORT = qw(
151 NODE $NODE *SELF node_of after 151 NODE $NODE *SELF node_of after
152 configure 152 configure
153 snd rcv mon mon_guard kil reg psub spawn cal 153 snd rcv mon mon_guard kil psub spawn cal
154 port 154 port
155); 155);
156 156
157our $SELF; 157our $SELF;
158 158
… …
523delivered again. 523delivered again.
524 524
525Inter-host-connection timeouts and monitoring depend on the transport 525Inter-host-connection timeouts and monitoring depend on the transport
526used. The only transport currently implemented is TCP, and AnyEvent::MP 526used. The only transport currently implemented is TCP, and AnyEvent::MP
527relies 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
528non-idle connection, and usually around two hours for idle conenctions). 528non-idle connection, and usually around two hours for idle connections).
529 529
530This means that monitoring is good for program errors and cleaning up 530This means that monitoring is good for program errors and cleaning up
531stuff 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
532to ensure some maximum latency. 532to ensure some maximum latency.
533 533
… …
565 } 565 }
566 566
567 $node->monitor ($port, $cb); 567 $node->monitor ($port, $cb);
568 568
569 defined wantarray 569 defined wantarray
570 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 570 and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
571} 571}
572 572
573=item $guard = mon_guard $port, $ref, $ref... 573=item $guard = mon_guard $port, $ref, $ref...
574 574
575Monitors 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
… …
727 727
728If 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>,
729then 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
730elapsed and the port is C<kil>ed. 730elapsed and the port is C<kil>ed.
731 731
732If 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
733instead, so it eventually gets cleaned-up. 733monitor the remote port instead, so it eventually gets cleaned-up.
734 734
735Currently this function returns the temporary port, but this "feature" 735Currently this function returns the temporary port, but this "feature"
736might 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
737this is indeed useful for something. 737this is indeed useful for something.
738 738
… …
774AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 774AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
775== 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
776programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 776programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
777sample: 777sample:
778 778
779 http://www.Erlang.se/doc/programming_rules.shtml 779 http://www.erlang.se/doc/programming_rules.shtml
780 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
781 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
782 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
783 783
784Despite the similarities, there are also some important differences: 784Despite the similarities, there are also some important differences:
785 785
786=over 4 786=over 4
787 787
788=item * Node IDs are arbitrary strings in AEMP. 788=item * Node IDs are arbitrary strings in AEMP.
789 789
790Erlang 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
791way. 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
792configuration 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.
793 794
794=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
795uses "local ports are like remote ports". 796uses "local ports are like remote ports".
796 797
797The failure modes for local ports are quite different (runtime errors 798The failure modes for local ports are quite different (runtime errors
… …
822so 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,
823connection establishment is handled in the background. 824connection establishment is handled in the background.
824 825
825=item * Erlang suffers from silent message loss, AEMP does not. 826=item * Erlang suffers from silent message loss, AEMP does not.
826 827
827Erlang makes few guarantees on messages delivery - messages can get lost 828Erlang implements few guarantees on messages delivery - messages can get
828without 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,
829and c, and the other side only receives messages a and c). 830b, and c, and the other side only receives messages a and c).
830 831
831AEMP guarantees correct ordering, and the guarantee that after one message 832AEMP guarantees correct ordering, and the guarantee that after one message
832is 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
833monitoring 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
834sequence. 835sequence.

Diff Legend

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