Amanda::Chunker::Scribe
step start_scribe => sub {
my $scribe = Amanda::Chunker::Scribe->new(
feedback => $feedback_obj);
$scribe->start(
write_timestamp => $write_timestamp);
};
step start_xfer => sub {
my ($err) = @_;
my $xfer_dest = $scribe->get_xfer_dest(
max_memory => 32*1024*64);
# .. set up the rest of the transfer ..
$xfer->start(sub {
my ($src, $msg, $xfer) = @_;
$scribe->handle_xmsg($src, $msg, $xfer);
# .. any other processing ..
};
# tell the scribe to start dumping via this transfer
$scribe->start_dump(
xfer => $xfer,
dump_header => $hdr,
dump_cb => $steps->{'dump_cb'},
filename => $filename,
use_bytes => $use_bytes,
chunk_size => $chunk_size);
};
step dump_cb => sub {
my %params = @_;
# .. handle dump results ..
print "DONE\n";
$finished_cb->();
};This package provides a high-level abstraction of Amanda's procedure for writing dumpfiles to holding disk.
Amanda writes a sequence of chunkfile to a sequence of holding disk.
The details of efficiently write to holding disk are handled by the low-level Amanda::Xfer::Dest::Chunker subclasses. The Scribe creates an instance of the appropriate subclass. It calls a number of Amanda::Chunker::Scribe::Feedback methods to indicate the status of the dump process and to request permission to use more holding disk.
The Amanda::Chunker::Scribe constructor takes one arguments: feedback. It specifies the Feedback object that will receive notifications from the Scribe (see below).
my $scribe = Amanda::Chunker::Scribe->new(
feedback => $my_feedback);Once the object is in place, call its start method.
Start the scribe's operation by calling its start method. The method takes one parameters:
$scribe->start(
write_timestamp => $ts);The timestamp will be written to each holding disk written by the Scribe
Once the Scribe is started, begin transferring a dumpfile. This is a three-step process: first, get an Amanda::Xfer::Dest::Chunker object from the Scribe, then start the transfer, and finally let the Scribe know that the transfer has started. Note that the Scribe supplies and manages the transfer destination, but the transfer itself remains the responsibility of the caller.
The parameter to get_xfer_dest are:
max_memorymaximun size to use on the holding disk.
Armed with the element returned by get_xfer_dest, the caller should create a source element and a transfer object and start the transfer. In order to manage the holding chunk process, the Scribe needs to be informed, via its handle_xmsg method, of all transfer messages . This is usually accomplished with something like:
$xfer->start(sub {
my ($src, $msg, $xfer) = @_;
$scribe->handle_xmsg($src, $msg, $xfer);
});Once the transfer has started, the Scribe is ready to begin writing chunk to holding disk. This is the first moment at which the Scribe needs a header, too. All of this is supplied to the start_dump method:
$scribe->start_dump(
xfer => $xfer,
dump_header => $hdr,
filename => $filename,
use_bytes => $use_bytes,
chunk_size => $chunk_size,
dump_cb => $dump_cb);The c<dump_header> here is the header that will be applied to all chunk of the dumpfile. The only field in the header that the Scribe controls is the cont_filename. The dump_cb callback passed to start_dump is called when the dump is completely finished - either successfully or with a fatal error. Unlike most callbacks, this one takes keyword arguments, since it has so many parameters.
$dump_cb->(
result => $result,
header_size => $header_size,
data_size => $data_size,
total_duration => $total_duration);All parameters will be present on every call, although the order is not guaranteed.
The result is one of "FAILED", "PARTIAL", or "DONE". Even when dump_cb reports a fatal error, result may be "PARTIAL" if some data was written successfully.
The holding_error key points to a list of errors, each given as a string, that describe what went wrong to cause the dump to fail.
The final parameters, size (in bytes), total_duration (in seconds), and nparts describe the total transfer, and are a sum of all of the parts written to the device. total_duration reflects the time from the start_dump call to the invocation of the dump_cb.
After you have requested a transfer destination, the scribe is poised to begin the transfer. If you cannot actually perform the transfer for some reason, you'll need to go through the motions all the same, but cancel the operation immediately. That can be done by calling cancel_dump:
$scribe->cancel_dump(
xfer => $xfer,
dump_cb => $dump_cb);When all of the dumpfiles are transferred, call the quit method to release any resources and clean up. This method takes a typical finished_cb.
$scribe->quit(finished_cb => sub {
print "ALL DONE!\n";
});The get_bytes_written returns the number of bytes written to the device at the time of the call, and is meant to be used for status reporting. This value is updated at least as each part is finished; for some modes of operation, it is updated continuously. Notably, DirectTCP transfers do not update continuously.
The Amanda::Chunker::Scribe::Feedback class is intended to be subclassed by the user. It provides a number of notification methods that enable the historical logging and driver/chunker interactions required by Amanda. The parent class does nothing of interest, but allows subclasses to omit methods they do not need.
$fb->notif_no_room($use_bytes, $mesg);The request_more_disk method provides a means for the caller to ask for more holding disk. It is called as
$fb->request_more_disk(perm_cb => $cb);All of the remaining methods are notifications, and do not take a callback.
$fb->scribe_notif_no_room();The Scribe calls scribe_notif_no_room when there is no more space allocated on the holding disk.
Finally, the Scribe sends a few historically significant trace log messages via scribe_notif_log_info:
$fb->scribe_notif_log_info(
message => $message);A typical Feedback subclass might begin like this:
package main::Feedback;
use Amanda::Chunker::Scribe;
use parent -norequire, 'Amanda::Chunker::Scribe::Feedback';
sub request_more_disk {
my $self = shift;
my %params = @_;
$self->{'proto'}->send(Amanda::Chunker::Protocol::RQ_MORE_DISK,
handle => $self->{'handle'});
}This page was automatically generated Tue Mar 19 07:08:15 2019 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.