NAME

Sys::Async::Virt::Stream - Client side of a data transfer channel

VERSION

v0.2.1

SYNOPSIS

use Future::AsyncAwait;

my $dom = await $virt->domain_lookup_by_name( 'domain-1' );
my ($mime, $stream) = await $dom->screenshot( 0 ); # 0 = screen number

try {
  while ( my $data = await $stream->receive ) {
    if ($data->{data}) {
      # process the received data
    }
    elsif ($data->{hole}) {
      # process a hole in the input data
    }
    else {
      # $data->{data} eq '' --> end-of-stream
      last;
    }
  }
}
catch ($e) {
  await $stream->abort;
}

await $stream->finish;

DESCRIPTION

A stream models a uni-directional data transfer channel. They are used to upload and download the content of storage volumes, during migration of guests among others.

EVENTS

CONSTRUCTOR

new

The constructor takes the following arguments:

• id

• proc

• client

• direction

• max_items

DESTRUCTOR

DESTROY

$stream = undef;

Aborts the stream, if it hasn't already been terminated.

ATTRIBUTES

direction

Can have one of two values; either send or receive.

METHODS

abort

await $stream->abort;
# -> (* no data *)

Terminates stream data transfer indicating an error condition on the client.

finish

await $stream->finish;
# -> (* no data *)

Terminates stream data transfer indicating success.

receive

await $stream->receive;
# -> { data => $data }
# or:
# -> { hole => { length => $length, flags => $flags } }

Applicable to receive direction streams. When called on send direction streams, throws an exception.

send

await $stream->send( $data );
# -> (* no data *)

Applicable to send direction streams. When called on receive direction streams, throws an exception.

send_hole

await $stream->send_hole( $length, $flags = 0 );
# -> (* no data *)

Applicable to send direction streams. When called on receive direction streams, throws an exception.

INTERNAL METHODS

_dispatch_error

_dispatch_receive

SEE ALSO

LibVirt, Sys::Virt

LICENSE AND COPYRIGHT

Copyright (C) 2024-2025 Erik Huelsmann

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Sys::Async::Virt

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