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.81 by root, Mon Sep 7 18:33:44 2009 UTC vs.
Revision 1.87 by root, Fri Sep 11 02:32:23 2009 UTC

… …
83 83
84Nodes are either public (have one or more listening ports) or private 84Nodes are either public (have one or more listening ports) or private
85(no listening ports). Private nodes cannot talk to other private nodes 85(no listening ports). Private nodes cannot talk to other private nodes
86currently. 86currently.
87 87
88=item node ID - C<[a-za-Z0-9_\-.:]+> 88=item node ID - C<[A-Z_][a-zA-Z0-9_\-.:]*>
89 89
90A node ID is a string that uniquely identifies the node within a 90A node ID is a string that uniquely identifies the node within a
91network. Depending on the configuration used, node IDs can look like a 91network. Depending on the configuration used, node IDs can look like a
92hostname, a hostname and a port, or a random string. AnyEvent::MP itself 92hostname, a hostname and a port, or a random string. AnyEvent::MP itself
93doesn't interpret node IDs in any way. 93doesn't interpret node IDs in any way.
… …
97Nodes can only talk to each other by creating some kind of connection to 97Nodes 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 98each other. To do this, nodes should listen on one or more local transport
99endpoints - binds. Currently, only standard C<ip:port> specifications can 99endpoints - binds. Currently, only standard C<ip:port> specifications can
100be used, which specify TCP ports to listen on. 100be used, which specify TCP ports to listen on.
101 101
102=item seeds - C<host:port> 102=item seed nodes
103 103
104When a node starts, it knows nothing about the network. To teach the node 104When 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 105about the network it first has to contact some other node within the
106network. This node is called a seed. 106network. This node is called a seed.
107 107
108Seeds are transport endpoint(s) of as many nodes as one wants. Those nodes 108Apart from the fact that other nodes know them as seed nodes and they have
109to have fixed listening addresses, seed nodes are perfectly normal nodes -
110any node can function as a seed node for others.
111
112In addition to discovering the network, seed nodes are also used to
113maintain the network and to connect nodes that otherwise would have
114trouble connecting. They form the backbone of an AnyEvent::MP network.
115
109are expected to be long-running, and at least one of those should always 116Seed 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 117should always be available. They should also be relatively responsive - a
111error), they try to re-establish connections to some seednodes again to 118seed node that blocks for long periods will slow down everybody else.
112join the network.
113 119
114Apart from being sued for seeding, seednodes are not special in any way - 120=item seeds - C<host:port>
115every public node can be a seednode. 121
122Seeds are transport endpoint(s) (usually a hostname/IP address and a
123TCP port) of nodes thta should be used as seed nodes.
124
125The 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
127of connections (e.g. due to a network error), they try to re-establish
128connections to some seednodes again to join the network.
116 129
117=back 130=back
118 131
119=head1 VARIABLES/FUNCTIONS 132=head1 VARIABLES/FUNCTIONS
120 133
… …
137our $VERSION = $AnyEvent::MP::Kernel::VERSION; 150our $VERSION = $AnyEvent::MP::Kernel::VERSION;
138 151
139our @EXPORT = qw( 152our @EXPORT = qw(
140 NODE $NODE *SELF node_of after 153 NODE $NODE *SELF node_of after
141 configure 154 configure
142 snd rcv mon mon_guard kil reg psub spawn 155 snd rcv mon mon_guard kil reg psub spawn cal
143 port 156 port
144); 157);
145 158
146our $SELF; 159our $SELF;
147 160
… …
216L<AnyEvent::MP::Global> module, which will then use it to keep 229L<AnyEvent::MP::Global> module, which will then use it to keep
217connectivity with at least one node at any point in time. 230connectivity with at least one node at any point in time.
218 231
219=back 232=back
220 233
221Example: become a distributed node using the locla node name as profile. 234Example: become a distributed node using the local node name as profile.
222This should be the most common form of invocation for "daemon"-type nodes. 235This should be the most common form of invocation for "daemon"-type nodes.
223 236
224 configure 237 configure
225 238
226Example: become an anonymous node. This form is often used for commandline 239Example: become an anonymous node. This form is often used for commandline
… …
621the package, then the package above the package and so on (e.g. 634the package, then the package above the package and so on (e.g.
622C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 635C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
623exists or it runs out of package names. 636exists or it runs out of package names.
624 637
625The init function is then called with the newly-created port as context 638The init function is then called with the newly-created port as context
626object (C<$SELF>) and the C<@initdata> values as arguments. 639object (C<$SELF>) and the C<@initdata> values as arguments. It I<must>
640call one of the C<rcv> functions to set callbacks on C<$SELF>, otherwise
641the port might not get created.
627 642
628A common idiom is to pass a local port, immediately monitor the spawned 643A common idiom is to pass a local port, immediately monitor the spawned
629port, and in the remote init function, immediately monitor the passed 644port, and in the remote init function, immediately monitor the passed
630local port. This two-way monitoring ensures that both ports get cleaned up 645local port. This two-way monitoring ensures that both ports get cleaned up
631when there is a problem. 646when there is a problem.
… …
655 670
656sub _spawn { 671sub _spawn {
657 my $port = shift; 672 my $port = shift;
658 my $init = shift; 673 my $init = shift;
659 674
675 # rcv will create the actual port
660 local $SELF = "$NODE#$port"; 676 local $SELF = "$NODE#$port";
661 eval { 677 eval {
662 &{ load_func $init } 678 &{ load_func $init }
663 }; 679 };
664 _self_die if $@; 680 _self_die if $@;
… …
699 ? $action[0]() 715 ? $action[0]()
700 : snd @action; 716 : snd @action;
701 }; 717 };
702} 718}
703 719
720=item cal $port, @msg, $callback[, $timeout]
721
722A simple form of RPC - sends a message to the given C<$port> with the
723given contents (C<@msg>), but adds a reply port to the message.
724
725The reply port is created temporarily just for the purpose of receiving
726the reply, and will be C<kil>ed when no longer needed.
727
728A reply message sent to the port is passed to the C<$callback> as-is.
729
730If 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
732elapsed and the port is C<kil>ed.
733
734If no time-out is given, then the local port will monitor the remote port
735instead, so it eventually gets cleaned-up.
736
737Currently this function returns the temporary port, but this "feature"
738might go in future versions unless you can make a convincing case that
739this is indeed useful for something.
740
741=cut
742
743sub cal(@) {
744 my $timeout = ref $_[-1] ? undef : pop;
745 my $cb = pop;
746
747 my $port = port {
748 undef $timeout;
749 kil $SELF;
750 &$cb;
751 };
752
753 if (defined $timeout) {
754 $timeout = AE::timer $timeout, 0, sub {
755 undef $timeout;
756 kil $port;
757 $cb->();
758 };
759 } else {
760 mon $_[0], sub {
761 kil $port;
762 $cb->();
763 };
764 }
765
766 push @_, $port;
767 &snd;
768
769 $port
770}
771
704=back 772=back
705 773
706=head1 AnyEvent::MP vs. Distributed Erlang 774=head1 AnyEvent::MP vs. Distributed Erlang
707 775
708AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node 776AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node

Diff Legend

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