Changer API: Difference between revisions
Jump to navigation
Jump to search
(Changer API moved to Changer API (1.0): Move old version documentation away) |
(not really done yet :)) |
||
| Line 1: | Line 1: | ||
This is a developer-level description of Changer API v. 2.0, which was introduced in Amanda-2.6.1. For the old (pre-2.6.1) changer API, see [[Changer API (1.0)]]. | |||
= Links = | |||
Detailed documentation of the Changer API is available directly in the source code, in the form of perldoc. See {{pod|Amanda::Changer}}. | |||
= Motivation for the Change = | |||
The previous [[Changer API (1.0)]] had a few design deficiencies which made it incompatible with the needs of future versions of Amanda. | |||
* All changer invocations are synchronous - Amanda stops to wait for the changer operation to complete. | |||
* There is no mechanism to mark a device as "in use." Amanda has historically handled this by only allowing one process with access to the drive to run at any time, but modern users demand more concurrency than this. | |||
* There is no mechanism to operate multiple, independent changers simultaneously - nor even to configure them. Tape-changer configuration is done with global Amanda parameters, and most scripts fetch their configuration using {{man|8|amgetconf}}. | |||
* The exiting interface requires callers to handle four semantically distinct types of changers: no changer at all (tpchanger=''), gravity changers, unsearchable changers, and searchable changers. | |||
* The exiting interface does not support advanced operations such as importing or exporting tapes or moving them from slot to slot. | |||
= Operational Overview = | |||
The changer API is a collection of perl modules with the common prefix <tt>Amanda::Changer</tt>. Changers are represented as objects, with (among others) a sophisticated <tt>load()</tt> method which loads a volume and returns a ''reservation'' object. The caller has exclusive use of the underlying device until the reservation is explicitly released. | |||
All operations are asynchronous, meaning that other activities such as file transfers can continue while the changer is performing an operation. As a result, the caller must be running an {{pod|Amanda::MainLoop}}, and the resulting Perl contains a lot of anonymous <tt>sub</tt>s. | |||
= Bits and Pieces = | |||
(stuff I need to put somewhere) | |||
== Configuration Matrix == | |||
What follows is an exhaustive list of the combinations of configuration options for a changer, and the resulting interpretation of the "default" changer. | |||
<table border="1"> | |||
<tr><th>global tapedev</th><th>global tpchanger</th><th>tpchanger in changer def'n</th><th>result</th></tr> | |||
<tr><td>- </td><td>- </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>- </td><td>dev uri </td><td>- </td><td>chg-single with dev</td></tr> | |||
<tr><td>- </td><td>dev alias </td><td>- </td><td>chg-single with dev</td></tr> | |||
<tr><td>- </td><td>changer uri </td><td>- </td><td>given changer with no config</td></tr> | |||
<tr><td>- </td><td>changer alias </td><td>changer uri </td><td>given changer with config from def'n</td></tr> | |||
<tr><td>- </td><td>changer alias </td><td>changer script</td><td>chg-compat with config from def'n</td></tr> | |||
<tr><td>- </td><td>changer script</td><td>- </td><td>chg-compat with global config</td></tr> | |||
<tr><td>dev uri </td><td>- </td><td>- </td><td>chg-single with dev</td></tr> | |||
<tr><td>dev uri </td><td>dev uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev uri </td><td>dev alias </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev uri </td><td>changer uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev uri </td><td>changer alias </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>dev uri </td><td>changer alias </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>dev uri </td><td>changer script</td><td>- </td><td>chg-compat with global config</td></tr> | |||
<tr><td>dev alias </td><td>- </td><td>- </td><td>chg-single with dev</td></tr> | |||
<tr><td>dev alias </td><td>dev uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev alias </td><td>dev alias </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev alias </td><td>changer uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>dev alias </td><td>changer alias </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>dev alias </td><td>changer alias </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>dev alias </td><td>changer script</td><td>- </td><td>chg-compat with global config</td></tr> | |||
<tr><td>changer uri </td><td>- </td><td>- </td><td>changer with global config</td></tr> | |||
<tr><td>changer uri </td><td>dev uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>changer uri </td><td>dev alias </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>changer uri </td><td>changer uri </td><td>- </td><td>invalid</td></tr> | |||
<tr><td>changer uri </td><td>changer alias </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer uri </td><td>changer alias </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>changer uri </td><td>changer script</td><td>- </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>- </td><td>changer uri </td><td>changer with config from def'n</td></tr> | |||
<tr><td>changer alias </td><td>- </td><td>changer script</td><td>chg-compat with config from def'n</td></tr> | |||
<tr><td>changer alias </td><td>dev uri </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>dev uri </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>dev alias </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>dev alias </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer uri </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer uri </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer alias </td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer alias </td><td>changer script</td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer script</td><td>changer uri </td><td>invalid</td></tr> | |||
<tr><td>changer alias </td><td>changer script</td><td>changer script</td><td>invalid</td></tr> | |||
</table> | |||
Revision as of 23:12, 13 December 2008
This is a developer-level description of Changer API v. 2.0, which was introduced in Amanda-2.6.1. For the old (pre-2.6.1) changer API, see Changer API (1.0).
Links
Detailed documentation of the Changer API is available directly in the source code, in the form of perldoc. See Amanda::Changer.
Motivation for the Change
The previous Changer API (1.0) had a few design deficiencies which made it incompatible with the needs of future versions of Amanda.
- All changer invocations are synchronous - Amanda stops to wait for the changer operation to complete.
- There is no mechanism to mark a device as "in use." Amanda has historically handled this by only allowing one process with access to the drive to run at any time, but modern users demand more concurrency than this.
- There is no mechanism to operate multiple, independent changers simultaneously - nor even to configure them. Tape-changer configuration is done with global Amanda parameters, and most scripts fetch their configuration using amgetconf(8).
- The exiting interface requires callers to handle four semantically distinct types of changers: no changer at all (tpchanger=), gravity changers, unsearchable changers, and searchable changers.
- The exiting interface does not support advanced operations such as importing or exporting tapes or moving them from slot to slot.
Operational Overview
The changer API is a collection of perl modules with the common prefix Amanda::Changer. Changers are represented as objects, with (among others) a sophisticated load() method which loads a volume and returns a reservation object. The caller has exclusive use of the underlying device until the reservation is explicitly released.
All operations are asynchronous, meaning that other activities such as file transfers can continue while the changer is performing an operation. As a result, the caller must be running an Amanda::MainLoop, and the resulting Perl contains a lot of anonymous subs.
Bits and Pieces
(stuff I need to put somewhere)
Configuration Matrix
What follows is an exhaustive list of the combinations of configuration options for a changer, and the resulting interpretation of the "default" changer.
| global tapedev | global tpchanger | tpchanger in changer def'n | result |
|---|---|---|---|
| - | - | - | invalid |
| - | dev uri | - | chg-single with dev |
| - | dev alias | - | chg-single with dev |
| - | changer uri | - | given changer with no config |
| - | changer alias | changer uri | given changer with config from def'n |
| - | changer alias | changer script | chg-compat with config from def'n |
| - | changer script | - | chg-compat with global config |
| dev uri | - | - | chg-single with dev |
| dev uri | dev uri | - | invalid |
| dev uri | dev alias | - | invalid |
| dev uri | changer uri | - | invalid |
| dev uri | changer alias | changer uri | invalid |
| dev uri | changer alias | changer script | invalid |
| dev uri | changer script | - | chg-compat with global config |
| dev alias | - | - | chg-single with dev |
| dev alias | dev uri | - | invalid |
| dev alias | dev alias | - | invalid |
| dev alias | changer uri | - | invalid |
| dev alias | changer alias | changer uri | invalid |
| dev alias | changer alias | changer script | invalid |
| dev alias | changer script | - | chg-compat with global config |
| changer uri | - | - | changer with global config |
| changer uri | dev uri | - | invalid |
| changer uri | dev alias | - | invalid |
| changer uri | changer uri | - | invalid |
| changer uri | changer alias | changer uri | invalid |
| changer uri | changer alias | changer script | invalid |
| changer uri | changer script | - | invalid |
| changer alias | - | changer uri | changer with config from def'n |
| changer alias | - | changer script | chg-compat with config from def'n |
| changer alias | dev uri | changer uri | invalid |
| changer alias | dev uri | changer script | invalid |
| changer alias | dev alias | changer uri | invalid |
| changer alias | dev alias | changer script | invalid |
| changer alias | changer uri | changer uri | invalid |
| changer alias | changer uri | changer script | invalid |
| changer alias | changer alias | changer uri | invalid |
| changer alias | changer alias | changer script | invalid |
| changer alias | changer script | changer uri | invalid |
| changer alias | changer script | changer script | invalid |