NAME

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

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'; },
);
$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_unacked

  The threshold number of unacknowledged PING messages (i.e., without a PONG response) before calling the on_fail callback.

• 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.

METHODS

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.

register

$keepalive->register( $transport );

Registers the 'keep alive program' with $transport.

LICENSE AND COPYRIGHT

See the LICENSE file in this distribution.