NAME

Sys::Virt::IO::Async - Helpers to integrate Sys::Virt with IO::Async

SYNOPSIS

  use IO::Async::Loop;
  use Sys::Virt;
  use Sys::Virt::Event;
  use Sys::Virt::IO::Async;
  use Sys::Virt::IO::Async::EventImpl;

  my $impl = Sys::Virt::IO::Async::EventImpl->new;
  my $loop = IO::Async::Loop->new;
  $loop->add( $impl );

  my $conn = Sys::Virt::IO::Async->new(
    virt => Sys::Virt->new( uri => 'qemu:///system' ),
    on_close => sub { ... },
    on_domain_change => sub { ... });

  $impl->add_child( $conn );


  # ... do stuff ...

  # close the connection:
  undef $conn;

DESCRIPTION

This module is a notifier for Sys::Virt. It makes most sense to use this module in conjunction with an event loop (See Sys::Virt::Event and Sys::Virt::EventImpl). It invokes the on_close event callback when the connection to libvirt is lost. While connected, any domain life cycle events trigger the on_domain_change event callback.

In addition to triggering these event callbacks, it also tracks callbacks registered with these functions in Sys::Virt: domain_event_register_any, network_event_register_any, storage_pool_event_register_any, node_device_event_register_any and secret_event_register_any. The tracked callbacks (including on_close and on_domain_change) are unregistered when the close event occurs: these callbacks must be deallocated for the Sys::Virt instance to be garbage collected.

METHODS

new( virt => $virt, on_close => $close, on_domain_change => $change)

Constructor. Returns a Sys::Virt::IO::Async instance.

The $on_close argument is either a coderef to be executed when the connection closes, or a future which will be resolved after the callback completes.

The $change argument is either a coderef to be executed when a domain life cycle event occurs, or a Future::Queue instance which will have the callback arguments pushed after the callback completes.

The $virt argument is required.

configure

Overrides the method inherited from IO::Async::Notifier.

deregister_callbacks

Deregisters all callbacks being tracked, which were registered using domain_event_register_any, network_event_register_any, storage_pool_event_register_any, node_device_event_register_any or secret_event_register_any and not yet deregistered using the associated deregistration functions.

domain_event_register

domain_event_deregister

Unsupported: domain event callback registration handled at instantiation.

domain_event_register_any($dom, $eventID, $callback)

network_event_register_any($net, $eventID, $callback)

storage_pool_event_register_any($pool, $eventID, $callback)

node_device_event_register_any($dev, $eventID, $callback)

secret_event_register_any($secret, $eventID, $callback)

Registers the callback with the wrapped Sys::Virt instance; $callback is called with a Sys::Virt::IO::Async instance as its first argument instead of the Sys::Virt instance if the callback had been registered through it directly.

If the $callback is an instance of Future::Queue, the arguments are pushed onto the queue as an array reference after the callback completes. The callback can be deregistered by calling the finish method of the queue.

IMPORTANT Code which tries to modify the state of libvirt (domains, networks, etc., but also callbacks) should be executed outside of the callback. This can be achieved using $conn-loop->later()>.

The registered callback is tracked and deregistered automatically when the connection with libvirt is closed,

Returns a $callbackID to be used for explicit deregistration.

domain_event_deregister_any($callbackID)

network_event_deregister_any($callbackID)

storage_pool_event_deregister_any($callbackID)

node_device_event_deregister_any($callbackID)

secret_event_deregister_any($callbackID)

Deregisters the callback, preventing further calls; stops tracking the callback for deregistration on connection close.

METHOD CALL FORWARDING

All method invocations for methods not documented above, are forwarded to the wrapped Sys::Virt instance:

  # this:
  my $uri = $conn->get_uri();

  # is similar to this:
  my $uri = $conn->virt->get_uri();

This way the instance of this class is a drop-in replacement for a Sys::Virt instance with a few minor exceptions (the methods documented above).

AUTHORS

• Erik Huelsmann ehuels@gmail.com

LICENSE AND COPYRIGHT

This software is copyright (c) 2023 by Erik Huelsmann.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Sys::Virt::IO::Async

perl -MCPAN -e shell
install Sys::Virt::IO::Async