ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/AnyEvent-MP/MP.pm
(Generate patch)

Comparing cvsroot/AnyEvent-MP/MP.pm (file contents):
Revision 1.33 by root, Wed Aug 5 22:40:51 2009 UTC vs.
Revision 1.35 by root, Thu Aug 6 10:21:48 2009 UTC

… …
22 snd $port2, ping => $port1; 22 snd $port2, ping => $port1;
23 23
24 # more, smarter, matches (_any_ is exported by this module) 24 # more, smarter, matches (_any_ is exported by this module)
25 rcv $port, [child_died => $pid] => sub { ... 25 rcv $port, [child_died => $pid] => sub { ...
26 rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3 26 rcv $port, [_any_, _any_, 3] => sub { .. $_[2] is 3
27
28 # linking two ports, so they both crash together
29 lnk $port1, $port2;
30
31 # monitoring
32 mon $port, $cb->(@msg) # callback is invoked on death
33 mon $port, $otherport # kill otherport on abnormal death
34 mon $port, $otherport, @msg # send message on death
27 35
28=head1 DESCRIPTION 36=head1 DESCRIPTION
29 37
30This module (-family) implements a simple message passing framework. 38This module (-family) implements a simple message passing framework.
31 39
… …
126identifiers become invalid. 134identifiers become invalid.
127 135
128=item $noderef = node_of $port 136=item $noderef = node_of $port
129 137
130Extracts and returns the noderef from a portid or a noderef. 138Extracts and returns the noderef from a portid or a noderef.
139
140=item initialise_node $noderef, $seednode, $seednode...
141
142=item initialise_node "slave/", $master, $master...
143
144Before a node can talk to other nodes on the network it has to initialise
145itself - the minimum a node needs to know is it's own name, and optionally
146it should know the noderefs of some other nodes in the network.
147
148This function initialises a node - it must be called exactly once (or
149never) before calling other AnyEvent::MP functions.
150
151All arguments are noderefs, which can be either resolved or unresolved.
152
153There are two types of networked nodes, public nodes and slave nodes:
154
155=over 4
156
157=item public nodes
158
159For public nodes, C<$noderef> must either be a (possibly unresolved)
160noderef, in which case it will be resolved, or C<undef> (or missing), in
161which case the noderef will be guessed.
162
163Afterwards, the node will bind itself on all endpoints and try to connect
164to all additional C<$seednodes> that are specified. Seednodes are optional
165and can be used to quickly bootstrap the node into an existing network.
166
167=item slave nodes
168
169When the C<$noderef> is the special string C<slave/>, then the node will
170become a slave node. Slave nodes cannot be contacted from outside and will
171route most of their traffic to the master node that they attach to.
172
173At least one additional noderef is required: The node will try to connect
174to all of them and will become a slave attached to the first node it can
175successfully connect to.
176
177=back
178
179This function will block until all nodes have been resolved and, for slave
180nodes, until it has successfully established a connection to a master
181server.
182
183Example: become a public node listening on the default node.
184
185 initialise_node;
186
187Example: become a public node, and try to contact some well-known master
188servers to become part of the network.
189
190 initialise_node undef, "master1", "master2";
191
192Example: become a public node listening on port C<4041>.
193
194 initialise_node 4041;
195
196Example: become a public node, only visible on localhost port 4044.
197
198 initialise_node "locahost:4044";
199
200Example: become a slave node to any of the specified master servers.
201
202 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
131 203
132=item $cv = resolve_node $noderef 204=item $cv = resolve_node $noderef
133 205
134Takes an unresolved node reference that may contain hostnames and 206Takes an unresolved node reference that may contain hostnames and
135abbreviated IDs, resolves all of them and returns a resolved node 207abbreviated IDs, resolves all of them and returns a resolved node
… …
506Transport/communication errors are reported as C<< transport_error => 578Transport/communication errors are reported as C<< transport_error =>
507$message >>. 579$message >>.
508 580
509=back 581=back
510 582
511=head1 FUNCTIONS FOR NODES
512
513=over 4
514
515=item initialise_node $noderef, $seednode, $seednode...
516
517=item initialise_node "slave/", $master, $master...
518
519Initialises a node - must be called exactly once before calling other
520AnyEvent::MP functions when talking to other nodes is required.
521
522All arguments are noderefs, which can be either resolved or unresolved.
523
524There are two types of networked nodes, public nodes and slave nodes:
525
526=over 4
527
528=item public nodes
529
530For public nodes, C<$noderef> must either be a (possibly unresolved)
531noderef, in which case it will be resolved, or C<undef> (or missing), in
532which case the noderef will be guessed.
533
534Afterwards, the node will bind itself on all endpoints and try to connect
535to all additional C<$seednodes> that are specified. Seednodes are optional
536and can be used to quickly bootstrap the node into an existing network.
537
538=item slave nodes
539
540When the C<$noderef> is the special string C<slave/>, then the node will
541become a slave node. Slave nodes cannot be contacted from outside and will
542route most of their traffic to the master node that they attach to.
543
544At least one additional noderef is required: The node will try to connect
545to all of them and will become a slave attached to the first node it can
546successfully connect to.
547
548=back
549
550This function will block until all nodes have been resolved and, for slave
551nodes, until it has successfully established a connection to a master
552server.
553
554Example: become a public node listening on the default node.
555
556 initialise_node;
557
558Example: become a public node, and try to contact some well-known master
559servers to become part of the network.
560
561 initialise_node undef, "master1", "master2";
562
563Example: become a public node listening on port C<4041>.
564
565 initialise_node 4041;
566
567Example: become a public node, only visible on localhost port 4044.
568
569 initialise_node "locahost:4044";
570
571Example: become a slave node to any of the specified master servers.
572
573 initialise_node "slave/", "master1", "192.168.13.17", "mp.example.net";
574
575=cut
576
577=back
578
579=head1 NODE MESSAGES 583=head1 NODE MESSAGES
580 584
581Nodes understand the following messages sent to them. Many of them take 585Nodes understand the following messages sent to them. Many of them take
582arguments called C<@reply>, which will simply be used to compose a reply 586arguments called C<@reply>, which will simply be used to compose a reply
583message - C<$reply[0]> is the port to reply to, C<$reply[1]> the type and 587message - C<$reply[0]> is the port to reply to, C<$reply[1]> the type and
… …
622 626
623=back 627=back
624 628
625=head1 AnyEvent::MP vs. Distributed Erlang 629=head1 AnyEvent::MP vs. Distributed Erlang
626 630
627AnyEvent::MP got lots of its ideas from distributed erlang (erlang node 631AnyEvent::MP got lots of its ideas from distributed Erlang (Erlang node
628== aemp node, erlang process == aemp port), so many of the documents and 632== aemp node, Erlang process == aemp port), so many of the documents and
629programming techniques employed by erlang apply to AnyEvent::MP. Here is a 633programming techniques employed by Erlang apply to AnyEvent::MP. Here is a
630sample: 634sample:
631 635
632 http://www.erlang.se/doc/programming_rules.shtml 636 http://www.Erlang.se/doc/programming_rules.shtml
633 http://erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4 637 http://Erlang.org/doc/getting_started/part_frame.html # chapters 3 and 4
634 http://erlang.org/download/erlang-book-part1.pdf # chapters 5 and 6 638 http://Erlang.org/download/Erlang-book-part1.pdf # chapters 5 and 6
635 http://erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5 639 http://Erlang.org/download/armstrong_thesis_2003.pdf # chapters 4 and 5
636 640
637Despite the similarities, there are also some important differences: 641Despite the similarities, there are also some important differences:
638 642
639=over 4 643=over 4
640 644
… …
651 655
652Erlang uses processes that selctively receive messages, and therefore 656Erlang uses processes that selctively receive messages, and therefore
653needs a queue. AEMP is event based, queuing messages would serve no useful 657needs a queue. AEMP is event based, queuing messages would serve no useful
654purpose. 658purpose.
655 659
656(But see L<Coro::MP> for a more erlang-like process model on top of AEMP). 660(But see L<Coro::MP> for a more Erlang-like process model on top of AEMP).
657 661
658=item * Erlang sends are synchronous, AEMP sends are asynchronous. 662=item * Erlang sends are synchronous, AEMP sends are asynchronous.
659 663
660Sending messages in erlang is synchronous and blocks the process. AEMP 664Sending messages in Erlang is synchronous and blocks the process. AEMP
661sends are immediate, connection establishment is handled in the 665sends are immediate, connection establishment is handled in the
662background. 666background.
663 667
664=item * Erlang can silently lose messages, AEMP cannot. 668=item * Erlang can silently lose messages, AEMP cannot.
665 669
… …
668and c, and the other side only receives messages a and c). 672and c, and the other side only receives messages a and c).
669 673
670AEMP guarantees correct ordering, and the guarantee that there are no 674AEMP guarantees correct ordering, and the guarantee that there are no
671holes in the message sequence. 675holes in the message sequence.
672 676
673=item * In erlang, processes can be declared dead and later be found to be 677=item * In Erlang, processes can be declared dead and later be found to be
674alive. 678alive.
675 679
676In erlang it can happen that a monitored process is declared dead and 680In Erlang it can happen that a monitored process is declared dead and
677linked processes get killed, but later it turns out that the process is 681linked processes get killed, but later it turns out that the process is
678still alive - and can receive messages. 682still alive - and can receive messages.
679 683
680In AEMP, when port monitoring detects a port as dead, then that port will 684In AEMP, when port monitoring detects a port as dead, then that port will
681eventually be killed - it cannot happen that a node detects a port as dead 685eventually be killed - it cannot happen that a node detects a port as dead
682and then later sends messages to it, finding it is still alive. 686and then later sends messages to it, finding it is still alive.
683 687
684=item * Erlang can send messages to the wrong port, AEMP does not. 688=item * Erlang can send messages to the wrong port, AEMP does not.
685 689
686In erlang it is quite possible that a node that restarts reuses a process 690In Erlang it is quite possible that a node that restarts reuses a process
687ID known to other nodes for a completely different process, causing 691ID known to other nodes for a completely different process, causing
688messages destined for that process to end up in an unrelated process. 692messages destined for that process to end up in an unrelated process.
689 693
690AEMP never reuses port IDs, so old messages or old port IDs floating 694AEMP never reuses port IDs, so old messages or old port IDs floating
691around in the network will not be sent to an unrelated port. 695around in the network will not be sent to an unrelated port.
… …
697securely authenticate nodes. 701securely authenticate nodes.
698 702
699=item * The AEMP protocol is optimised for both text-based and binary 703=item * The AEMP protocol is optimised for both text-based and binary
700communications. 704communications.
701 705
702The AEMP protocol, unlike the erlang protocol, supports both 706The AEMP protocol, unlike the Erlang protocol, supports both
703language-independent text-only protocols (good for debugging) and binary, 707language-independent text-only protocols (good for debugging) and binary,
704language-specific serialisers (e.g. Storable). 708language-specific serialisers (e.g. Storable).
705 709
706It has also been carefully designed to be implementable in other languages 710It has also been carefully designed to be implementable in other languages
707with a minimum of work while gracefully degrading fucntionality to make the 711with a minimum of work while gracefully degrading fucntionality to make the
708protocol simple. 712protocol simple.
709 713
714=item * AEMP has more flexible monitoring options than Erlang.
715
716In Erlang, you can chose to receive I<all> exit signals as messages
717or I<none>, there is no in-between, so monitoring single processes is
718difficult to implement. Monitoring in AEMP is more flexible than in
719Erlang, as one can choose between automatic kill, exit message or callback
720on a per-process basis.
721
722=item * Erlang has different semantics for monitoring and linking, AEMP has the same.
723
724Monitoring in Erlang is not an indicator of process death/crashes,
725as linking is (except linking is unreliable in Erlang). In AEMP, the
726semantics of monitoring and linking are identical, linking is simply
727two-way monitoring with automatic kill.
728
710=back 729=back
711 730
712=head1 SEE ALSO 731=head1 SEE ALSO
713 732
714L<AnyEvent>. 733L<AnyEvent>.

Diff Legend

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