NAME

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

VERSION

v0.0.12

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.

Instances have IO::Async::Notifier mixed in because they need access to awaitable futures. $self-loop->new_future> provides that access.

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