1Sys::Virt::Stream(3pm)User Contributed Perl DocumentationSys::Virt::Stream(3pm)
2
6 Sys::Virt::Stream - Represent & manage a libvirt stream
7
9 The "Sys::Virt::Stream" module represents a stream managed by the
10 virtual machine monitor.
11
13 my $st Sys::Virt::Stream->new($conn, $flags);
14 Creates a new data stream, ready for use with a stream based API.
15 The optional $flags parameter can be used to configure the stream
16 as non-blocking
17 $st->abort()
19 Abort I/O on the stream. Either this function or "finish" must be
20 called on any stream which has been activated
21 $st->finish()
23 Complete I/O on the stream. Either this function or "abort" must be
24 called on any stream which has been activated
25 $rv = $st->recv($data, $nbytes, $flags=0)
27 Receive up to $nbytes worth of data, copying into $data. Returns
28 the number of bytes read, or -3 if hole is reached and $flags
29 contains RECV_STOP_AT_HOLE, or -2 if I/O would block, or -1 on
30 error. The $flags parameter accepts the following flags:
31 Sys::Virt::Stream::RECV_STOP_AT_HOLE
33 If this flag is set, the "recv" function will stop reading from
34 stream if it has reached a hole. In that case, -3 is returned
35 and "recv_hole" should be called to get the hole size.
36 $rv = $st->send($data, $nbytes)
38 Send up to $nbytes worth of data, copying from $data. Returns the
39 number of bytes sent, or -2 if I/O would block, or -1 on error.
40 $rv = $st->recv_hole($flags=0)
42 Determine the amount of the empty space (in bytes) to be created in
43 a stream's target file when uploading or downloading sparsely
44 populated files. This is the counterpart to "send_hole". The
45 optional $flags parameter is currently unused and defaults to zero
46 if omitted.
47 $st->send_hole($length, $flags=0)
49 Rather than transmitting empty file space, this method directs the
50 stream target to create $length bytes of empty space. This method
51 would be used when uploading or downloading sparsely populated
52 files to avoid the needless copy of empty file space. The optional
53 $flags parameter is currently unused and defaults to zero if
54 omitted.
55 $st->recv_all($handler)
57 Receive all data available from the stream, invoking $handler to
58 process the data. The $handler parameter must be a function which
59 expects three arguments, the $st stream object, a scalar containing
60 the data received and a data byte count. The function should return
61 the number of bytes processed, or -1 upon error.
62 $st->send_all($handler)
64 Send all data produced by $handler to the stream. The $handler
65 parameter must be a function which expects three arguments, the $st
66 stream object, a scalar which must be filled with data and a
67 maximum data byte count desired. The function should return the
68 number of bytes filled, 0 on end of file, or -1 upon error
69 $st->sparse_recv_all($handler, $hole_handler)
71 Receive all data available from the sparse stream, invoking
72 $handler to process the data. The $handler parameter must be a
73 function which expects three arguments, the $st stream object, a
74 scalar containing the data received and a data byte count. The
75 function should return the number of bytes processed, or -1 upon
76 error. The second argument $hole_handler is a function which
77 expects two arguments: the $st stream and a scalar, number
78 describing the size of the hole in the stream (in bytes). The
79 $hole_handler is expected to return a non-negative number on
80 success (usually 0) and a negative number (usually -1) otherwise.
81 $st->sparse_send_all($handler, $hole_handler, $skip_handler)
83 Send all data produced by $handler to the stream. The $handler
84 parameter must be a function which expects three arguments, the $st
85 stream object, a scalar which must be filled with data and a
86 maximum data byte count desired. The function should return the
87 number of bytes filled, 0 on end of file, or -1 upon error. The
88 second argument $hole_handler is a function expecting just one
89 argument $st and returning an array of two elements ($in_data,
90 $section_len) where $in_data has zero or non-zero value if
91 underlying file is in a hole or data section respectively. The
92 $section_len then is the number of remaining bytes in the current
93 section in the underlying file. Finally, the third $skip_handler is
94 a function expecting two arguments $st and $length which moves
95 cursor in the underlying file for $length bytes. The $skip_handler
96 is expected to return a non-negative number on success (usually 0)
97 and a negative number (usually -1) otherwise.
98 $st->add_callback($events, $coderef)
100 Register a callback to be invoked whenever the stream has one or
101 more events from $events mask set. The $coderef must be a
102 subroutine that expects 2 parameters, the original $st object and
103 the new $events mask
104 $st->update_callback($events)
106 Change the event mask for a previously registered callback to
107 $events
108 $st->remove_callback();
110 Remove a previously registered callback
111
113 Sys::Virt::Stream::NONBLOCK
114 Create a stream which will not block when performing I/O
115 Sys::Virt::Stream::EVENT_READABLE
117 The stream has data available for read without blocking
118 Sys::Virt::Stream::EVENT_WRITABLE
120 The stream has ability to write data without blocking
121 Sys::Virt::Stream::EVENT_ERROR
123 An error occurred on the stream
124 Sys::Virt::Stream::EVENT_HANGUP
126 The remote end of the stream closed
127
129 Daniel P. Berrange <berrange@redhat.com>
130
132 Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P.
133 Berrange
134
136 This program is free software; you can redistribute it and/or modify it
137 under the terms of either the GNU General Public License as published
138 by the Free Software Foundation (either version 2 of the License, or at
139 your option any later version), or, the Artistic License, as specified
140 in the Perl README file.
141
143 Sys::Virt, Sys::Virt::Error, "http://libvirt.org"
144perl v5.38.0 2023-09-08 Sys::Virt::Stream(3pm)