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.82 by root, Mon Sep 7 18:42:09 2009 UTC vs.
Revision 1.97 by root, Fri Oct 2 13:29:49 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
… …
83 81
84Nodes are either public (have one or more listening ports) or private 82Nodes are either public (have one or more listening ports) or private
85(no listening ports). Private nodes cannot talk to other private nodes 83(no listening ports). Private nodes cannot talk to other private nodes
86currently. 84currently.
87 85
88=item node ID - C<[a-za-Z0-9_\-.:]+> 86=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
89 87
90A node ID is a string that uniquely identifies the node within a 88A node ID is a string that uniquely identifies the node within a
91network. Depending on the configuration used, node IDs can look like a 89network. Depending on the configuration used, node IDs can look like a
92hostname, a hostname and a port, or a random string. AnyEvent::MP itself 90hostname, a hostname and a port, or a random string. AnyEvent::MP itself
93doesn't interpret node IDs in any way. 91doesn't interpret node IDs in any way.
… …
97Nodes can only talk to each other by creating some kind of connection to 95Nodes can only talk to each other by creating some kind of connection to
98each other. To do this, nodes should listen on one or more local transport 96each other. To do this, nodes should listen on one or more local transport
99endpoints - binds. Currently, only standard C<ip:port> specifications can 97endpoints - binds. Currently, only standard C<ip:port> specifications can
100be used, which specify TCP ports to listen on. 98be used, which specify TCP ports to listen on.
101 99
102=item seeds - C<host:port> 100=item seed nodes
103 101
104When a node starts, it knows nothing about the network. To teach the node 102When a node starts, it knows nothing about the network. To teach the node
105about the network it first has to contact some other node within the 103about the network it first has to contact some other node within the
106network. This node is called a seed. 104network. This node is called a seed.
107 105
108Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 106Apart from the fact that other nodes know them as seed nodes and they have
107to have fixed listening addresses, seed nodes are perfectly normal nodes -
108any node can function as a seed node for others.
109
110In addition to discovering the network, seed nodes are also used to
111maintain the network and to connect nodes that otherwise would have
112trouble connecting. They form the backbone of an AnyEvent::MP network.
113
109are expected to be long-running, and at least one of those should always 114Seed nodes are expected to be long-running, and at least one seed node
110be available. When nodes run out of connections (e.g. due to a network 115should always be available. They should also be relatively responsive - a
111error), they try to re-establish connections to some seednodes again to 116seed node that blocks for long periods will slow down everybody else.
112join the network.
113 117
114Apart from being sued for seeding, seednodes are not special in any way - 118=item seeds - C<host:port>
115every public node can be a seednode. 119
120Seeds are transport endpoint(s) (usually a hostname/IP address and a
121TCP port) of nodes that should be used as seed nodes.
122
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
125of connections (e.g. due to a network error), they try to re-establish
126connections to some seednodes again to join the network.
116 127
117=back 128=back
118 129
119=head1 VARIABLES/FUNCTIONS 130=head1 VARIABLES/FUNCTIONS
120 131
… …
132 143
133use AE (); 144use AE ();
134 145
135use base "Exporter"; 146use base "Exporter";
136 147
137our $VERSION = $AnyEvent::MP::Kernel::VERSION; 148our $VERSION = 1.2;
138 149
139our @EXPORT = qw( 150our @EXPORT = qw(
140 NODE $NODE *SELF node_of after 151 NODE $NODE *SELF node_of after
141 configure 152 configure
142 snd rcv mon mon_guard kil reg psub spawn 153 snd rcv mon mon_guard kil psub spawn cal
143 port 154 port
144); 155);
145 156
146our $SELF; 157our $SELF;
147 158
… …
216L<AnyEvent::MP::Global> module, which will then use it to keep 227L<AnyEvent::MP::Global> module, which will then use it to keep
217connectivity with at least one node at any point in time. 228connectivity with at least one node at any point in time.
218 229
219=back 230=back
220 231
221Example: become a distributed node using the locla node name as profile. 232Example: become a distributed node using the local node name as profile.
222This should be the most common form of invocation for "daemon"-type nodes. 233This should be the most common form of invocation for "daemon"-type nodes.
223 234
224 configure 235 configure
225 236
226Example: become an anonymous node. This form is often used for commandline 237Example: become an anonymous node. This form is often used for commandline
… …
512delivered again. 523delivered again.
513 524
514Inter-host-connection timeouts and monitoring depend on the transport 525Inter-host-connection timeouts and monitoring depend on the transport
515used. The only transport currently implemented is TCP, and AnyEvent::MP 526used. The only transport currently implemented is TCP, and AnyEvent::MP
516relies 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
517non-idle connection, and usually around two hours for idle conenctions). 528non-idle connection, and usually around two hours for idle connections).
518 529
519This means that monitoring is good for program errors and cleaning up 530This means that monitoring is good for program errors and cleaning up
520stuff 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
521to ensure some maximum latency. 532to ensure some maximum latency.
522 533
… …
554 } 565 }
555 566
556 $node->monitor ($port, $cb); 567 $node->monitor ($port, $cb);
557 568
558 defined wantarray 569 defined wantarray
559 and AnyEvent::Util::guard { $node->unmonitor ($port, $cb) } 570 and ($cb += 0, AnyEvent::Util::guard { $node->unmonitor ($port, $cb) })
560} 571}
561 572
562=item $guard = mon_guard $port, $ref, $ref... 573=item $guard = mon_guard $port, $ref, $ref...
563 574
564Monitors 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
… …
702 ? $action[0]() 713 ? $action[0]()
703 : snd @action; 714 : snd @action;
704 }; 715 };
705} 716}
706 717
718=item cal $port, @msg, $callback[, $timeout]
719
720A simple form of RPC - sends a message to the given C<$port> with the
721given contents (C<@msg>), but adds a reply port to the message.
722
723The reply port is created temporarily just for the purpose of receiving
724the reply, and will be C<kil>ed when no longer needed.
725
726A reply message sent to the port is passed to the C<$callback> as-is.
727
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
730elapsed and the port is C<kil>ed.
731
732If no time-out is given, then the local port will monitor the remote port
733instead, so it eventually gets cleaned-up.
734
735Currently this function returns the temporary port, but this "feature"
736might go in future versions unless you can make a convincing case that
737this is indeed useful for something.
738
739=cut
740
741sub cal(@) {
742 my $timeout = ref $_[-1] ? undef : pop;
743 my $cb = pop;
744
745 my $port = port {
746 undef $timeout;
747 kil $SELF;
748 &$cb;
749 };
750
751 if (defined $timeout) {
752 $timeout = AE::timer $timeout, 0, sub {
753 undef $timeout;
754 kil $port;
755 $cb->();
756 };
757 } else {
758 mon $_[0], sub {
759 kil $port;
760 $cb->();
761 };
762 }
763
764 push @_, $port;
765 &snd;
766
767 $port
768}
769
707=back 770=back
708 771
709=head1 AnyEvent::MP vs. Distributed Erlang 772=head1 AnyEvent::MP vs. Distributed Erlang
710 773
711AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 774AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
712== 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
713programming techniques employed by Erlang apply to AnyEvent::MP. Here is a 776programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
714sample: 777sample:
715 778
716 http://www.Erlang.se/doc/programming_rules.shtml 779 http://www.erlang.se/doc/programming_rules.shtml
717 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
718 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
719 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
720 783
721Despite the similarities, there are also some important differences: 784Despite the similarities, there are also some important differences:
722 785
723=over 4 786=over 4
724 787

Diff Legend

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