=head0 Adding transactions to DBM::Deep
+For the past 9 months, I've been working on adding transactions to
+L<DBM::Deep|DBM::Deep>. During that time, I looked far and wide for an
+accessible description of how a programmer should go about implementing
+transactions. The only things I found were either extremely pedantic academic
+papers or code. The former weren't very easy to read and the latter were less
+soN<Have I<you> ever tried to read the source for BDB or InnoDB? Reading
+perl's source is easier.>. This is the article I wished I'd been able to read
+nine months ago.
+
=head1 What is DBM::Deep?
L<DBM::Deep|DBM::Deep> is a module written completely in Perl that provides a way of
L<DBM::Deep|DBM::Deep> allows for the size a given datastructure to be limited by disk
instead (up to the given perl's largefile support).
-=item * IPC
+=item * Database
-While not a common use, this allows for inter-process communication without
-worrying about the specifics of how a given OS handles IPC.
+Once you have persistent datastructures, you start wanting to have multiple
+processes be able to use that data. (More on this later.)
=back
=head1 How does DBM::Deep work?
L<DBM::Deep|DBM::Deep> works by tying a variable to a file on disk. Every
-read and write go to the file and modify the file immediately. To
+read and write go directly to the file and modify the file immediately. To
represent Perl's hashes and arrays, a record-based file format is used. There
is a file header storing file-wide values, such as the size of the internal
file pointers. Afterwards, there are the data records.
The most important feature of L<DBM::Deep|DBM::Deep> is that it can be
completely transparent. Other than the line tying the variable to the file, no
other part of your program needs to know that the variable being used isn't a
-"normal" Perl variable.
+"normal" Perl variable. So, the following works just fine:
+
+ # As far as the rest of the program is concerned, the following two lines
+ # are identical - they produce a variable $foo that can be used as a hashref.
+ # my $foo = {};
+ my $foo = DBM::Deep->new( 'mydb.db' );
+
+ $foo->{bar} = 'baz';
+ $foo->{complex} = [
+ { a => 'b' }, 0, '123', undef, [ 1 .. 5 ],
+ ];
+
+ # And so on and so forth.
=head2 DBM::Deep's file structure
=back
-=head1 What are transactions?
+=head1 Why add transactions to DBM::Deep?
+
+For the most part, L<DBM::Deep|DBM::Deep> functions perfectly well without
+transactions. Most uses that I've seen tend to be either single-process
+read/write persistence or a multi-process readonly cache for an expensive, but
+static, lookup. With transactions, L<DBM::Deep|DBM::Deep> can now be used
+safely for multi-process read/write persistence in situations that don't
+need (or cannot use) a full RDBMS.
+
+=head2 What are transactions?
Originally from the database world, a transaction is a way of isolating the
effects of a given set of actions, then applying them all at once. It's a way
=back
-=head1 Why add them to DBM::Deep?
+=head2 Why add them to DBM::Deep?
The ability to have actions occur in either I<atomically> (as in the previous
example) or I<isolation> from the rest of the users of the data is a powerful
Sub-transactions can also work better with libraries that may want to use
transactions themselves.
+=head2 Durability
+
+As mentioned in L</What are transactions?>, the 'D' in ACID stands for
+I<Durable>. L<DBM::Deep|DBM::Deep> does not satisfy that criterion because
+durability almost always requires another file (or files) for a commit log. I
+deemed this unacceptable for this release because one of the
+L<DBM::Deep|DBM::Deep>'s features is the single datafile. However, Berkley DB
+provides durability with only a single file. Cribbing from them may be viable
+in the future.
+
=cut
projects / dbsrgits/DBM-Deep.git / commitdiff