DBM::Deep::Engine man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

DBM::Deep::Engine(3)  User Contributed Perl Documentation DBM::Deep::Engine(3)

NAME
       DBM::Deep::Engine

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 wiill 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.14.1			  2011-07-15		  DBM::Deep::Engine(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net