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.66 by root, Fri Aug 28 01:07:24 2009 UTC vs.
Revision 1.67 by root, Fri Aug 28 22:21:53 2009 UTC

… …
40 40
41=head1 CURRENT STATUS 41=head1 CURRENT STATUS
42 42
43 AnyEvent::MP - stable API, should work 43 AnyEvent::MP - stable API, should work
44 AnyEvent::MP::Intro - outdated 44 AnyEvent::MP::Intro - outdated
45 AnyEvent::MP::Kernel - WIP
46 AnyEvent::MP::Transport - mostly stable 45 AnyEvent::MP::Kernel - mostly stable
46 AnyEvent::MP::Global - mostly stable
47 AnyEvent::MP::Node - mostly stable, but internal anyways
48 AnyEvent::MP::Transport - mostly stable, but internal anyways
47 49
48 stay tuned. 50 stay tuned.
49 51
50=head1 DESCRIPTION 52=head1 DESCRIPTION
51 53
52This module (-family) implements a simple message passing framework. 54This module (-family) implements a simple message passing framework.
53 55
54Despite its simplicity, you can securely message other processes running 56Despite its simplicity, you can securely message other processes running
55on the same or other hosts. 57on the same or other hosts, and you can supervise entities remotely.
56 58
57For an introduction to this module family, see the L<AnyEvent::MP::Intro> 59For an introduction to this module family, see the L<AnyEvent::MP::Intro>
58manual page. 60manual page and the examples under F<eg/>.
59 61
60At the moment, this module family is severly broken and underdocumented, 62At the moment, this module family is a bit underdocumented.
61so do not use. This was uploaded mainly to reserve the CPAN namespace -
62stay tuned!
63 63
64=head1 CONCEPTS 64=head1 CONCEPTS
65 65
66=over 4 66=over 4
67 67
… …
71 71
72Ports allow you to register C<rcv> handlers that can match all or just 72Ports allow you to register C<rcv> handlers that can match all or just
73some messages. Messages send to ports will not be queued, regardless of 73some messages. Messages send to ports will not be queued, regardless of
74anything was listening for them or not. 74anything was listening for them or not.
75 75
76=item port ID - C<noderef#portname> 76=item port ID - C<nodeid#portname>
77 77
78A port ID is the concatenation of a noderef, a hash-mark (C<#>) as 78A port ID is the concatenation of a node ID, a hash-mark (C<#>) as
79separator, and a port name (a printable string of unspecified format). An 79separator, and a port name (a printable string of unspecified format).
80exception is the the node port, whose ID is identical to its node
81reference.
82 80
83=item node 81=item node
84 82
85A node is a single process containing at least one port - the node port, 83A node is a single process containing at least one port - the node port,
86which provides nodes to manage each other remotely, and to create new 84which enables nodes to manage each other remotely, and to create new
87ports. 85ports.
88 86
89Nodes are either private (single-process only), slaves (can only talk to 87Nodes are either public (have one or more listening ports) or private
90public nodes, but do not need an open port) or public nodes (connectable 88(no listening ports). Private nodes cannot talk to other private nodes
91from any other node). 89currently.
92 90
93=item node ID - C<[a-za-Z0-9_\-.:]+> 91=item node ID - C<[a-za-Z0-9_\-.:]+>
94 92
95A node ID is a string that uniquely identifies the node within a 93A node ID is a string that uniquely identifies the node within a
96network. Depending on the configuration used, node IDs can look like a 94network. Depending on the configuration used, node IDs can look like a
… …
114are expected to be long-running, and at least one of those should always 112are expected to be long-running, and at least one of those should always
115be available. When nodes run out of connections (e.g. due to a network 113be available. When nodes run out of connections (e.g. due to a network
116error), they try to re-establish connections to some seednodes again to 114error), they try to re-establish connections to some seednodes again to
117join the network. 115join the network.
118 116
117Apart from being sued for seeding, seednodes are not special in any way -
118every public node can be a seednode.
119
119=back 120=back
120 121
121=head1 VARIABLES/FUNCTIONS 122=head1 VARIABLES/FUNCTIONS
122 123
123=over 4 124=over 4
… …
138 139
139our $VERSION = $AnyEvent::MP::Kernel::VERSION; 140our $VERSION = $AnyEvent::MP::Kernel::VERSION;
140 141
141our @EXPORT = qw( 142our @EXPORT = qw(
142 NODE $NODE *SELF node_of after 143 NODE $NODE *SELF node_of after
143 resolve_node initialise_node 144 initialise_node
144 snd rcv mon mon_guard kil reg psub spawn 145 snd rcv mon mon_guard kil reg psub spawn
145 port 146 port
146); 147);
147 148
148our $SELF; 149our $SELF;
… …
153 kil $SELF, die => $msg; 154 kil $SELF, die => $msg;
154} 155}
155 156
156=item $thisnode = NODE / $NODE 157=item $thisnode = NODE / $NODE
157 158
158The C<NODE> function returns, and the C<$NODE> variable contains the node 159The C<NODE> function returns, and the C<$NODE> variable contains, the node
159ID of the node running in the current process. This value is initialised by 160ID of the node running in the current process. This value is initialised by
160a call to C<initialise_node>. 161a call to C<initialise_node>.
161 162
162=item $nodeid = node_of $port 163=item $nodeid = node_of $port
163 164
164Extracts and returns the node ID part from a port ID or a node ID. 165Extracts and returns the node ID from a port ID or a node ID.
165 166
166=item initialise_node $profile_name 167=item initialise_node $profile_name
167 168
168Before a node can talk to other nodes on the network (i.e. enter 169Before a node can talk to other nodes on the network (i.e. enter
169"distributed mode") it has to initialise itself - the minimum a node needs 170"distributed mode") it has to initialise itself - the minimum a node needs
… …
217=item $SELF 218=item $SELF
218 219
219Contains the current port id while executing C<rcv> callbacks or C<psub> 220Contains the current port id while executing C<rcv> callbacks or C<psub>
220blocks. 221blocks.
221 222
222=item SELF, %SELF, @SELF... 223=item *SELF, SELF, %SELF, @SELF...
223 224
224Due to some quirks in how perl exports variables, it is impossible to 225Due to some quirks in how perl exports variables, it is impossible to
225just export C<$SELF>, all the symbols called C<SELF> are exported by this 226just export C<$SELF>, all the symbols named C<SELF> are exported by this
226module, but only C<$SELF> is currently used. 227module, but only C<$SELF> is currently used.
227 228
228=item snd $port, type => @data 229=item snd $port, type => @data
229 230
230=item snd $port, @msg 231=item snd $port, @msg
231 232
232Send the given message to the given port ID, which can identify either 233Send the given message to the given port, which can identify either a
233a local or a remote port, and must be a port ID. 234local or a remote port, and must be a port ID.
234 235
235While the message can be about anything, it is highly recommended to use a 236While the message can be almost anything, it is highly recommended to
236string as first element (a port ID, or some word that indicates a request 237use a string as first element (a port ID, or some word that indicates a
237type etc.). 238request type etc.) and to consist if only simple perl values (scalars,
239arrays, hashes) - if you think you need to pass an object, think again.
238 240
239The message data effectively becomes read-only after a call to this 241The message data logically becomes read-only after a call to this
240function: modifying any argument is not allowed and can cause many 242function: modifying any argument (or values referenced by them) is
241problems. 243forbidden, as there can be considerable time between the call to C<snd>
244and the time the message is actually being serialised - in fact, it might
245never be copied as within the same process it is simply handed to the
246receiving port.
242 247
243The type of data you can transfer depends on the transport protocol: when 248The type of data you can transfer depends on the transport protocol: when
244JSON is used, then only strings, numbers and arrays and hashes consisting 249JSON is used, then only strings, numbers and arrays and hashes consisting
245of those are allowed (no objects). When Storable is used, then anything 250of those are allowed (no objects). When Storable is used, then anything
246that Storable can serialise and deserialise is allowed, and for the local 251that Storable can serialise and deserialise is allowed, and for the local
247node, anything can be passed. 252node, anything can be passed. Best rely only on the common denominator of
253these.
248 254
249=item $local_port = port 255=item $local_port = port
250 256
251Create a new local port object and returns its port ID. Initially it has 257Create a new local port object and returns its port ID. Initially it has
252no callbacks set and will throw an error when it receives messages. 258no callbacks set and will throw an error when it receives messages.
… …
428 $res 434 $res
429 } 435 }
430 } 436 }
431} 437}
432 438
433=item $guard = mon $port, $cb->(@reason) 439=item $guard = mon $port, $cb->(@reason) # call $cb when $port dies
434 440
435=item $guard = mon $port, $rcvport 441=item $guard = mon $port, $rcvport # kill $rcvport when $port dies
436 442
437=item $guard = mon $port 443=item $guard = mon $port # kill $SELF when $port dies
438 444
439=item $guard = mon $port, $rcvport, @msg 445=item $guard = mon $port, $rcvport, @msg # send a message when $port dies
440 446
441Monitor the given port and do something when the port is killed or 447Monitor the given port and do something when the port is killed or
442messages to it were lost, and optionally return a guard that can be used 448messages to it were lost, and optionally return a guard that can be used
443to stop monitoring again. 449to stop monitoring again.
444 450
445C<mon> effectively guarantees that, in the absence of hardware failures, 451C<mon> effectively guarantees that, in the absence of hardware failures,
446that after starting the monitor, either all messages sent to the port 452after starting the monitor, either all messages sent to the port will
447will arrive, or the monitoring action will be invoked after possible 453arrive, or the monitoring action will be invoked after possible message
448message loss has been detected. No messages will be lost "in between" 454loss has been detected. No messages will be lost "in between" (after
449(after the first lost message no further messages will be received by the 455the first lost message no further messages will be received by the
450port). After the monitoring action was invoked, further messages might get 456port). After the monitoring action was invoked, further messages might get
451delivered again. 457delivered again.
452 458
453Note that monitoring-actions are one-shot: once released, they are removed 459Note that monitoring-actions are one-shot: once messages are lost (and a
454and will not trigger again. 460monitoring alert was raised), they are removed and will not trigger again.
455 461
456In the first form (callback), the callback is simply called with any 462In the first form (callback), the callback is simply called with any
457number of C<@reason> elements (no @reason means that the port was deleted 463number of C<@reason> elements (no @reason means that the port was deleted
458"normally"). Note also that I<< the callback B<must> never die >>, so use 464"normally"). Note also that I<< the callback B<must> never die >>, so use
459C<eval> if unsure. 465C<eval> if unsure.
… …
521is killed, the references will be freed. 527is killed, the references will be freed.
522 528
523Optionally returns a guard that will stop the monitoring. 529Optionally returns a guard that will stop the monitoring.
524 530
525This function is useful when you create e.g. timers or other watchers and 531This function is useful when you create e.g. timers or other watchers and
526want to free them when the port gets killed: 532want to free them when the port gets killed (note the use of C<psub>):
527 533
528 $port->rcv (start => sub { 534 $port->rcv (start => sub {
529 my $timer; $timer = mon_guard $port, AE::timer 1, 1, sub { 535 my $timer; $timer = mon_guard $port, AE::timer 1, 1, psub {
530 undef $timer if 0.9 < rand; 536 undef $timer if 0.9 < rand;
531 }); 537 });
532 }); 538 });
533 539
534=cut 540=cut
… …
543 549
544=item kil $port[, @reason] 550=item kil $port[, @reason]
545 551
546Kill the specified port with the given C<@reason>. 552Kill the specified port with the given C<@reason>.
547 553
548If no C<@reason> is specified, then the port is killed "normally" (linked 554If no C<@reason> is specified, then the port is killed "normally" (ports
549ports will not be kileld, or even notified). 555monitoring other ports will not necessarily die because a port dies
556"normally").
550 557
551Otherwise, linked ports get killed with the same reason (second form of 558Otherwise, linked ports get killed with the same reason (second form of
552C<mon>, see below). 559C<mon>, see above).
553 560
554Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks 561Runtime errors while evaluating C<rcv> callbacks or inside C<psub> blocks
555will be reported as reason C<< die => $@ >>. 562will be reported as reason C<< die => $@ >>.
556 563
557Transport/communication errors are reported as C<< transport_error => 564Transport/communication errors are reported as C<< transport_error =>
… …
562=item $port = spawn $node, $initfunc[, @initdata] 569=item $port = spawn $node, $initfunc[, @initdata]
563 570
564Creates a port on the node C<$node> (which can also be a port ID, in which 571Creates a port on the node C<$node> (which can also be a port ID, in which
565case it's the node where that port resides). 572case it's the node where that port resides).
566 573
567The port ID of the newly created port is return immediately, and it is 574The port ID of the newly created port is returned immediately, and it is
568permissible to immediately start sending messages or monitor the port. 575possible to immediately start sending messages or to monitor the port.
569 576
570After the port has been created, the init function is 577After the port has been created, the init function is called on the remote
571called. This function must be a fully-qualified function name 578node, in the same context as a C<rcv> callback. This function must be a
572(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main 579fully-qualified function name (e.g. C<MyApp::Chat::Server::init>). To
573program, use C<::name>. 580specify a function in the main program, use C<::name>.
574 581
575If the function doesn't exist, then the node tries to C<require> 582If the function doesn't exist, then the node tries to C<require>
576the package, then the package above the package and so on (e.g. 583the package, then the package above the package and so on (e.g.
577C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 584C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
578exists or it runs out of package names. 585exists or it runs out of package names.
579 586
580The init function is then called with the newly-created port as context 587The init function is then called with the newly-created port as context
581object (C<$SELF>) and the C<@initdata> values as arguments. 588object (C<$SELF>) and the C<@initdata> values as arguments.
582 589
583A common idiom is to pass your own port, monitor the spawned port, and 590A common idiom is to pass a local port, immediately monitor the spawned
584in the init function, monitor the original port. This two-way monitoring 591port, and in the remote init function, immediately monitor the passed
585ensures that both ports get cleaned up when there is a problem. 592local port. This two-way monitoring ensures that both ports get cleaned up
593when there is a problem.
586 594
587Example: spawn a chat server port on C<$othernode>. 595Example: spawn a chat server port on C<$othernode>.
588 596
589 # this node, executed from within a port context: 597 # this node, executed from within a port context:
590 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF; 598 my $server = spawn $othernode, "MyApp::Chat::Server::connect", $SELF;
… …
632=item after $timeout, $callback 640=item after $timeout, $callback
633 641
634Either sends the given message, or call the given callback, after the 642Either sends the given message, or call the given callback, after the
635specified number of seconds. 643specified number of seconds.
636 644
637This is simply a utility function that come sin handy at times. 645This is simply a utility function that comes in handy at times - the
646AnyEvent::MP author is not convinced of the wisdom of having it, though,
647so it may go away in the future.
638 648
639=cut 649=cut
640 650
641sub after($@) { 651sub after($@) {
642 my ($timeout, @action) = @_; 652 my ($timeout, @action) = @_;
… …
733=item * The AEMP protocol is optimised for both text-based and binary 743=item * The AEMP protocol is optimised for both text-based and binary
734communications. 744communications.
735 745
736The AEMP protocol, unlike the Erlang protocol, supports both programming 746The AEMP protocol, unlike the Erlang protocol, supports both programming
737language independent text-only protocols (good for debugging) and binary, 747language independent text-only protocols (good for debugging) and binary,
738language-specific serialisers (e.g. Storable). 748language-specific serialisers (e.g. Storable). By default, unless TLS is
749used, the protocol is actually completely text-based.
739 750
740It has also been carefully designed to be implementable in other languages 751It has also been carefully designed to be implementable in other languages
741with a minimum of work while gracefully degrading functionality to make the 752with a minimum of work while gracefully degrading functionality to make the
742protocol simple. 753protocol simple.
743 754
… …
749Erlang, as one can choose between automatic kill, exit message or callback 760Erlang, as one can choose between automatic kill, exit message or callback
750on a per-process basis. 761on a per-process basis.
751 762
752=item * Erlang tries to hide remote/local connections, AEMP does not. 763=item * Erlang tries to hide remote/local connections, AEMP does not.
753 764
754Monitoring in Erlang is not an indicator of process death/crashes, 765Monitoring in Erlang is not an indicator of process death/crashes, in the
755as linking is (except linking is unreliable in Erlang). 766same way as linking is (except linking is unreliable in Erlang).
756 767
757In AEMP, you don't "look up" registered port names or send to named ports 768In AEMP, you don't "look up" registered port names or send to named ports
758that might or might not be persistent. Instead, you normally spawn a port 769that might or might not be persistent. Instead, you normally spawn a port
759on the remote node. The init function monitors the you, and you monitor 770on the remote node. The init function monitors you, and you monitor the
760the remote port. Since both monitors are local to the node, they are much 771remote port. Since both monitors are local to the node, they are much more
761more reliable. 772reliable (no need for C<spawn_link>).
762 773
763This also saves round-trips and avoids sending messages to the wrong port 774This also saves round-trips and avoids sending messages to the wrong port
764(hard to do in Erlang). 775(hard to do in Erlang).
765 776
766=back 777=back
767 778
768=head1 RATIONALE 779=head1 RATIONALE
769 780
770=over 4 781=over 4
771 782
772=item Why strings for ports and noderefs, why not objects? 783=item Why strings for port and node IDs, why not objects?
773 784
774We considered "objects", but found that the actual number of methods 785We considered "objects", but found that the actual number of methods
775thatc an be called are very low. Since port IDs and noderefs travel over 786that can be called are quite low. Since port and node IDs travel over
776the network frequently, the serialising/deserialising would add lots of 787the network frequently, the serialising/deserialising would add lots of
777overhead, as well as having to keep a proxy object. 788overhead, as well as having to keep a proxy object everywhere.
778 789
779Strings can easily be printed, easily serialised etc. and need no special 790Strings can easily be printed, easily serialised etc. and need no special
780procedures to be "valid". 791procedures to be "valid".
781 792
782And a a miniport consists of a single closure stored in a global hash - it 793And as a result, a miniport consists of a single closure stored in a
783can't become much cheaper. 794global hash - it can't become much cheaper.
784 795
785=item Why favour JSON, why not real serialising format such as Storable? 796=item Why favour JSON, why not a real serialising format such as Storable?
786 797
787In fact, any AnyEvent::MP node will happily accept Storable as framing 798In fact, any AnyEvent::MP node will happily accept Storable as framing
788format, but currently there is no way to make a node use Storable by 799format, but currently there is no way to make a node use Storable by
789default. 800default (although all nodes will accept it).
790 801
791The default framing protocol is JSON because a) JSON::XS is many times 802The default framing protocol is JSON because a) JSON::XS is many times
792faster for small messages and b) most importantly, after years of 803faster for small messages and b) most importantly, after years of
793experience we found that object serialisation is causing more problems 804experience we found that object serialisation is causing more problems
794than it gains: Just like function calls, objects simply do not travel 805than it solves: Just like function calls, objects simply do not travel
795easily over the network, mostly because they will always be a copy, so you 806easily over the network, mostly because they will always be a copy, so you
796always have to re-think your design. 807always have to re-think your design.
797 808
798Keeping your messages simple, concentrating on data structures rather than 809Keeping your messages simple, concentrating on data structures rather than
799objects, will keep your messages clean, tidy and efficient. 810objects, will keep your messages clean, tidy and efficient.

Diff Legend

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