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.38 by root, Fri Aug 7 22:55:18 2009 UTC vs.
Revision 1.47 by root, Thu Aug 13 01:57:10 2009 UTC

… …
38 # monitoring 38 # monitoring
39 mon $port, $cb->(@msg) # callback is invoked on death 39 mon $port, $cb->(@msg) # callback is invoked on death
40 mon $port, $otherport # kill otherport on abnormal death 40 mon $port, $otherport # kill otherport on abnormal death
41 mon $port, $otherport, @msg # send message on death 41 mon $port, $otherport, @msg # send message on death
42 42
43=head1 CURRENT STATUS
44
45 AnyEvent::MP - stable API, should work
46 AnyEvent::MP::Intro - outdated
47 AnyEvent::MP::Kernel - WIP
48 AnyEvent::MP::Transport - mostly stable
49
50 stay tuned.
51
43=head1 DESCRIPTION 52=head1 DESCRIPTION
44 53
45This module (-family) implements a simple message passing framework. 54This module (-family) implements a simple message passing framework.
46 55
47Despite its simplicity, you can securely message other processes running 56Despite its simplicity, you can securely message other processes running
… …
50For 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>
51manual page. 60manual page.
52 61
53At the moment, this module family is severly broken and underdocumented, 62At the moment, this module family is severly broken and underdocumented,
54so do not use. This was uploaded mainly to reserve the CPAN namespace - 63so do not use. This was uploaded mainly to reserve the CPAN namespace -
55stay tuned! The basic API should be finished, however. 64stay tuned!
56 65
57=head1 CONCEPTS 66=head1 CONCEPTS
58 67
59=over 4 68=over 4
60 69
… …
105 114
106=cut 115=cut
107 116
108package AnyEvent::MP; 117package AnyEvent::MP;
109 118
110use AnyEvent::MP::Base; 119use AnyEvent::MP::Kernel;
111 120
112use common::sense; 121use common::sense;
113 122
114use Carp (); 123use Carp ();
115 124
116use AE (); 125use AE ();
117 126
118use base "Exporter"; 127use base "Exporter";
119 128
120our $VERSION = '0.1'; 129our $VERSION = $AnyEvent::MP::Kernel::VERSION;
130
121our @EXPORT = qw( 131our @EXPORT = qw(
122 NODE $NODE *SELF node_of _any_ 132 NODE $NODE *SELF node_of _any_
123 resolve_node initialise_node 133 resolve_node initialise_node
124 snd rcv mon kil reg psub spawn 134 snd rcv mon kil reg psub spawn
125 port 135 port
… …
501 511
502=item $guard = mon $port 512=item $guard = mon $port
503 513
504=item $guard = mon $port, $rcvport, @msg 514=item $guard = mon $port, $rcvport, @msg
505 515
506Monitor the given port and do something when the port is killed, and 516Monitor the given port and do something when the port is killed or
507optionally return a guard that can be used to stop monitoring again. 517messages to it were lost, and optionally return a guard that can be used
518to stop monitoring again.
519
520C<mon> effectively guarantees that, in the absence of hardware failures,
521that after starting the monitor, either all messages sent to the port
522will arrive, or the monitoring action will be invoked after possible
523message loss has been detected. No messages will be lost "in between"
524(after the first lost message no further messages will be received by the
525port). After the monitoring action was invoked, further messages might get
526delivered again.
508 527
509In the first form (callback), the callback is simply called with any 528In the first form (callback), the callback is simply called with any
510number of C<@reason> elements (no @reason means that the port was deleted 529number of C<@reason> elements (no @reason means that the port was deleted
511"normally"). Note also that I<< the callback B<must> never die >>, so use 530"normally"). Note also that I<< the callback B<must> never die >>, so use
512C<eval> if unsure. 531C<eval> if unsure.
513 532
514In the second form (another port given), the other port (C<$rcvport) 533In the second form (another port given), the other port (C<$rcvport>)
515will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on 534will be C<kil>'ed with C<@reason>, iff a @reason was specified, i.e. on
516"normal" kils nothing happens, while under all other conditions, the other 535"normal" kils nothing happens, while under all other conditions, the other
517port is killed with the same reason. 536port is killed with the same reason.
518 537
519The third form (kill self) is the same as the second form, except that 538The third form (kill self) is the same as the second form, except that
… …
546sub mon { 565sub mon {
547 my ($noderef, $port) = split /#/, shift, 2; 566 my ($noderef, $port) = split /#/, shift, 2;
548 567
549 my $node = $NODE{$noderef} || add_node $noderef; 568 my $node = $NODE{$noderef} || add_node $noderef;
550 569
551 my $cb = @_ ? $_[0] : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,'; 570 my $cb = @_ ? shift : $SELF || Carp::croak 'mon: called with one argument only, but $SELF not set,';
552 571
553 unless (ref $cb) { 572 unless (ref $cb) {
554 if (@_) { 573 if (@_) {
555 # send a kill info message 574 # send a kill info message
556 my (@msg) = @_; 575 my (@msg) = ($cb, @_);
557 $cb = sub { snd @msg, @_ }; 576 $cb = sub { snd @msg, @_ };
558 } else { 577 } else {
559 # simply kill other port 578 # simply kill other port
560 my $port = $cb; 579 my $port = $cb;
561 $cb = sub { kil $port, @_ if @_ }; 580 $cb = sub { kil $port, @_ if @_ };
… …
619 638
620The port ID of the newly created port is return immediately, and it is 639The port ID of the newly created port is return immediately, and it is
621permissible to immediately start sending messages or monitor the port. 640permissible to immediately start sending messages or monitor the port.
622 641
623After the port has been created, the init function is 642After the port has been created, the init function is
624called. This fucntion must be a fully-qualified function name 643called. This function must be a fully-qualified function name
625(e.g. C<MyApp::Chat::Server::init>). 644(e.g. C<MyApp::Chat::Server::init>). To specify a function in the main
645program, use C<::name>.
626 646
627If the function doesn't exist, then the node tries to C<require> 647If the function doesn't exist, then the node tries to C<require>
628the package, then the package above the package and so on (e.g. 648the package, then the package above the package and so on (e.g.
629C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function 649C<MyApp::Chat::Server>, C<MyApp::Chat>, C<MyApp>) until the function
630exists or it runs out of package names. 650exists or it runs out of package names.
… …
669sub spawn(@) { 689sub spawn(@) {
670 my ($noderef, undef) = split /#/, shift, 2; 690 my ($noderef, undef) = split /#/, shift, 2;
671 691
672 my $id = "$RUNIQ." . $ID++; 692 my $id = "$RUNIQ." . $ID++;
673 693
694 $_[0] =~ /::/
695 or Carp::croak "spawn init function must be a fully-qualified name, caught";
696
674 ($NODE{$noderef} || add_node $noderef) 697 ($NODE{$noderef} || add_node $noderef)
675 ->send (["", "AnyEvent::MP::_spawn" => $id, @_]); 698 ->send (["", "AnyEvent::MP::_spawn" => $id, @_]);
676 699
677 "$noderef#$id" 700 "$noderef#$id"
678} 701}
… …
832This also saves round-trips and avoids sending messages to the wrong port 855This also saves round-trips and avoids sending messages to the wrong port
833(hard to do in Erlang). 856(hard to do in Erlang).
834 857
835=back 858=back
836 859
860=head1 RATIONALE
861
862=over 4
863
864=item Why strings for ports and noderefs, why not objects?
865
866We considered "objects", but found that the actual number of methods
867thatc an be called are very low. Since port IDs and noderefs travel over
868the network frequently, the serialising/deserialising would add lots of
869overhead, as well as having to keep a proxy object.
870
871Strings can easily be printed, easily serialised etc. and need no special
872procedures to be "valid".
873
874And a a miniport consists of a single closure stored in a global hash - it
875can't become much cheaper.
876
877=item Why favour JSON, why not real serialising format such as Storable?
878
879In fact, any AnyEvent::MP node will happily accept Storable as framing
880format, but currently there is no way to make a node use Storable by
881default.
882
883The default framing protocol is JSON because a) JSON::XS is many times
884faster for small messages and b) most importantly, after years of
885experience we found that object serialisation is causing more problems
886than it gains: Just like function calls, objects simply do not travel
887easily over the network, mostly because they will always be a copy, so you
888always have to re-think your design.
889
890Keeping your messages simple, concentrating on data structures rather than
891objects, will keep your messages clean, tidy and efficient.
892
893=back
894
837=head1 SEE ALSO 895=head1 SEE ALSO
838 896
839L<AnyEvent>. 897L<AnyEvent>.
840 898
841=head1 AUTHOR 899=head1 AUTHOR

Diff Legend

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