Amanda::Xfer - the transfer architecture
use Amanda::MainLoop; use Amanda::Xfer qw( :constants ); use POSIX;
my $infd = POSIX::open("input", POSIX::O_RDONLY, 0);
my $outfd = POSIX::open("output", POSIX::O_CREAT|POSIX::O_WRONLY, 0640);
my $xfer = Amanda::Xfer->new([
Amanda::Xfer::Source::Fd->new($infd),
Amanda::Xfer::Dest::Fd->new($outfd)
]);
$xfer->get_source()->set_callback(sub {
my ($src, $xmsg, $xfer) = @_;
print "Message from $xfer: $xmsg\n"; # use stringify operations
if ($xfer->get_status() == $XFER_DONE) {
$src->remove();
Amanda::MainLoop::quit();
}
});
$xfer->start();
Amanda::MainLoop::run();
See L<http://wiki.zmanda.com/index.php/XFA>; for background on the transfer
architecture.
Fluid.
A new transfer is created with Amanda::Xfer->new(), which takes an arrayref
giving the transfer elements which should compose the transfer.
The resulting object has the following methods:
get_source()
Get the the Amanda::MainLoop manpage event source through which messages will be
delivered for this transfer. Use its set_callback method to connect a perl
sub for processing events. You must release the source when the
transfer is complete!
The callback from this event source receives three arguments: the event source,
the message, and a reference to the controlling transfer. See the description of
Amanda::Xfer::Msg, below, for details.
start()
Start this transfer. Processing takes place asynchronously, and messages will begin queueing up immediately.
cancel()
Stop transferring data. The transfer will send an XMSG_CANCEL, ``drain'' any
buffered data as best it can, and then complete normally with an XMSG_DONE.
get_status()
Get the transfer's status. The result will be one of $XFER_INIT,
$XFER_START, $XFER_RUNNING, or $XFER_DONE. These symbols are
available for import with the tag :constants.
repr()
Return a string representation of this transfer, suitable for use in debugging messages. This method is automatically invoked when a transfer is interpolated into a string: print ``Starting $xfer\n'';
The individual transfer elements that compose a transfer are instances of
subclasses of Amanda::Xfer::Element. All such objects have a repr() method,
similar to that for transfers, and support a similar kind of string
interpolation.
Note that the names of these classes contain the words ``Source'', ``Filter'', and ``Dest''. This is merely suggestive of their intended purpose -- there are no such abstract classes.
Amanda::Xfer::Source::Device->new($device);
This source reads data from a device. The device should already be queued up
for reading ($device-seek_file(..)>). The element will read until the end
of the device file.
Amanda::Xfer::Source::Fd->new(fileno($fh));
This source reads data from a file descriptor. It reads until EOF, but does not close the descriptor. Be careful not to let Perl close the file for you!
Amanda::Xfer::Source::Random->new($length, $seed);
This source provides length bytes of random data (or an unlimited amount
of data if length is zero). $seed is the seed used
to generate the random numbers; this seed can be used in a destination to
check for correct output.
Amanda::Xfer::Source::Pattern->new($length, $pattern);
This source provides length bytes containing copies of pattern. If length is zero, the source provides an unlimited number of bytes.
Amanda::Xfer::Filter::Xor->new($key);
This filter applies a bytewise XOR operation to the data flowing through it.
Amanda::Xfer::Dest::Device->new($device, $max_memory);
This source writes data to a device. The device should already be queued up
for writing ($device-start_file(..)>). No more than $max_memory will be
used for buffers. Use zero for the default buffer size. On completion of the
transfer, the file will be finished.
Amanda::Xfer::Dest::Fd->new(fileno($fh));
This destination writes data to a file descriptor. The file is not closed after the transfer is completed. Be careful not to let Perl close the file for you!
Amanda::Xfer::Dest::Null->new($seed);
This destination discards the data it receives. If $seed is nonzero, then
the element will validate that it receives the data that
Amanda::Xfer::Source::Random produced with the same seed. No validation is
performed if $seed is zero.
Messages are simple hashrefs, with a few convenience methods. Like transfers,
they have a repr() method that formats the message nicely, and is available
through string interpolation:
print ``Received message $msg\n'';
Every message has the following keys:
The message type -- one of the xmsg_type constants available from the import
tag :constants.
The transfer element that sent the message.
The version of the message. This is used to support extensibility of the protocol.
The canonical description of the message types and keys is in xfer-src/xmsg.h, and is
not duplicated here.
This page was automatically generated Fri Feb 5 19:41:21 2010 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.