This is an internal-use-only object for DBM::Deep.
It mediates the low-level mapping between the DBM::Deep objects and the storage medium.

The purpose of this documentation is to provide low-level documentation for developers.
It is not intended to be used by the general public.
This documentation and what it documents can and will change without notice.

The engine exposes an API to the DBM::Deep objects (DBM::Deep,
DBM::Deep::Array,
and DBM::Deep::Hash) for their use to access the actual stored values.
This API is the following:

new

read_value

get_classname

make_reference

key_exists

delete_key

write_value

get_next_key

setup

clear

begin_work

commit

rollback

lock_exclusive

lock_shared

unlock

They are explained in their own sections below.
These methods,
in turn,
may provide some bounds-checking,
but primarily act to instantiate objects in the Engine::Sector::* hierarchy and dispatch to them.

Transactions in DBM::Deep are implemented using a variant of MVCC.
This attempts to keep the amount of actual work done against the file low while still providing Atomicity,
Consistency,
and Isolation.
Durability,
unfortunately,
cannot be done with only one file.

If another process uses a transaction slot and writes stuff to it,
then terminates,
the data that process wrote is still within the file.
In order to address this,
there is also a transaction staleness counter associated within every write.
Each time a transaction is started,
that process increments that transaction's staleness counter.
If,
when it reads a value,
the staleness counters aren't identical,
DBM::Deep will consider the value on disk to be stale and discard it.

The fourth leg of ACID is Durability,
the guarantee that when a commit returns,
the data will be there the next time you read from it.
This should be regardless of any crashes or powerdowns in between the commit and subsequent read.
DBM::Deep does provide that guarantee; once the commit returns,
all of the data has been transferred from the transaction shadow to the HEAD.
The issue arises with partial commits - a commit that is interrupted in some fashion.
In keeping with DBM::Deep's "tradition" of very light error-checking and non-existent error-handling,
there is no way to recover from a partial commit.
(This is probably a failure in Consistency as well as Durability.)

Other DBMSes use transaction logs (a separate file,
generally) to achieve Durability.
As DBM::Deep is a single-file,
we would have to do something similar to what SQLite and BDB do in terms of committing using synchronized writes.
To do this,
we would have to use a much higher RAM footprint and some serious programming that makes my head hurt just to think about it.

This takes an object that provides _base_offset() and two strings.
The strings correspond to the old key and new key,
respectively.
This operation is equivalent to (given $db->{foo} = [];) $db->{bar} = $db->{foo}.

This takes an object that provides _base_offset().
It will do everything needed in order to properly initialize all values for necessary functioning.
If this is called upon an already initialized object,
this will also reset the inode.