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.78 by root, Thu Sep 3 20:16:36 2009 UTC vs.
Revision 1.79 by root, Fri Sep 4 21:52:09 2009 UTC

… …
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.
46 AnyEvent::MP::Global - stable API, protocol not yet final. 46 AnyEvent::MP::Global - stable but incomplete, protocol not yet final.
47 47
48 stay tuned. 48stay tuned.
49 49
50=head1 DESCRIPTION 50=head1 DESCRIPTION
51 51
52This module (-family) implements a simple message passing framework. 52This module (-family) implements a simple message passing framework.
53 53
… …
61 61
62=over 4 62=over 4
63 63
64=item port 64=item port
65 65
66A port is something you can send messages to (with the C<snd> function). 66Not to be confused with a TCP port, a "port" is something you can send
67messages to (with the C<snd> function).
67 68
68Ports allow you to register C<rcv> handlers that can match all or just 69Ports allow you to register C<rcv> handlers that can match all or just
69some messages. Messages send to ports will not be queued, regardless of 70some messages. Messages send to ports will not be queued, regardless of
70anything was listening for them or not. 71anything was listening for them or not.
71 72
… …
474 475
475Monitor the given port and do something when the port is killed or 476Monitor the given port and do something when the port is killed or
476messages to it were lost, and optionally return a guard that can be used 477messages to it were lost, and optionally return a guard that can be used
477to stop monitoring again. 478to stop monitoring again.
478 479
480In the first form (callback), the callback is simply called with any
481number of C<@reason> elements (no @reason means that the port was deleted
482"normally"). Note also that I<< the callback B<must> never die >>, so use
483C<eval> if unsure.
484
485In the second form (another port given), the other port (C<$rcvport>)
486will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
487"normal" kils nothing happens, while under all other conditions, the other
488port is killed with the same reason.
489
490The third form (kill self) is the same as the second form, except that
491C<$rvport> defaults to C<$SELF>.
492
493In the last form (message), a message of the form C<@msg, @reason> will be
494C<snd>.
495
496Monitoring-actions are one-shot: once messages are lost (and a monitoring
497alert was raised), they are removed and will not trigger again.
498
499As a rule of thumb, monitoring requests should always monitor a port from
500a local port (or callback). The reason is that kill messages might get
501lost, just like any other message. Another less obvious reason is that
502even monitoring requests can get lost (for example, when the connection
503to the other node goes down permanently). When monitoring a port locally
504these problems do not exist.
505
479C<mon> effectively guarantees that, in the absence of hardware failures, 506C<mon> effectively guarantees that, in the absence of hardware failures,
480after starting the monitor, either all messages sent to the port will 507after starting the monitor, either all messages sent to the port will
481arrive, or the monitoring action will be invoked after possible message 508arrive, or the monitoring action will be invoked after possible message
482loss has been detected. No messages will be lost "in between" (after 509loss has been detected. No messages will be lost "in between" (after
483the first lost message no further messages will be received by the 510the first lost message no further messages will be received by the
484port). After the monitoring action was invoked, further messages might get 511port). After the monitoring action was invoked, further messages might get
485delivered again. 512delivered again.
486 513
487Note that monitoring-actions are one-shot: once messages are lost (and a 514Inter-host-connection timeouts and monitoring depend on the transport
488monitoring alert was raised), they are removed and will not trigger again. 515used. 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
517non-idle connection, and usually around two hours for idle conenctions).
489 518
490In the first form (callback), the callback is simply called with any 519This means that monitoring is good for program errors and cleaning up
491number of C<@reason> elements (no @reason means that the port was deleted 520stuff eventually, but they are no replacement for a timeout when you need
492"normally"). Note also that I<< the callback B<must> never die >>, so use 521to ensure some maximum latency.
493C<eval> if unsure.
494
495In the second form (another port given), the other port (C<$rcvport>)
496will be C<kil>'ed with C<@reason>, if a @reason was specified, i.e. on
497"normal" kils nothing happens, while under all other conditions, the other
498port is killed with the same reason.
499
500The third form (kill self) is the same as the second form, except that
501C<$rvport> defaults to C<$SELF>.
502
503In the last form (message), a message of the form C<@msg, @reason> will be
504C<snd>.
505
506As a rule of thumb, monitoring requests should always monitor a port from
507a local port (or callback). The reason is that kill messages might get
508lost, just like any other message. Another less obvious reason is that
509even monitoring requests can get lost (for example, when the connection
510to the other node goes down permanently). When monitoring a port locally
511these problems do not exist.
512 522
513Example: call a given callback when C<$port> is killed. 523Example: call a given callback when C<$port> is killed.
514 524
515 mon $port, sub { warn "port died because of <@_>\n" }; 525 mon $port, sub { warn "port died because of <@_>\n" };
516 526

Diff Legend

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