/ 
Protocol-Sys-Virt-v10.3.13
River stage zero No dependents
/ Protocol::Sys::Virt::KeepAlive

NAME

Protocol::Sys::Virt::KeepAlive - Check transport link availability

VERSION

v10.3.13

Based on LibVirt tag v10.3.0

SYNOPSIS

use Protocol::Sys::Virt::Transport;
use Protocol::Sys::Virt::KeepAlive;

my $transport = Protocol::Sys::Virt::Transport->new(
   role => 'client',
   on_send => sub { ... }
);

my $keepalive = Protocol::Sys::Virt::KeepAlive->new(
   max_unacked => 20,
   on_ack  => sub { say 'We are still alive!'; },
   on_fail => sub { die 'Connection timed out'; },
   on_ping => sub {
      my ($ka, $trnsp) = @_;
      $ka->pong;
   },
);
$keepalive->register( $transport );

$keepalive->ping;
$keepalive->ping;

DESCRIPTION

This module defines the "Keep Alive" program of the LibVirt protocol. Its use as part of the connection to the libvirt daemon(s), is negotiated over the (primary, remote) program protocol. Support for this "program" can be queried using the REMOTE_PROC_CONNECT_SUPPORTS_FEATURE call.

Instances keep a count of unacknowledged PING messages; when the number exceeds a certain threshold, the on_fail callback is called.

Note that users actively need to call the ping method; there's no timer functionality in this module which automatically calls it.

CONSTRUCTOR

new

Accepts the following options:

  • max_inactive

    The threshold number of ping calls without activity; when the number of calls exceeds this value, the on_fail callback will be invoked.

    Note that activity can be signalled through mark_active as well as receiving PING or PONG messages.

  • on_ack

    Callback called when a PONG message is received.

  • on_fail

    Callback called when the number of unacknowledged PING messages exceeds the max_unacked threshold.

  • on_ping

    $on_ping->( $keepalive, $transport );

    Callback called when a PING message is received. Typically should call $keepalive->pong (and deal with its return value).

METHODS

mark_active

$keepalive->mark_active;

Makes the keep alive tracker aware of connection activity other than the PING and PONG messages it registered itself for with the $transport.

This function may be called on incoming data but should not be called when data is transmitted. When this function has been called between two calls to $keepalive->ping, it will not send a PING message, taking the current activity as sufficient proof of an open connection.

ping

$keepalive->ping;

Sends a PROC_PING message over the $transport on which it is registered. If the number of unacknowledged pings grows above the threshold, triggers the on_fail event.

Returns either nothing at all (in case no PING message needed to be sent), or the return value of the sender routine registered with the transport when a PING message was sent.

pong

$keepalive->pong;

Sends a PROC_PONG message over the $transport on which it is registered.

Returns the return value of the sender routine registered with the transport.

register

$keepalive->register( $transport );

Registers the 'keep alive program' with $transport.

LICENSE AND COPYRIGHT

See the LICENSE file in this distribution.