.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBM::Deep::Engine 3pm"
.TH DBM::Deep::Engine 3pm "2018-05-23" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBM::Deep::Engine \- mediate mapping between DBM::Deep objects and storage medium
.SH "PURPOSE"
.IX Header "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.
.PP
The purpose of this documentation is to provide low-level documentation for
developers. It is \fBnot\fR intended to be used by the general public. This
documentation and what it documents can and will change without notice.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
The engine exposes an \s-1API\s0 to the DBM::Deep objects (DBM::Deep, DBM::Deep::Array,
and DBM::Deep::Hash) for their use to access the actual stored values. This \s-1API\s0
is the following:
.IP "\(bu" 4
new
.IP "\(bu" 4
read_value
.IP "\(bu" 4
get_classname
.IP "\(bu" 4
make_reference
.IP "\(bu" 4
key_exists
.IP "\(bu" 4
delete_key
.IP "\(bu" 4
write_value
.IP "\(bu" 4
get_next_key
.IP "\(bu" 4
setup
.IP "\(bu" 4
clear
.IP "\(bu" 4
begin_work
.IP "\(bu" 4
commit
.IP "\(bu" 4
rollback
.IP "\(bu" 4
lock_exclusive
.IP "\(bu" 4
lock_shared
.IP "\(bu" 4
unlock
.PP
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.
.SH "TRANSACTIONS"
.IX Header "TRANSACTIONS"
Transactions in DBM::Deep are implemented using a variant of \s-1MVCC.\s0 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.
.SS "\s-1STALENESS\s0"
.IX Subsection "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.
.SS "\s-1DURABILITY\s0"
.IX Subsection "DURABILITY"
The fourth leg of \s-1ACID\s0 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 \s-1HEAD.\s0 The issue arises
with partial commits \- a commit that is interrupted in some fashion. In keeping
with DBM::Deep's \*(L"tradition\*(R" 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.)
.PP
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 \s-1BDB\s0 do in terms of committing using synchronized
writes. To do this, we would have to use a much higher \s-1RAM\s0 footprint and some
serious programming that makes my head hurt just to think about it.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "read_value( $obj, $key )"
.el .SS "read_value( \f(CW$obj\fP, \f(CW$key\fP )"
.IX Subsection "read_value( $obj, $key )"
This takes an object that provides \fI_base_offset()\fR and a string. It returns the
value stored in the corresponding Sector::Value's data section.
.ie n .SS "get_classname( $obj )"
.el .SS "get_classname( \f(CW$obj\fP )"
.IX Subsection "get_classname( $obj )"
This takes an object that provides \fI_base_offset()\fR and returns the classname (if
any) associated with it.
.PP
It delegates to \fISector::Reference::get_classname()\fR for the heavy lifting.
.PP
It performs a staleness check.
.ie n .SS "make_reference( $obj, $old_key, $new_key )"
.el .SS "make_reference( \f(CW$obj\fP, \f(CW$old_key\fP, \f(CW$new_key\fP )"
.IX Subsection "make_reference( $obj, $old_key, $new_key )"
This takes an object that provides \fI_base_offset()\fR and two strings. The
strings correspond to the old key and new key, respectively. This operation
is equivalent to (given \f(CW\*(C`$db\->{foo} = [];\*(C'\fR) \f(CW\*(C`$db\->{bar} = $db\->{foo}\*(C'\fR.
.PP
This returns nothing.
.ie n .SS "key_exists( $obj, $key )"
.el .SS "key_exists( \f(CW$obj\fP, \f(CW$key\fP )"
.IX Subsection "key_exists( $obj, $key )"
This takes an object that provides \fI_base_offset()\fR and a string for
the key to be checked. This returns 1 for true and "" for false.
.ie n .SS "delete_key( $obj, $key )"
.el .SS "delete_key( \f(CW$obj\fP, \f(CW$key\fP )"
.IX Subsection "delete_key( $obj, $key )"
This takes an object that provides \fI_base_offset()\fR and a string for
the key to be deleted. This returns the result of the Sector::Reference
\&\fIdelete_key()\fR method.
.ie n .SS "write_value( $obj, $key, $value )"
.el .SS "write_value( \f(CW$obj\fP, \f(CW$key\fP, \f(CW$value\fP )"
.IX Subsection "write_value( $obj, $key, $value )"
This takes an object that provides \fI_base_offset()\fR, a string for the
key, and a value. This value can be anything storable within DBM::Deep.
.PP
This returns 1 upon success.
.ie n .SS "setup( $obj )"
.el .SS "setup( \f(CW$obj\fP )"
.IX Subsection "setup( $obj )"
This takes an object that provides \fI_base_offset()\fR. 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.
.PP
This returns 1.
.ie n .SS "begin_work( $obj )"
.el .SS "begin_work( \f(CW$obj\fP )"
.IX Subsection "begin_work( $obj )"
This takes an object that provides \fI_base_offset()\fR. It will set up all necessary
bookkeeping in order to run all work within a transaction.
.PP
If \f(CW$obj\fR is already within a transaction, an error will be thrown. If there are
no more available transactions, an error will be thrown.
.PP
This returns undef.
.ie n .SS "rollback( $obj )"
.el .SS "rollback( \f(CW$obj\fP )"
.IX Subsection "rollback( $obj )"
This takes an object that provides \fI_base_offset()\fR. It will revert all
actions taken within the running transaction.
.PP
If \f(CW$obj\fR is not within a transaction, an error will be thrown.
.PP
This returns 1.
.ie n .SS "commit( $obj )"
.el .SS "commit( \f(CW$obj\fP )"
.IX Subsection "commit( $obj )"
This takes an object that provides \fI_base_offset()\fR. It will apply all
actions taken within the transaction to the \s-1HEAD.\s0
.PP
If \f(CW$obj\fR is not within a transaction, an error will be thrown.
.PP
This returns 1.
.ie n .SS "get_next_key( $obj, $prev_key )"
.el .SS "get_next_key( \f(CW$obj\fP, \f(CW$prev_key\fP )"
.IX Subsection "get_next_key( $obj, $prev_key )"
This takes an object that provides \fI_base_offset()\fR and an optional string
representing the prior key returned via a prior invocation of this method.
.PP
This method delegates to \f(CW\*(C`DBM::Deep::Iterator\->get_next_key()\*(C'\fR.
.SS "\fIlock_exclusive()\fP"
.IX Subsection "lock_exclusive()"
This takes an object that provides \fI_base_offset()\fR. It will guarantee that
the storage has taken precautions to be safe for a write.
.PP
This returns nothing.
.SS "\fIlock_shared()\fP"
.IX Subsection "lock_shared()"
This takes an object that provides \fI_base_offset()\fR. It will guarantee that
the storage has taken precautions to be safe for a read.
.PP
This returns nothing.
.SS "\fIunlock()\fP"
.IX Subsection "unlock()"
This takes an object that provides \fI_base_offset()\fR. It will guarantee that
the storage has released the most recently-taken lock.
.PP
This returns nothing.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
The following methods are internal-use-only to DBM::Deep::Engine and its
child classes.
.SS "\fIflush()\fP"
.IX Subsection "flush()"
This takes no arguments. It will do everything necessary to flush all things to
disk. This is usually called during \fIunlock()\fR and \fIsetup()\fR.
.PP
This returns nothing.
.ie n .SS "load_sector( $loc )"
.el .SS "load_sector( \f(CW$loc\fP )"
.IX Subsection "load_sector( $loc )"
This takes an id/location/offset and loads the sector based on the engine's
defined sector type.
.ie n .SS "clear( $obj )"
.el .SS "clear( \f(CW$obj\fP )"
.IX Subsection "clear( $obj )"
This takes an object that provides \fI_base_offset()\fR and deletes all its 
elements, returning nothing.
.SS "cache / clear_cache"
.IX Subsection "cache / clear_cache"
This is the cache of loaded Reference sectors.
.ie n .SS "supports( $option )"
.el .SS "supports( \f(CW$option\fP )"
.IX Subsection "supports( $option )"
This returns a boolean depending on if this instance of DBM::Dep supports
that feature. \f(CW$option\fR can be one of:
.IP "\(bu" 4
transactions
.IP "\(bu" 4
singletons
.PP
Any other value will return false.
.SH "ACCESSORS"
.IX Header "ACCESSORS"
The following are readonly attributes.
.IP "\(bu" 4
storage
.IP "\(bu" 4
sector_type
.IP "\(bu" 4
iterator_class