view release on metacpan or  search on metacpan

README  view on Meta::CPAN

           my $port = port { ... };

           peval $port, sub {
              init
                 or die "unable to init";
           };

    $closure = psub { BLOCK }
        Remembers $SELF and creates a closure out of the BLOCK. When the
        closure is executed, sets up the environment in the same way as in
        "rcv" callbacks, i.e. runtime errors will cause the port to get
        "kil"ed.

        The effect is basically as if it returned "sub { peval $SELF, sub {
        BLOCK }, @_ }".

        This is useful when you register callbacks from "rcv" callbacks:

           rcv delayed_reply => sub {
              my ($delay, @reply) = @_;
              my $timer = AE::timer $delay, 0, psub {
                 snd @reply, $SELF;
              };
           };

    $guard = mon $port, $rcvport # kill $rcvport when $port dies
    $guard = mon $port # kill $SELF when $port dies
    $guard = mon $port, $cb->(@reason) # call $cb when $port dies
    $guard = mon $port, $rcvport, @msg # send a message when $port dies
        Monitor the given port and do something when the port is killed or
        messages to it were lost, and optionally return a guard that can be
        used to stop monitoring again.

        The first two forms distinguish between "normal" and "abnormal"
        kil's:

        In the first form (another port given), if the $port is "kil"'ed
        with a non-empty reason, the other port ($rcvport) will be kil'ed
        with the same reason. That is, on "normal" kil's nothing happens,
        while under all other conditions, the other port is killed with the
        same reason.

        The second form (kill self) is the same as the first form, except
        that $rvport defaults to $SELF.

        The remaining forms don't distinguish between "normal" and
        "abnormal" kil's - it's up to the callback or receiver to check
        whether the @reason is empty and act accordingly.

        In the third form (callback), the callback is simply called with any
        number of @reason elements (empty @reason means that the port was
        deleted "normally"). Note also that *the callback must never die*,
        so use "eval" if unsure.

        In the last form (message), a message of the form "$rcvport, @msg,
        @reason" will be "snd".

        Monitoring-actions are one-shot: once messages are lost (and a
        monitoring alert was raised), they are removed and will not trigger
        again, even if it turns out that the port is still alive.

        As a rule of thumb, monitoring requests should always monitor a
        remote port locally (using a local $rcvport or a callback). The
        reason is that kill messages might get lost, just like any other
        message. Another less obvious reason is that even monitoring
        requests can get lost (for example, when the connection to the other
        node goes down permanently). When monitoring a port locally these
        problems do not exist.

        "mon" effectively guarantees that, in the absence of hardware
        failures, after starting the monitor, either all messages sent to
        the port will arrive, or the monitoring action will be invoked after
        possible message loss has been detected. No messages will be lost
        "in between" (after the first lost message no further messages will
        be received by the port). After the monitoring action was invoked,
        further messages might get delivered again.

        Inter-host-connection timeouts and monitoring depend on the
        transport used. The only transport currently implemented is TCP, and
        AnyEvent::MP relies on TCP to detect node-downs (this can take 10-15
        minutes on a non-idle connection, and usually around two hours for
        idle connections).

        This means that monitoring is good for program errors and cleaning
        up stuff eventually, but they are no replacement for a timeout when
        you need to ensure some maximum latency.

        Example: call a given callback when $port is killed.

           mon $port, sub { warn "port died because of <@_>\n" };

        Example: kill ourselves when $port is killed abnormally.

           mon $port;

        Example: send us a restart message when another $port is killed.

           mon $port, $self => "restart";

    $guard = mon_guard $port, $ref, $ref...
        Monitors the given $port and keeps the passed references. When the
        port is killed, the references will be freed.

        Optionally returns a guard that will stop the monitoring.

        This function is useful when you create e.g. timers or other
        watchers and want to free them when the port gets killed (note the
        use of "psub"):

          $port->rcv (start => sub {
             my $timer; $timer = mon_guard $port, AE::timer 1, 1, psub {
                undef $timer if 0.9 < rand;
             });
          });

    kil $port[, @reason]
        Kill the specified port with the given @reason.

        If no @reason is specified, then the port is killed "normally" -
        monitor callback will be invoked, but the kil will not cause linked