=head1 NAME
-DBM::Deep - A pure perl multi-level hash/array DBM
+DBM::Deep - A pure perl multi-level hash/array DBM that supports transactions
=head1 SYNOPSIS
42, 99,
];
+ $db->begin_work;
+
+ # Do stuff here
+
+ $db->rollback;
+ $db->commit;
+
tie my %db, 'DBM::Deep', 'foo.db';
$db{key} = 'value';
print $db{key};
=head1 VERSION DIFFERENCES
+B<NOTE>: 0.99_03 has significant file format differences from prior versions.
+THere will be a backwards-compatibility layer in 1.00, but that is slated for
+a later 0.99_x release. This version is B<NOT> backwards compatible with any
+other release of DBM::Deep.
+
B<NOTE>: 0.99_01 and above have significant file format differences from 0.983 and
before. There will be a backwards-compatibility layer in 1.00, but that is
slated for a later 0.99_x release. This version is B<NOT> backwards compatible
Pass any true value to enable. This is an optional parameter, and defaults to 0
(disabled).
-=item * autobless
-
-If I<autobless> mode is enabled, DBM::Deep will preserve the class something
-is blessed into, and restores it when fetched. This is an optional parameter, and defaults to 1 (enabled).
-
-B<Note:> If you use the OO-interface, you will not be able to call any methods
-of DBM::Deep on the blessed item. This is considered to be a feature.
-
=item * filter_*
See L</FILTERS> below.
=head2 EXPLICIT LOCKING
You can explicitly lock a database, so it remains locked for multiple
-transactions. This is done by calling the C<lock()> method, and passing an
+actions. This is done by calling the C<lock()> method, and passing an
optional lock mode argument (defaults to exclusive mode). This is particularly
useful for things like counters, where the current value needs to be fetched,
then incremented, then stored again.
Only change this for new files. Once the value has been set, it is stored in
the file's header and cannot be changed for the life of the file. These
parameters are per-file, meaning you can access 32-bit and 64-bit files, as
-you chose.
+you choose.
B<Note:> We have not personally tested files larger than 2 GB -- all my
systems have only a 32-bit Perl. However, I have received user reports that
=head1 CIRCULAR REFERENCES
+B<NOTE>: DBM::Deep 0.99_03 has turned off circular references pending
+evaluation of some edge cases. I hope to be able to re-enable circular
+references in a future version prior to 1.00.
+
DBM::Deep has B<experimental> support for circular references. Meaning you
can have a nested hash key or array element that points to a parent object.
This relationship is stored in the DB file, and is preserved between sessions.
This section describes all the known issues with DBM::Deep. It you have found
something that is not listed here, please send e-mail to L<jhuckaby@cpan.org>.
-=head2 UNUSED SPACE RECOVERY
-
-One major caveat with DBM::Deep is that space occupied by existing keys and
-values is not recovered when they are deleted. Meaning if you keep deleting
-and adding new keys, your file will continuously grow. I am working on this,
-but in the meantime you can call the built-in C<optimize()> method from time to
-time (perhaps in a crontab or something) to recover all your unused space.
-
- $db->optimize(); # returns true on success
-
-This rebuilds the ENTIRE database into a new file, then moves it on top of
-the original. The new file will have no unused space, thus it will take up as
-little disk space as possible. Please note that this operation can take
-a long time for large files, and you need enough disk space to temporarily hold
-2 copies of your DB file. The temporary file is created in the same directory
-as the original, named with a ".tmp" extension, and is deleted when the
-operation completes. Oh, and if locking is enabled, the DB is automatically
-locked for the entire duration of the copy.
-
-B<WARNING:> Only call optimize() on the top-level node of the database, and
-make sure there are no child references lying around. DBM::Deep keeps a reference
-counter, and if it is greater than 1, optimize() will abort and return undef.
-
=head2 REFERENCES
(The reasons given assume a high level of Perl understanding, specifically of
Beware of using C<shift()>, C<unshift()> or C<splice()> with large arrays.
These functions cause every element in the array to move, which can be murder
on DBM::Deep, as every element has to be fetched from disk, then stored again in
-a different location. This will be addressed in the forthcoming version 1.00.
+a different location. This will be addressed in a future version.
=head2 WRITEONLY FILES
---------------------------- ------ ------ ------ ------ ------ ------ ------
File stmt bran cond sub pod time total
---------------------------- ------ ------ ------ ------ ------ ------ ------
- blib/lib/DBM/Deep.pm 96.2 89.0 75.0 95.8 89.5 36.0 92.9
- blib/lib/DBM/Deep/Array.pm 96.1 88.3 100.0 96.4 100.0 15.9 94.7
- blib/lib/DBM/Deep/Engine.pm 96.6 86.6 89.5 100.0 0.0 20.0 91.0
- blib/lib/DBM/Deep/File.pm 99.4 88.3 55.6 100.0 0.0 19.6 89.5
- blib/lib/DBM/Deep/Hash.pm 98.5 83.3 100.0 100.0 100.0 8.5 96.3
- Total 96.9 87.4 81.2 98.0 38.5 100.0 92.1
+ blib/lib/DBM/Deep.pm 87.7 81.0 81.0 93.9 89.5 4.2 87.2
+ blib/lib/DBM/Deep/Array.pm 95.9 88.3 100.0 96.4 100.0 4.9 94.5
+ blib/lib/DBM/Deep/Engine.pm 94.3 83.9 78.0 94.6 0.0 60.0 87.9
+ blib/lib/DBM/Deep/File.pm 88.5 76.2 45.5 93.8 0.0 28.9 78.8
+ blib/lib/DBM/Deep/Hash.pm 98.5 83.3 100.0 100.0 100.0 2.1 96.3
+ Total 93.0 83.4 77.5 95.0 31.6 100.0 88.3
---------------------------- ------ ------ ------ ------ ------ ------ ------
-
=head1 MORE INFORMATION
Check out the DBM::Deep Google Group at L<http://groups.google.com/group/DBM-Deep>
The source code repository is at L<http://svn.perl.org/modules/DBM-Deep>
-=head1 MAINTAINERS
+=head1 MAINTAINER(S)
Rob Kinyon, L<rkinyon@cpan.org>
Special thanks to Adam Sah and Rich Gaushell! You know why :-)
+Additional thanks go out to Stonehenge who have sponsored the 1.00 release.
+
=head1 SEE ALSO
perltie(1), Tie::Hash(3), Digest::MD5(3), Fcntl(3), flock(2), lockf(3), nfs(5),
=head1 LICENSE
-Copyright (c) 2002-2006 Joseph Huckaby. All Rights Reserved.
+Copyright (c) 2007 Rob Kinyon. All Rights Reserved.
This is free software, you may use it and distribute it under the
same terms as Perl itself.
projects / dbsrgits/DBM-Deep.git / commitdiff