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

perl v5.36.0                                       2023-11-12                             DBM::Deep::Engine(3pm)