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.94 by root, Tue Sep 22 14:14:43 2009 UTC vs.
Revision 1.101 by root, Tue Oct 6 01:31:22 2009 UTC

… …
30 rcv $port, pong => sub { warn "pong received\n" }; 30 rcv $port, pong => sub { warn "pong received\n" };
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 # destroy a prot again
36 kil $port; # "normal" kill
37 kil $port, my_error => "everything is broken"; # error kill
38
35 # monitoring 39 # monitoring
36 mon $localport, $cb->(@msg) # callback is invoked on death 40 mon $localport, $cb->(@msg) # callback is invoked on death
37 mon $localport, $otherport # kill otherport on abnormal death 41 mon $localport, $otherport # kill otherport on abnormal death
38 mon $localport, $otherport, @msg # send message on death 42 mon $localport, $otherport, @msg # send message on death
43
44 # temporarily execute code in port context
45 peval $port, sub { die "kill the port!" };
46
47 # execute callbacks in $SELF port context
48 my $timer = AE::timer 1, 0, psub {
49 die "kill the port, delayed";
50 };
39 51
40=head1 CURRENT STATUS 52=head1 CURRENT STATUS
41 53
42 bin/aemp - stable. 54 bin/aemp - stable.
43 AnyEvent::MP - stable API, should work. 55 AnyEvent::MP - stable API, should work.
… …
116seed node that blocks for long periods will slow down everybody else. 128seed node that blocks for long periods will slow down everybody else.
117 129
118=item seeds - C<host:port> 130=item seeds - C<host:port>
119 131
120Seeds are transport endpoint(s) (usually a hostname/IP address and a 132Seeds are transport endpoint(s) (usually a hostname/IP address and a
121TCP port) of nodes thta should be used as seed nodes. 133TCP port) of nodes that should be used as seed nodes.
122 134
123The nodes listening on those endpoints are expected to be long-running, 135The 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 136and 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 137of connections (e.g. due to a network error), they try to re-establish
126connections to some seednodes again to join the network. 138connections to some seednodes again to join the network.
… …
143 155
144use AE (); 156use AE ();
145 157
146use base "Exporter"; 158use base "Exporter";
147 159
148our $VERSION = $AnyEvent::MP::Kernel::VERSION; 160our $VERSION = 1.21;
149 161
150our @EXPORT = qw( 162our @EXPORT = qw(
151 NODE $NODE *SELF node_of after 163 NODE $NODE *SELF node_of after
152 configure 164 configure
153 snd rcv mon mon_guard kil psub spawn cal 165 snd rcv mon mon_guard kil psub peval spawn cal
154 port 166 port
155); 167);
156 168
157our $SELF; 169our $SELF;
158 170
… …
436 } 448 }
437 449
438 $port 450 $port
439} 451}
440 452
453=item peval $port, $coderef[, @args]
454
455Evaluates the given C<$codref> within the contetx of C<$port>, that is,
456when the code throews an exception the C<$port> will be killed.
457
458Any remaining args will be passed to the callback. Any return values will
459be returned to the caller.
460
461This is useful when you temporarily want to execute code in the context of
462a port.
463
464Example: create a port and run some initialisation code in it's context.
465
466 my $port = port { ... };
467
468 peval $port, sub {
469 init
470 or die "unable to init";
471 };
472
473=cut
474
475sub peval($$) {
476 local $SELF = shift;
477 my $cb = shift;
478
479 if (wantarray) {
480 my @res = eval { &$cb };
481 _self_die if $@;
482 @res
483 } else {
484 my $res = eval { &$cb };
485 _self_die if $@;
486 $res
487 }
488}
489
441=item $closure = psub { BLOCK } 490=item $closure = psub { BLOCK }
442 491
443Remembers C<$SELF> and creates a closure out of the BLOCK. When the 492Remembers C<$SELF> and creates a closure out of the BLOCK. When the
444closure is executed, sets up the environment in the same way as in C<rcv> 493closure is executed, sets up the environment in the same way as in C<rcv>
445callbacks, i.e. runtime errors will cause the port to get C<kil>ed. 494callbacks, i.e. runtime errors will cause the port to get C<kil>ed.
495
496The effect is basically as if it returned C<< sub { peval $SELF, sub {
497BLOCK } } >>.
446 498
447This is useful when you register callbacks from C<rcv> callbacks: 499This is useful when you register callbacks from C<rcv> callbacks:
448 500
449 rcv delayed_reply => sub { 501 rcv delayed_reply => sub {
450 my ($delay, @reply) = @_; 502 my ($delay, @reply) = @_;
… …
523delivered again. 575delivered again.
524 576
525Inter-host-connection timeouts and monitoring depend on the transport 577Inter-host-connection timeouts and monitoring depend on the transport
526used. The only transport currently implemented is TCP, and AnyEvent::MP 578used. 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 579relies 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). 580non-idle connection, and usually around two hours for idle connections).
529 581
530This means that monitoring is good for program errors and cleaning up 582This means that monitoring is good for program errors and cleaning up
531stuff eventually, but they are no replacement for a timeout when you need 583stuff eventually, but they are no replacement for a timeout when you need
532to ensure some maximum latency. 584to ensure some maximum latency.
533 585
… …
727 779
728If an optional time-out (in seconds) is given and it is not C<undef>, 780If 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 781then the callback will be called without any arguments after the time-out
730elapsed and the port is C<kil>ed. 782elapsed and the port is C<kil>ed.
731 783
732If no time-out is given, then the local port will monitor the remote port 784If no time-out is given (or it is C<undef>), then the local port will
733instead, so it eventually gets cleaned-up. 785monitor the remote port instead, so it eventually gets cleaned-up.
734 786
735Currently this function returns the temporary port, but this "feature" 787Currently this function returns the temporary port, but this "feature"
736might go in future versions unless you can make a convincing case that 788might go in future versions unless you can make a convincing case that
737this is indeed useful for something. 789this is indeed useful for something.
738 790
… …
774AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 826AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
775== aemp node, Erlang process == aemp port), so many of the documents and 827== aemp node, Erlang process == aemp port), so many of the documents and
776programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 828programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
777sample: 829sample:
778 830
779 http://www.Erlang.se/doc/programming_rules.shtml 831 http://www.erlang.se/doc/programming_rules.shtml
780 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 832 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 833 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 834 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
783 835
784Despite the similarities, there are also some important differences: 836Despite the similarities, there are also some important differences:
785 837
786=over 4 838=over 4
787 839
788=item * Node IDs are arbitrary strings in AEMP. 840=item * Node IDs are arbitrary strings in AEMP.
789 841
790Erlang relies on special naming and DNS to work everywhere in the same 842Erlang 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 843way. AEMP relies on each node somehow knowing its own address(es) (e.g. by
792configuration or DNS), but will otherwise discover other odes itself. 844configuration or DNS), and possibly the addresses of some seed nodes, but
845will otherwise discover other nodes (and their IDs) itself.
793 846
794=item * Erlang has a "remote ports are like local ports" philosophy, AEMP 847=item * Erlang has a "remote ports are like local ports" philosophy, AEMP
795uses "local ports are like remote ports". 848uses "local ports are like remote ports".
796 849
797The failure modes for local ports are quite different (runtime errors 850The failure modes for local ports are quite different (runtime errors
… …
822so does not need a queue that can overflow). AEMP sends are immediate, 875so does not need a queue that can overflow). AEMP sends are immediate,
823connection establishment is handled in the background. 876connection establishment is handled in the background.
824 877
825=item * Erlang suffers from silent message loss, AEMP does not. 878=item * Erlang suffers from silent message loss, AEMP does not.
826 879
827Erlang makes few guarantees on messages delivery - messages can get lost 880Erlang implements few guarantees on messages delivery - messages can get
828without any of the processes realising it (i.e. you send messages a, b, 881lost 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). 882b, and c, and the other side only receives messages a and c).
830 883
831AEMP guarantees correct ordering, and the guarantee that after one message 884AEMP 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 885is 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 886monitoring raises an error, so there are no silent "holes" in the message
834sequence. 887sequence.

Diff Legend

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