NAME
DBM::Deep::Engine
PURPOSE
This is an internal-use-only object for "" in DBM::Deep. It mediates the low-level mapping between the "" in 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_fh
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 stil 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 it 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 synchonized writes. To do this, we would have to use a much higher RAM footprint and some serious programming that make my head hurts just to think about it.
EXTERNAL METHODS
new()
This takes a set of args. These args are described in the documentation for "new" in DBM::Deep.
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 "" in DBM::Deep.
This returns 1 upon success.
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().
setup_fh( $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.
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 all locks taken.
This returns nothing.
INTERNAL METHODS
The following methods are internal-use-only to DBM::Deep::Engine.
read_txn_slots()
This takes no arguments.
This will return an array with a 1 or 0 in each slot. Each spot represents one available transaction. If the slot is 1, that transaction is taken. If it is 0, the transaction is available.
write_txn_slots( @slots )
This takes an array of 1's and 0's. This array represents the transaction slots returned by "read_txn_slots()". In other words, the following is true:
@x = read_txn_slots( write_txn_slots( @x ) );(With the obviously missing object referents added back in.)
get_running_txn_ids()
This takes no arguments.
This will return an array of taken transaction IDs. This wraps "read_txn_slots()".
get_txn_staleness_counter( $trans_id )
This will return the staleness counter for the given transaction ID. Please see "TRANSACTION STALENESS" for more information.
inc_txn_staleness_counter( $trans_id )
This will increment the staleness counter for the given transaction ID. Please see "TRANSACTION STALENESS" for more information.
get_entries()
This takes no arguments.
This returns a list of all the sectors that have been modified by this transaction.
add_entry( $trans_id, $location )
This takes a transaction ID and a file location and marks the sector at that location as having been modified by the transaction identified by $trans_id.
This returns nothing.
NOTE: Unlike all the other _entries() methods, there are several cases where $trans_id != $self->trans_id for this method.
reindex_entry( $old_loc, $new_loc )
This takes two locations (old and new, respectively). If a location that has been modified by this transaction is subsequently reindexed due to a bucketlist overflowing, then the entries hash needs to be made aware of this change.
This returns nothing.
clear_entries()
This takes no arguments. It will clear the entries list for the running transaction.
This returns nothing.
_write_file_header()
This writes the file header for a new file. This will write the various settings that set how the file is interpreted.
_read_file_header()
This reads the file header from an existing file. This will read the various settings that set how the file is interpreted.
_load_sector( $offset )
This will instantiate and return the sector object that represents the data found at $offset.
_apply_digest( @stuff )
This will apply the digest methd (default to Digest::MD5::md5) to the arguments passed in and return the result.
_add_free_blist_sector( $offset, $size )
_add_free_data_sector( $offset, $size )
_add_free_index_sector( $offset, $size )
These methods are all wrappers around _add_free_sector(), providing the proper chain offset ($multiple) for the sector type.
_add_free_sector( $multiple, $offset, $size )
_add_free_sector() takes the offset into the chains location, the offset of the sector, and the size of that sector. It will mark the sector as a free sector and put it into the list of sectors that are free of this type for use later.
This returns nothing.
NOTE: $size is unused?
_request_blist_sector( $size )
_request_data_sector( $size )
_request_index_sector( $size )
These methods are all wrappers around _request_sector(), providing the proper chain offset ($multiple) for the sector type.
_request_sector( $multiple $size )
This takes the offset into the chains location and the size of that sector.
This returns the object with the sector. If there is an available free sector of that type, then it will be reused. If there isn't one, then a new one will be allocated.
flush()
This takes no arguments. It will do everything necessary to flush all things to disk. This is usually called during unlock() and setup_fh().
This returns nothing.
ACCESSORS
The following are readonly attributes.
storage
byte_size
hash_size
hash_chars
num_txns
max_buckets
blank_md5
data_sector_size
txn_bitfield_len
The following are read/write attributes.
trans_id / set_trans_id( $new_id )
trans_loc / set_trans_loc( $new_loc )
chains_loc / set_chains_loc( $new_loc )
_dump_file()
This method takes no arguments. It's used to print out a textual representation of the DBM::Deep DB file. It assumes the file is not-corrupted.