Scroll to navigation

Sys::Virt::Stream(3pm) User Contributed Perl Documentation Sys::Virt::Stream(3pm)

NAME

Sys::Virt::Stream - Represent & manage a libvirt stream

DESCRIPTION

The "Sys::Virt::Stream" module represents a stream managed by the virtual machine monitor.

METHODS

Creates a new data stream, ready for use with a stream based API. The optional $flags parameter can be used to configure the stream as non-blocking
$st->abort()
Abort I/O on the stream. Either this function or "finish" must be called on any stream which has been activated
$st->finish()
Complete I/O on the stream. Either this function or "abort" must be called on any stream which has been activated
$rv = $st->recv($data, $nbytes, $flags=0)
Receive up to $nbytes worth of data, copying into $data. Returns the number of bytes read, or -3 if hole is reached and $flags contains RECV_STOP_AT_HOLE, or -2 if I/O would block, or -1 on error. The $flags parameter accepts the following flags:
If this flag is set, the "recv" function will stop reading from stream if it has reached a hole. In that case, -3 is returned and "recv_hole" should be called to get the hole size.
$rv = $st->send($data, $nbytes)
Send up to $nbytes worth of data, copying from $data. Returns the number of bytes sent, or -2 if I/O would block, or -1 on error.
$rv = $st->recv_hole($flags=0)
Determine the amount of the empty space (in bytes) to be created in a stream's target file when uploading or downloading sparsely populated files. This is the counterpart to "send_hole". The optional $flags parameter is currently unused and defaults to zero if omitted.
$st->send_hole($length, $flags=0)
Rather than transmitting empty file space, this method directs the stream target to create $length bytes of empty space. This method would be used when uploading or downloading sparsely populated files to avoid the needless copy of empty file space. The optional $flags parameter is currently unused and defaults to zero if omitted.
$st->recv_all($handler)
Receive all data available from the stream, invoking $handler to process the data. The $handler parameter must be a function which expects three arguments, the $st stream object, a scalar containing the data received and a data byte count. The function should return the number of bytes processed, or -1 upon error.
$st->send_all($handler)
Send all data produced by $handler to the stream. The $handler parameter must be a function which expects three arguments, the $st stream object, a scalar which must be filled with data and a maximum data byte count desired. The function should return the number of bytes filled, 0 on end of file, or -1 upon error
$st->sparse_recv_all($handler, $hole_handler)
Receive all data available from the sparse stream, invoking $handler to process the data. The $handler parameter must be a function which expects three arguments, the $st stream object, a scalar containing the data received and a data byte count. The function should return the number of bytes processed, or -1 upon error. The second argument $hole_handler is a function which expects two arguments: the $st stream and a scalar, number describing the size of the hole in the stream (in bytes). The $hole_handler is expected to return a non-negative number on success (usually 0) and a negative number (usually -1) otherwise.
$st->sparse_send_all($handler, $hole_handler, $skip_handler)
Send all data produced by $handler to the stream. The $handler parameter must be a function which expects three arguments, the $st stream object, a scalar which must be filled with data and a maximum data byte count desired. The function should return the number of bytes filled, 0 on end of file, or -1 upon error. The second argument $hole_handler is a function expecting just one argument $st and returning an array of two elements ($in_data, $section_len) where $in_data has zero or non-zero value if underlying file is in a hole or data section respectively. The $section_len then is the number of remaining bytes in the current section in the underlying file. Finally, the third $skip_handler is a function expecting two arguments $st and $length which moves cursor in the underlying file for $length bytes. The $skip_handler is expected to return a non-negative number on success (usually 0) and a negative number (usually -1) otherwise.
$st->add_callback($events, $coderef)
Register a callback to be invoked whenever the stream has one or more events from $events mask set. The $coderef must be a subroutine that expects 2 parameters, the original $st object and the new $events mask
$st->update_callback($events)
Change the event mask for a previously registered callback to $events
$st->remove_callback();
Remove a previously registered callback

CONSTANTS

Create a stream which will not block when performing I/O
The stream has data available for read without blocking
The stream has ability to write data without blocking
An error occurred on the stream
The remote end of the stream closed

AUTHORS

Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT

Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either the GNU General Public License as published by the Free Software Foundation (either version 2 of the License, or at your option any later version), or, the Artistic License, as specified in the Perl README file.

SEE ALSO

Sys::Virt, Sys::Virt::Error, "http://libvirt.org"

2024-03-07 perl v5.38.2