NAME

       DBM::Deep::Engine - mediate mapping between DBM::Deep objects and storage medium

PURPOSE

       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.

OVERVIEW

       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

       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.

   STALENESS
       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.

   DURABILITY
       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.

METHODS

   read_value( $obj, $key )
       This takes an object that provides _base_offset() and a string. It returns the value
       stored in the corresponding Sector::Value's data section.

   get_classname( $obj )
       This takes an object that provides _base_offset() and returns the classname (if any)
       associated with it.

       It delegates to Sector::Reference::get_classname() for the heavy lifting.

       It performs a staleness check.

   make_reference( $obj, $old_key, $new_key )
       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 returns nothing.

   key_exists( $obj, $key )
       This takes an object that provides _base_offset() and a string for the key to be checked.
       This returns 1 for true and "" for false.

   delete_key( $obj, $key )
       This takes an object that provides _base_offset() and a string for the key to be deleted.
       This returns the result of the Sector::Reference delete_key() method.

   write_value( $obj, $key, $value )
       This takes an object that provides _base_offset(), a string for the key, and a value. This
       value can be anything storable within DBM::Deep.

       This returns 1 upon success.

   setup( $obj )
       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.

       This returns 1.

   begin_work( $obj )
       This takes an object that provides _base_offset(). It will set up all necessary
       bookkeeping in order to run all work within a transaction.

       If $obj is already within a transaction, an error will be thrown. If there are no more
       available transactions, an error will be thrown.

       This returns undef.

   rollback( $obj )
       This takes an object that provides _base_offset(). It will revert all actions taken within
       the running transaction.

       If $obj is not within a transaction, an error will be thrown.

       This returns 1.

   commit( $obj )
       This takes an object that provides _base_offset(). It will apply all actions taken within
       the transaction to the HEAD.

       If $obj is not within a transaction, an error will be thrown.

       This returns 1.

   get_next_key( $obj, $prev_key )
       This takes an object that provides _base_offset() and an optional string representing the
       prior key returned via a prior invocation of this method.

       This method delegates to "DBM::Deep::Iterator->get_next_key()".

   lock_exclusive()
       This takes an object that provides _base_offset(). It will guarantee that the storage has
       taken precautions to be safe for a write.

       This returns nothing.

   lock_shared()
       This takes an object that provides _base_offset(). It will guarantee that the storage has
       taken precautions to be safe for a read.

       This returns nothing.

   unlock()
       This takes an object that provides _base_offset(). It will guarantee that the storage has
       released the most recently-taken lock.

       This returns nothing.

INTERNAL METHODS

       The following methods are internal-use-only to DBM::Deep::Engine and its child classes.

   flush()
       This takes no arguments. It will do everything necessary to flush all things to disk. This
       is usually called during unlock() and setup().

       This returns nothing.

   load_sector( $loc )
       This takes an id/location/offset and loads the sector based on the engine's defined sector
       type.

   clear( $obj )
       This takes an object that provides _base_offset() and deletes all its elements, returning
       nothing.

   cache / clear_cache
       This is the cache of loaded Reference sectors.

   supports( $option )
       This returns a boolean depending on if this instance of DBM::Dep supports that feature.
       $option can be one of:

       •   transactions

       •   singletons

       Any other value will return false.

ACCESSORS

       The following are readonly attributes.

       •   storage

       •   sector_type

       •   iterator_class