-%perlcode %{
-=head1 NAME
-
-Amanda::Xfer - the transfer architecture
-
-=head1 SYNOPSIS
-
- 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.
-
-=head1 API STATUS
-
-Fluid.
-
-=head1 Amanda::Xfer Objects
-
-A new transfer is created with C<< Amanda::Xfer->new() >>, which takes an arrayref
-giving the transfer elements which should compose the transfer.
-
-The resulting object has the following methods:
-
-=over
-
-=item get_source()
-
-Get the L<Amanda::MainLoop> event source through which messages will be
-delivered for this transfer. Use its C<set_callback> method to connect a perl
-sub for processing events. You I<must> C<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
-C<Amanda::Xfer::Msg>, below, for details.
-
-=item start()
-
-Start this transfer. Processing takes place asynchronously, and messages will
-begin queueing up immediately.
-
-=item cancel()
-
-Stop transferring data. The transfer will send an C<XMSG_CANCEL>, "drain" any
-buffered data as best it can, and then complete normally with an C<XMSG_DONE>.
-
-=item get_status()
-
-Get the transfer's status. The result will be one of C<$XFER_INIT>,
-C<$XFER_START>, C<$XFER_RUNNING>, or C<$XFER_DONE>. These symbols are
-available for import with the tag C<:constants>.
-
-=item 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";
-
-=back
-
-=head1 Amanda::Xfer::Element objects
-
-The individual transfer elements that compose a transfer are instances of
-subclasses of Amanda::Xfer::Element. All such objects have a C<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.
-
-=head2 Transfer Sources
-
-=head3 Amanda::Xfer::Source::Device
-
- Amanda::Xfer::Source::Device->new($device);
-
-This source reads data from a device. The device should already be queued up
-for reading (C<$device->seek_file(..)>). The element will read until the end
-of the device file.
-
-=head3 Amanda::Xfer::Source::Fd
-
- 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!
-
-=head3 Amanda::Xfer::Source::Random
-
- Amanda::Xfer::Source::Random->new($length, $seed);
-
-This source provides I<length> bytes of random data (or an unlimited amount
-of data if I<length> is zero). C<$seed> is the seed used
-to generate the random numbers; this seed can be used in a destination to
-check for correct output.
-
-=head3 Amanda::Xfer::Source::Pattern
-
- Amanda::Xfer::Source::Pattern->new($length, $pattern);
-
-This source provides I<length> bytes containing copies of
-I<pattern>. If I<length> is zero, the source provides an unlimited
-number of bytes.
-
-=head2 Transfer Filters
-
-=head3 Amanda::Xfer::Filter:Xor
-
- Amanda::Xfer::Filter::Xor->new($key);
-
-This filter applies a bytewise XOR operation to the data flowing through it.
-
-=head2 Transfer Destinations
-
-=head3 Amanda::Xfer::Dest::Device
-
- Amanda::Xfer::Dest::Device->new($device, $max_memory);
-
-This source writes data to a device. The device should already be queued up
-for writing (C<$device->start_file(..)>). No more than C<$max_memory> will be
-used for buffers. Use zero for the default buffer size. On completion of the
-transfer, the file will be finished.
-
-=head3 Amanda::Xfer::Dest::Fd
-
- 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!
-
-=head3 Amanda::Xfer::Dest::Null
-
- Amanda::Xfer::Dest::Null->new($seed);
-
-This destination discards the data it receives. If C<$seed> is nonzero, then
-the element will validate that it receives the data that
-C<Amanda::Xfer::Source::Random> produced with the same seed. No validation is
-performed if C<$seed> is zero.
-
-=head1 Amanda::Xfer::Msg objects
-
-Messages are simple hashrefs, with a few convenience methods. Like transfers,
-they have a C<repr()> method that formats the message nicely, and is available
-through string interpolation:
- print "Received message $msg\n";
-
-Every message has the following keys:
-
-=over
-
-=item type
-
-The message type -- one of the C<xmsg_type> constants available from the import
-tag C<:constants>.
-
-=item elt
-
-The transfer element that sent the message.
-
-=item version
-
-The version of the message. This is used to support extensibility of the protocol.
-
-=back
-
-The canonical description of the message types and keys is in C<xfer-src/xmsg.h>, and is
-not duplicated here.
-
-=cut
-%}
-