DBM::Deep::Internals
+=head1 OUT OF DATE
+
+This document is out-of-date. It describes an intermediate file format used
+during the development from 0.983 to 1.0000. It will be rewritten soon.
+
=head1 DESCRIPTION
-This is a document describing the internal workings of L<DBM::Deep/>. It is
+This is a document describing the internal workings of L<DBM::Deep>. It is
not necessary to read this document if you only intend to be a user. This
document is intended for people who either want a deeper understanding of
-specifics of how L<DBM::Deep/> works or who wish to help program
-L<DBM::Deep/>.
+specifics of how L<DBM::Deep> works or who wish to help program
+L<DBM::Deep>.
=head1 CLASS LAYOUT
-L<DBM::Deep/> is broken up into five classes in three inheritance hierarchies.
+L<DBM::Deep> is broken up into five classes in three inheritance hierarchies.
=over 4
=item *
-L<DBM::Deep/> is the parent of L<DBM::Deep::Array/> and L<DBM::Deep::Hash/>.
+L<DBM::Deep> is the parent of L<DBM::Deep::Array> and L<DBM::Deep::Hash>.
These classes form the immediate interface to the outside world. They are the
classes that provide the TIE mechanisms as well as the OO methods.
=item *
-L<DBM::Deep::Engine/> is the layer that deals with the mechanics of reading
+L<DBM::Deep::Engine> is the layer that deals with the mechanics of reading
and writing to the file. This is where the logic of the file layout is
handled.
=item *
-L<DBM::Deep::File/> is the layer that deals with the physical file. As a
+L<DBM::Deep::File> is the layer that deals with the physical file. As a
singleton that every other object has a reference to, it also provides a place
to handle datastructure-wide items, such as transactions.
=item * Version
-This is four bytes containing the header version. This lets the header change over time.
+This is four bytes containing the file version. This lets the file format change over time.
+
+=item * Constants
+
+These are the file-wide constants that determine how the file is laid out.
+They can only be set upon file creation.
=item * Transaction information
The current running transactions are stored here, as is the next transaction
ID.
-=item * Constants
+=item * Freespace information
-These are the file-wide constants that determine how the file is laid out.
-They can only be set upon file creation.
+Pointers into the next free sectors of the various sector sizes (Index,
+Bucketlist, and Data) are stored here.
=back
=head1 PERFORMANCE
-L<DBM::Deep/> is written completely in Perl. It also is a multi-process DBM
+L<DBM::Deep> is written completely in Perl. It also is a multi-process DBM
that uses the datafile as a method of synchronizing between multiple
processes. This is unlike most RDBMSes like MySQL and Oracle. Furthermore,
-unlike all RDBMSes, L<DBM::Deep/> stores both the data and the structure of
+unlike all RDBMSes, L<DBM::Deep> stores both the data and the structure of
that data as it would appear in a Perl program.
=head2 CPU
DBM::Deep is I/O-bound, pure and simple. The faster your disk, the faster
DBM::Deep will be. Currently, when performing C<my $x = $db-E<gt>{foo}>, there
are a minimum of 4 seeks and 1332 + N bytes read (where N is the length of your
-data). (All values assume a medium filesize.) The actions take are:
+data). (All values assume a medium filesize.) The actions taken are:
=over 4
=head2 MEMORY USAGE
-One of the great things about L<DBM::Deep/> is that it uses very little memory.
+One of the great things about L<DBM::Deep> is that it uses very little memory.
Even with huge databases (1,000,000+ keys) you will not see much increased
-memory on your process. L<DBM::Deep/> relies solely on the filesystem for storing
+memory on your process. L<DBM::Deep> relies solely on the filesystem for storing
and fetching data. Here is output from I<top> before even opening a database
handle:
projects / dbsrgits/DBM-Deep.git / blobdiff