This source reads data from a holding file (see L<Amanda::Holding>).
If the transfer only consists of a C<Amanda::Xfer::Source::Holding>
-and an C<Amanda::Xfer::Dest::Taper::Splitter> (with no filters), then the source
+and an C<Amanda::Xfer::Dest::Taper::Cacher> (with no filters), then the source
will call the destination's C<cache_inform> method so that it can use
holding chunks for a split-part cache.
Amanda::Xfer::Source::DirectTCPListen->new();
This source is for use when the transfer data will come in via DirectTCP, with
-the data's I<source> connecting to the data's I<destination>. Set up the
-transfer, and after starting it, call its C<get_addrs> method to get an
-arrayref of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which are
-listening for an incoming data connection. Once a connection arrives, this
-element will read data from it and send those data into the transfer.
+the data's I<source> connecting to the data's I<destination>. That is, the
+data source is the connection initiator. Set up the transfer, and after
+starting it, call this element's C<get_addrs> method to get an arrayref of ip/port pairs,
+e.g., C<[ "192.168.4.5", 9924 ]>, all of which are listening for an incoming
+data connection. Once a connection arrives, this element will read data from
+it and send those data into the transfer.
my $addrs = $src->get_addrs();
Amanda::Xfer::Source::DirectTCPConnect->new($addrs);
This source is for use when the transfer data will come in via DirectTCP, with
-the data's I<destination> connecting to the the data's I<source>. The element
-connects to C<$addrs> and reads the transfer data from the connection.
+the data's I<destination> connecting to the the data's I<source>. That is, the
+data destination is the connection initiator. The element connects to
+C<$addrs> and reads the transfer data from the connection.
=head2 Transfer Filters
=head3 Amanda::Xfer::Filter:Process
- Amanda::Xfer::Filter::Process->new([@args], $need_root);
+ Amanda::Xfer::Filter::Process->new([@args], $need_root, $log_stderr);
This filter will pipe data through the standard file descriptors of the
subprocess specified by C<@args>. If C<$need_root> is true, it will attempt to
change to uid 0 before executing the process. Standard output from the process
is redirected to the debug log. Note that the process is invoked directly, not
via a shell, so shell metacharcters (e.g., C<< 2>&1 >>) will not function as
-expected.
+expected. If C<$log_stderr> is set, then the filter's standard error is sent
+to the debug log; otherwise, it is sent to the parent process's stderr.
=head3 Amanda::Xfer::Filter:Xor
=head3 Amanda::Xfer::Dest::Device (SERVER ONLY)
- Amanda::Xfer::Dest::Device->new($device, $max_memory);
+ Amanda::Xfer::Dest::Device->new($device, $cancel_at_eom);
-This source writes data to a device. The device should be ready 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.
+This source writes data to a device. The device should be ready for writing
+(C<< $device->start_file(..) >>). On completion of the transfer, the file will
+be finished. If an error occurs, or if C<$cancel_at_eom> is true and the
+device signals LEOM, the transfer will be cancelled.
+
+Note that this element does not apply any sort of stream buffering.
=head3 Amanda::Xfer::Dest::Buffer
Amanda::Xfer::Dest::DirectTCPListen->new();
This destination is for use when the transfer data will come in via DirectTCP,
-with the data's I<destination> connecting to the data's I<source>. Set up the
-transfer, and after starting it, call this element's C<get_addrs> method to get
-an arrayref of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which
-are listening for an incoming data connection. Once a connection arrives, this
-element will write the transfer data to it.
+with the data's I<destination> connecting to the data's I<source>. That is,
+the data destination is the connection initiator. Set up the transfer, and
+after starting it, call this element's C<get_addrs> method to get an arrayref
+of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which are listening
+for an incoming data connection. Once a connection arrives, this element will
+write the transfer data to it.
my $addrs = $src->get_addrs();
Amanda::Xfer::Dest::DirectTCPConnect->new($addrs);
This destination is for use when the transfer data will come in via DirectTCP,
-with the data's I<source> connecting to the the data's I<destination>. The
-element connects to C<$addrs> and writes the transfer data to the connection.
+with the data's I<source> connecting to the the data's I<destination>. That
+is, the data source is the connection initiator. The element connects to
+C<$addrs> and writes the transfer data to the connection.
=head3 Amanda::Xfer::Dest::Fd
=head3 Amanda::Xfer::Dest::Taper (SERVER ONLY)
-This is the parent class to C<Amanda::Xfer::Dest::Taper::Splitter> and
+This is the parent class to C<Amanda::Xfer::Dest::Taper::Cacher> and
C<Amanda::Xfer::Dest::Taper::DirectTCP>. These subclasses allow a single
transfer to write to multiple files (parts) on a device, and even spread those
parts over multiple devices, without interrupting the transfer itself.
=head3 Amanda::Xfer::Dest::Taper::Splitter
Amanda::Xfer::Dest::Taper::Splitter->new($first_device, $max_memory,
+ $part_size, $expect_cache_inform);
+
+This class splits a data stream into parts on the storage media. It is for use
+when the device supports LEOM, when the dump is already available on disk
+(C<cache_inform>), or when no caching is desired. It does not cache parts, so
+it can only retry a partial part if the transfer source is calling
+C<cache_inform>. If the element is used with devices that do not support LEOM,
+then it will cancel the entire transfer if the device reaches EOM and
+C<cache_inform> is not in use. Set C<$expect_cache_inform> appropriately based
+on the incoming data.
+
+The C<$part_size> and C<$first_device> parameters are described above for
+C<Amanda::Xfer::Dest::Taper>.
+
+=head3 Amanda::Xfer::Dest::Taper::Cacher
+
+ Amanda::Xfer::Dest::Taper::Cacher->new($first_device, $max_memory,
$part_size, $use_mem_cache, $disk_cache_dirname);
-This class caches data from each part in one of a variety of ways, and supports
-"rewinding" to retry a failed part (e.g., one that does not fit on a device).
-It assumes that when a device reaches EOM while writing, the entire file is
-corrupt. It does not (yet) support logical EOM, which can render this
-assumption incorrect.
+This class is similar to the splitter, but caches data from each part in one of
+a variety of ways to support "rewinding" to retry a failed part (e.g., one that
+does not fit on a device). It assumes that when a device reaches EOM while
+writing, the entire on-volume file is corrupt - that is, that the device does
+not support logical EOM. The class does not support C<cache_inform>.
-The C<$first_device> is used to calculate some internal constants, notably the
-slab size, based on the device characteristics. Subsequent devices must have
-the same block size. The C<$part_size> and C<$first_device> parameters are
-described above.
+The C<$part_size> and C<$first_device> parameters are described above for
+C<Amanda::Xfer::Dest::Taper>.
If C<$use_mem_cache> is true, each part will be cached in memory (using
C<$part_size> bytes of memory; plan accordingly!). If C<$disk_cache_dirname>
is defined, then each part will be cached on-disk in a file in this directory.
It is an error to specify both in-memory and on-disk caching. If neither
option is specified, the element will operate successfully, but will not be
-able to retry a part unless C<cache_inform> has been used properly (see above).
+able to retry a part, and will cancel the transfer if a part fails.
=head3 Amanda::Xfer::Dest::Taper::DirectTCP
projects / debian / amanda / blobdiff