From: rkinyon Date: Mon, 15 Jan 2007 05:29:46 +0000 (+0000) Subject: POD updates, including code coverage X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=fa944deb938453ad7ee178b2d432fb49db6d4909;p=dbsrgits%2FDBM-Deep.git POD updates, including code coverage --- diff --git a/lib/DBM/Deep.pm b/lib/DBM/Deep.pm index e57afb4..03dd371 100644 --- a/lib/DBM/Deep.pm +++ b/lib/DBM/Deep.pm @@ -572,7 +572,7 @@ __END__ =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 @@ -591,6 +591,13 @@ DBM::Deep - A pure perl multi-level hash/array DBM 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}; @@ -610,6 +617,11 @@ Windows. =head1 VERSION DIFFERENCES +B: 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 backwards compatible with any +other release of DBM::Deep. + B: 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 backwards compatible @@ -747,14 +759,6 @@ multiple processes accessing the same DB file (also consider enable I). Pass any true value to enable. This is an optional parameter, and defaults to 0 (disabled). -=item * autobless - -If I 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 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 below. @@ -1052,7 +1056,7 @@ NFS> below for more. =head2 EXPLICIT LOCKING You can explicitly lock a database, so it remains locked for multiple -transactions. This is done by calling the C method, and passing an +actions. This is done by calling the C 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. @@ -1314,7 +1318,7 @@ B Changing these values will B work for existing database files. 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 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 @@ -1386,6 +1390,10 @@ every time you access this file. Otherwise, the default (MD5) will be used. =head1 CIRCULAR REFERENCES +B: 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 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. @@ -1436,29 +1444,6 @@ by the InnoDB MySQL table type. 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. -=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 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 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 @@ -1545,7 +1530,7 @@ modifications to either $db or $copy will be visible to both. Beware of using C, C or C 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 @@ -1562,14 +1547,13 @@ B report on this distribution's test suite. ---------------------------- ------ ------ ------ ------ ------ ------ ------ 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 @@ -1578,7 +1562,7 @@ irc.perl.org The source code repository is at L -=head1 MAINTAINERS +=head1 MAINTAINER(S) Rob Kinyon, L @@ -1586,6 +1570,8 @@ Originally written by Joseph Huckaby, L 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), @@ -1593,7 +1579,7 @@ Digest::SHA256(3), Crypt::Blowfish(3), Compress::Zlib(3) =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. diff --git a/lib/DBM/Deep/Engine.pm b/lib/DBM/Deep/Engine.pm index 722e2e7..d315aab 100644 --- a/lib/DBM/Deep/Engine.pm +++ b/lib/DBM/Deep/Engine.pm @@ -78,8 +78,6 @@ sub new { $self->{$param} = $args->{$param}; } - $self->{byte_pack} = $StP{ $self->byte_size }; - ## # Number of buckets per blist before another level of indexing is # done. Increase this value for slightly greater speed, but larger database