fixed typo in POD
[dbsrgits/DBM-Deep.git] / lib / DBM / Deep.pm
CommitLineData
ffed8b01 1package DBM::Deep;
2
3##
4# DBM::Deep
5#
6# Description:
d0b74c17 7# Multi-level database module for storing hash trees, arrays and simple
8# key/value pairs into FTP-able, cross-platform binary database files.
ffed8b01 9#
d0b74c17 10# Type `perldoc DBM::Deep` for complete documentation.
ffed8b01 11#
12# Usage Examples:
d0b74c17 13# my %db;
14# tie %db, 'DBM::Deep', 'my_database.db'; # standard tie() method
ffed8b01 15#
d0b74c17 16# my $db = new DBM::Deep( 'my_database.db' ); # preferred OO method
17#
18# $db->{my_scalar} = 'hello world';
19# $db->{my_hash} = { larry => 'genius', hashes => 'fast' };
20# $db->{my_array} = [ 1, 2, 3, time() ];
21# $db->{my_complex} = [ 'hello', { perl => 'rules' }, 42, 99 ];
22# push @{$db->{my_array}}, 'another value';
23# my @key_list = keys %{$db->{my_hash}};
24# print "This module " . $db->{my_complex}->[1]->{perl} . "!\n";
ffed8b01 25#
26# Copyright:
d0b74c17 27# (c) 2002-2006 Joseph Huckaby. All Rights Reserved.
28# This program is free software; you can redistribute it and/or
29# modify it under the same terms as Perl itself.
ffed8b01 30##
31
32use strict;
8b957036 33
596e9574 34use Fcntl qw( :DEFAULT :flock :seek );
ffed8b01 35use Digest::MD5 ();
36use Scalar::Util ();
ffed8b01 37
95967a5e 38use DBM::Deep::Engine;
39
596e9574 40use vars qw( $VERSION );
3a7a0dce 41$VERSION = q(0.99_01);
ffed8b01 42
ffed8b01 43##
44# Setup constants for users to pass to new()
45##
e06824f8 46sub TYPE_HASH () { DBM::Deep::Engine->SIG_HASH }
47sub TYPE_ARRAY () { DBM::Deep::Engine->SIG_ARRAY }
ffed8b01 48
0ca7ea98 49sub _get_args {
50 my $proto = shift;
51
52 my $args;
53 if (scalar(@_) > 1) {
54 if ( @_ % 2 ) {
55 $proto->_throw_error( "Odd number of parameters to " . (caller(1))[2] );
56 }
57 $args = {@_};
58 }
d0b74c17 59 elsif ( ref $_[0] ) {
4d35d856 60 unless ( eval { local $SIG{'__DIE__'}; %{$_[0]} || 1 } ) {
0ca7ea98 61 $proto->_throw_error( "Not a hashref in args to " . (caller(1))[2] );
62 }
63 $args = $_[0];
64 }
d0b74c17 65 else {
0ca7ea98 66 $args = { file => shift };
67 }
68
69 return $args;
70}
71
ffed8b01 72sub new {
d0b74c17 73 ##
74 # Class constructor method for Perl OO interface.
75 # Calls tie() and returns blessed reference to tied hash or array,
76 # providing a hybrid OO/tie interface.
77 ##
78 my $class = shift;
79 my $args = $class->_get_args( @_ );
80
81 ##
82 # Check if we want a tied hash or array.
83 ##
84 my $self;
85 if (defined($args->{type}) && $args->{type} eq TYPE_ARRAY) {
6fe26b29 86 $class = 'DBM::Deep::Array';
87 require DBM::Deep::Array;
d0b74c17 88 tie @$self, $class, %$args;
89 }
90 else {
6fe26b29 91 $class = 'DBM::Deep::Hash';
92 require DBM::Deep::Hash;
d0b74c17 93 tie %$self, $class, %$args;
94 }
ffed8b01 95
d0b74c17 96 return bless $self, $class;
ffed8b01 97}
98
0795f290 99sub _init {
100 ##
101 # Setup $self and bless into this class.
102 ##
103 my $class = shift;
994ccd8e 104 my ($args) = @_;
0795f290 105
106 # These are the defaults to be optionally overridden below
107 my $self = bless {
95967a5e 108 type => TYPE_HASH,
612969fb 109 engine => DBM::Deep::Engine->new,
e06824f8 110 base_offset => undef,
0795f290 111 }, $class;
8db25060 112
0795f290 113 foreach my $param ( keys %$self ) {
114 next unless exists $args->{$param};
115 $self->{$param} = delete $args->{$param}
ffed8b01 116 }
d0b74c17 117
37c5bcf0 118 # locking implicitly enables autoflush
119 if ($args->{locking}) { $args->{autoflush} = 1; }
d0b74c17 120
0795f290 121 $self->{root} = exists $args->{root}
122 ? $args->{root}
123 : DBM::Deep::_::Root->new( $args );
124
70b55428 125 $self->{engine}->setup_fh( $self );
0795f290 126
127 return $self;
ffed8b01 128}
129
ffed8b01 130sub TIEHASH {
6fe26b29 131 shift;
132 require DBM::Deep::Hash;
133 return DBM::Deep::Hash->TIEHASH( @_ );
ffed8b01 134}
135
136sub TIEARRAY {
6fe26b29 137 shift;
138 require DBM::Deep::Array;
139 return DBM::Deep::Array->TIEARRAY( @_ );
ffed8b01 140}
141
cc4bef86 142#XXX Unneeded now ...
143#sub DESTROY {
144#}
ffed8b01 145
ffed8b01 146sub lock {
d0b74c17 147 ##
148 # If db locking is set, flock() the db file. If called multiple
149 # times before unlock(), then the same number of unlocks() must
150 # be called before the lock is released.
151 ##
994ccd8e 152 my $self = shift->_get_self;
153 my ($type) = @_;
ffed8b01 154 $type = LOCK_EX unless defined $type;
d0b74c17 155
156 if (!defined($self->_fh)) { return; }
157
158 if ($self->_root->{locking}) {
159 if (!$self->_root->{locked}) {
160 flock($self->_fh, $type);
161
162 # refresh end counter in case file has changed size
118ba343 163 my @stats = stat($self->_fh);
d0b74c17 164 $self->_root->{end} = $stats[7];
165
166 # double-check file inode, in case another process
167 # has optimize()d our file while we were waiting.
168 if ($stats[1] != $self->_root->{inode}) {
3d1b8be9 169 $self->{engine}->close_fh( $self );
70b55428 170 $self->{engine}->setup_fh( $self );
d0b74c17 171 flock($self->_fh, $type); # re-lock
70b55428 172
173 # This may not be necessary after re-opening
d0b74c17 174 $self->_root->{end} = (stat($self->_fh))[7]; # re-end
175 }
176 }
177 $self->_root->{locked}++;
b4522594 178
179 return 1;
d0b74c17 180 }
b4522594 181
182 return;
ffed8b01 183}
184
185sub unlock {
d0b74c17 186 ##
187 # If db locking is set, unlock the db file. See note in lock()
188 # regarding calling lock() multiple times.
189 ##
994ccd8e 190 my $self = shift->_get_self;
7f441181 191
d0b74c17 192 if (!defined($self->_fh)) { return; }
193
194 if ($self->_root->{locking} && $self->_root->{locked} > 0) {
195 $self->_root->{locked}--;
196 if (!$self->_root->{locked}) { flock($self->_fh, LOCK_UN); }
b4522594 197
198 return 1;
d0b74c17 199 }
b4522594 200
201 return;
ffed8b01 202}
203
906c8e01 204sub _copy_value {
205 my $self = shift->_get_self;
206 my ($spot, $value) = @_;
207
208 if ( !ref $value ) {
209 ${$spot} = $value;
210 }
211 elsif ( eval { local $SIG{__DIE__}; $value->isa( 'DBM::Deep' ) } ) {
212 my $type = $value->_type;
213 ${$spot} = $type eq TYPE_HASH ? {} : [];
214 $value->_copy_node( ${$spot} );
215 }
216 else {
217 my $r = Scalar::Util::reftype( $value );
218 my $c = Scalar::Util::blessed( $value );
219 if ( $r eq 'ARRAY' ) {
220 ${$spot} = [ @{$value} ];
221 }
222 else {
223 ${$spot} = { %{$value} };
224 }
95bbd935 225 ${$spot} = bless ${$spot}, $c
906c8e01 226 if defined $c;
227 }
228
229 return 1;
230}
231
261d1296 232sub _copy_node {
d0b74c17 233 ##
234 # Copy single level of keys or elements to new DB handle.
235 # Recurse for nested structures
236 ##
906c8e01 237 my $self = shift->_get_self;
d0b74c17 238 my ($db_temp) = @_;
b8b48a59 239
d0b74c17 240 if ($self->_type eq TYPE_HASH) {
241 my $key = $self->first_key();
242 while ($key) {
243 my $value = $self->get($key);
906c8e01 244 $self->_copy_value( \$db_temp->{$key}, $value );
d0b74c17 245 $key = $self->next_key($key);
246 }
247 }
248 else {
249 my $length = $self->length();
250 for (my $index = 0; $index < $length; $index++) {
251 my $value = $self->get($index);
906c8e01 252 $self->_copy_value( \$db_temp->[$index], $value );
d0b74c17 253 }
254 }
906c8e01 255
256 return 1;
ffed8b01 257}
258
259sub export {
d0b74c17 260 ##
261 # Recursively export into standard Perl hashes and arrays.
262 ##
994ccd8e 263 my $self = shift->_get_self;
d0b74c17 264
265 my $temp;
266 if ($self->_type eq TYPE_HASH) { $temp = {}; }
267 elsif ($self->_type eq TYPE_ARRAY) { $temp = []; }
268
269 $self->lock();
270 $self->_copy_node( $temp );
271 $self->unlock();
272
273 return $temp;
ffed8b01 274}
275
276sub import {
d0b74c17 277 ##
278 # Recursively import Perl hash/array structure
279 ##
d0b74c17 280 if (!ref($_[0])) { return; } # Perl calls import() on use -- ignore
281
994ccd8e 282 my $self = shift->_get_self;
283 my ($struct) = @_;
d0b74c17 284
c9cec40e 285 # struct is not a reference, so just import based on our type
d0b74c17 286 if (!ref($struct)) {
d0b74c17 287 if ($self->_type eq TYPE_HASH) { $struct = {@_}; }
288 elsif ($self->_type eq TYPE_ARRAY) { $struct = [@_]; }
289 }
290
ffed8b01 291 my $r = Scalar::Util::reftype($struct) || '';
d0b74c17 292 if ($r eq "HASH" && $self->_type eq TYPE_HASH) {
293 foreach my $key (keys %$struct) { $self->put($key, $struct->{$key}); }
294 }
295 elsif ($r eq "ARRAY" && $self->_type eq TYPE_ARRAY) {
296 $self->push( @$struct );
297 }
298 else {
1400a48e 299 $self->_throw_error("Cannot import: type mismatch");
d0b74c17 300 }
301
302 return 1;
ffed8b01 303}
304
305sub optimize {
d0b74c17 306 ##
307 # Rebuild entire database into new file, then move
308 # it back on top of original.
309 ##
994ccd8e 310 my $self = shift->_get_self;
cc4bef86 311
312#XXX Need to create a new test for this
d0b74c17 313# if ($self->_root->{links} > 1) {
1400a48e 314# $self->_throw_error("Cannot optimize: reference count is greater than 1");
d0b74c17 315# }
316
317 my $db_temp = DBM::Deep->new(
318 file => $self->_root->{file} . '.tmp',
319 type => $self->_type
320 );
d0b74c17 321
322 $self->lock();
323 $self->_copy_node( $db_temp );
324 undef $db_temp;
325
326 ##
327 # Attempt to copy user, group and permissions over to new file
328 ##
329 my @stats = stat($self->_fh);
330 my $perms = $stats[2] & 07777;
331 my $uid = $stats[4];
332 my $gid = $stats[5];
333 chown( $uid, $gid, $self->_root->{file} . '.tmp' );
334 chmod( $perms, $self->_root->{file} . '.tmp' );
335
ffed8b01 336 # q.v. perlport for more information on this variable
90f93b43 337 if ( $^O eq 'MSWin32' || $^O eq 'cygwin' ) {
d0b74c17 338 ##
339 # Potential race condition when optmizing on Win32 with locking.
340 # The Windows filesystem requires that the filehandle be closed
341 # before it is overwritten with rename(). This could be redone
342 # with a soft copy.
343 ##
344 $self->unlock();
345 $self->{engine}->close_fh( $self );
346 }
347
348 if (!rename $self->_root->{file} . '.tmp', $self->_root->{file}) {
349 unlink $self->_root->{file} . '.tmp';
350 $self->unlock();
1400a48e 351 $self->_throw_error("Optimize failed: Cannot copy temp file over original: $!");
d0b74c17 352 }
353
354 $self->unlock();
355 $self->{engine}->close_fh( $self );
70b55428 356 $self->{engine}->setup_fh( $self );
357
d0b74c17 358 return 1;
ffed8b01 359}
360
361sub clone {
d0b74c17 362 ##
363 # Make copy of object and return
364 ##
994ccd8e 365 my $self = shift->_get_self;
d0b74c17 366
367 return DBM::Deep->new(
368 type => $self->_type,
369 base_offset => $self->_base_offset,
370 root => $self->_root
371 );
ffed8b01 372}
373
374{
375 my %is_legal_filter = map {
376 $_ => ~~1,
377 } qw(
378 store_key store_value
379 fetch_key fetch_value
380 );
381
382 sub set_filter {
383 ##
384 # Setup filter function for storing or fetching the key or value
385 ##
994ccd8e 386 my $self = shift->_get_self;
387 my $type = lc shift;
388 my $func = shift;
d0b74c17 389
ffed8b01 390 if ( $is_legal_filter{$type} ) {
4d35d856 391 $self->_root->{"filter_$type"} = $func;
ffed8b01 392 return 1;
393 }
394
395 return;
396 }
397}
398
399##
400# Accessor methods
401##
402
4d35d856 403sub _root {
d0b74c17 404 ##
405 # Get access to the root structure
406 ##
2ac02042 407 my $self = $_[0]->_get_self;
d0b74c17 408 return $self->{root};
ffed8b01 409}
410
4d35d856 411sub _type {
d0b74c17 412 ##
413 # Get type of current node (TYPE_HASH or TYPE_ARRAY)
414 ##
2ac02042 415 my $self = $_[0]->_get_self;
d0b74c17 416 return $self->{type};
ffed8b01 417}
418
4d35d856 419sub _base_offset {
d0b74c17 420 ##
421 # Get base_offset of current node (TYPE_HASH or TYPE_ARRAY)
422 ##
2ac02042 423 my $self = $_[0]->_get_self;
d0b74c17 424 return $self->{base_offset};
ffed8b01 425}
426
994ccd8e 427sub _fh {
428 ##
429 # Get access to the raw fh
430 ##
431 my $self = $_[0]->_get_self;
432 return $self->_root->{fh};
433}
434
ffed8b01 435##
436# Utility methods
437##
438
261d1296 439sub _throw_error {
95967a5e 440 die "DBM::Deep: $_[1]\n";
ffed8b01 441}
442
acd4faf2 443sub _is_writable {
444 my $fh = shift;
445 (O_WRONLY | O_RDWR) & fcntl( $fh, F_GETFL, my $slush = 0);
446}
447
9be51a89 448#sub _is_readable {
449# my $fh = shift;
450# (O_RDONLY | O_RDWR) & fcntl( $fh, F_GETFL, my $slush = 0);
451#}
acd4faf2 452
ffed8b01 453sub STORE {
d0b74c17 454 ##
455 # Store single hash key/value or array element in database.
456 ##
457 my $self = shift->_get_self;
458 my ($key, $value) = @_;
81d3d316 459
acd4faf2 460 unless ( _is_writable( $self->_fh ) ) {
461 $self->_throw_error( 'Cannot write to a readonly filehandle' );
462 }
d0b74c17 463
464 ##
465 # Request exclusive lock for writing
466 ##
467 $self->lock( LOCK_EX );
468
469 my $md5 = $self->{engine}{digest}->($key);
470
471 my $tag = $self->{engine}->find_bucket_list( $self, $md5, { create => 1 } );
472
473 # User may be storing a hash, in which case we do not want it run
474 # through the filtering system
475 if ( !ref($value) && $self->_root->{filter_store_value} ) {
476 $value = $self->_root->{filter_store_value}->( $value );
477 }
478
479 ##
480 # Add key/value to bucket list
481 ##
482 my $result = $self->{engine}->add_bucket( $self, $tag, $md5, $key, $value );
483
484 $self->unlock();
485
486 return $result;
ffed8b01 487}
488
489sub FETCH {
d0b74c17 490 ##
491 # Fetch single value or element given plain key or array index
492 ##
cb79ec85 493 my $self = shift->_get_self;
e06824f8 494 my ($key) = @_;
ffed8b01 495
d0b74c17 496 my $md5 = $self->{engine}{digest}->($key);
497
498 ##
499 # Request shared lock for reading
500 ##
501 $self->lock( LOCK_SH );
502
503 my $tag = $self->{engine}->find_bucket_list( $self, $md5 );
504 if (!$tag) {
505 $self->unlock();
506 return;
507 }
508
509 ##
510 # Get value from bucket list
511 ##
512 my $result = $self->{engine}->get_bucket_value( $self, $tag, $md5 );
513
514 $self->unlock();
515
a86430bd 516 # Filters only apply to scalar values, so the ref check is making
517 # sure the fetched bucket is a scalar, not a child hash or array.
d0b74c17 518 return ($result && !ref($result) && $self->_root->{filter_fetch_value})
4d35d856 519 ? $self->_root->{filter_fetch_value}->($result)
cb79ec85 520 : $result;
ffed8b01 521}
522
523sub DELETE {
d0b74c17 524 ##
525 # Delete single key/value pair or element given plain key or array index
526 ##
2ac02042 527 my $self = $_[0]->_get_self;
d0b74c17 528 my $key = $_[1];
529
a86430bd 530 unless ( _is_writable( $self->_fh ) ) {
531 $self->_throw_error( 'Cannot write to a readonly filehandle' );
532 }
d0b74c17 533
534 ##
535 # Request exclusive lock for writing
536 ##
537 $self->lock( LOCK_EX );
538
a86430bd 539 my $md5 = $self->{engine}{digest}->($key);
540
d0b74c17 541 my $tag = $self->{engine}->find_bucket_list( $self, $md5 );
542 if (!$tag) {
543 $self->unlock();
544 return;
545 }
546
547 ##
548 # Delete bucket
549 ##
9020ee8c 550 my $value = $self->{engine}->get_bucket_value($self, $tag, $md5 );
a86430bd 551
552 if (defined $value && !ref($value) && $self->_root->{filter_fetch_value}) {
4d35d856 553 $value = $self->_root->{filter_fetch_value}->($value);
3b6a5056 554 }
555
d0b74c17 556 my $result = $self->{engine}->delete_bucket( $self, $tag, $md5 );
557
558 ##
559 # If this object is an array and the key deleted was on the end of the stack,
560 # decrement the length variable.
561 ##
562
563 $self->unlock();
564
565 return $value;
ffed8b01 566}
567
568sub EXISTS {
d0b74c17 569 ##
570 # Check if a single key or element exists given plain key or array index
571 ##
2ac02042 572 my $self = $_[0]->_get_self;
d0b74c17 573 my $key = $_[1];
574
575 my $md5 = $self->{engine}{digest}->($key);
576
577 ##
578 # Request shared lock for reading
579 ##
580 $self->lock( LOCK_SH );
581
582 my $tag = $self->{engine}->find_bucket_list( $self, $md5 );
583 if (!$tag) {
584 $self->unlock();
585
586 ##
587 # For some reason, the built-in exists() function returns '' for false
588 ##
589 return '';
590 }
591
592 ##
593 # Check if bucket exists and return 1 or ''
594 ##
595 my $result = $self->{engine}->bucket_exists( $self, $tag, $md5 ) || '';
596
597 $self->unlock();
598
599 return $result;
ffed8b01 600}
601
602sub CLEAR {
d0b74c17 603 ##
604 # Clear all keys from hash, or all elements from array.
605 ##
2ac02042 606 my $self = $_[0]->_get_self;
ffed8b01 607
a86430bd 608 unless ( _is_writable( $self->_fh ) ) {
609 $self->_throw_error( 'Cannot write to a readonly filehandle' );
610 }
611
d0b74c17 612 ##
613 # Request exclusive lock for writing
614 ##
615 $self->lock( LOCK_EX );
616
4d35d856 617 my $fh = $self->_fh;
629df3a3 618
d0b74c17 619 seek($fh, $self->_base_offset + $self->_root->{file_offset}, SEEK_SET);
620 if (eof $fh) {
621 $self->unlock();
622 return;
623 }
624
2603d86e 625 $self->{engine}->create_tag(
626 $self, $self->_base_offset, $self->_type,
f37c15ab 627 chr(0)x$self->{engine}{index_size},
2603d86e 628 );
d0b74c17 629
630 $self->unlock();
631
632 return 1;
ffed8b01 633}
634
ffed8b01 635##
636# Public method aliases
637##
7f441181 638sub put { (shift)->STORE( @_ ) }
639sub store { (shift)->STORE( @_ ) }
640sub get { (shift)->FETCH( @_ ) }
641sub fetch { (shift)->FETCH( @_ ) }
baa27ab6 642sub delete { (shift)->DELETE( @_ ) }
643sub exists { (shift)->EXISTS( @_ ) }
644sub clear { (shift)->CLEAR( @_ ) }
ffed8b01 645
cc4bef86 646package DBM::Deep::_::Root;
647
648sub new {
649 my $class = shift;
650 my ($args) = @_;
651
652 my $self = bless {
a86430bd 653 autobless => undef,
654 autoflush => undef,
c9ec091a 655 end => 0,
f5be9b03 656 fh => undef,
a86430bd 657 file => undef,
f5be9b03 658 file_offset => 0,
f5be9b03 659 locking => undef,
660 locked => 0,
661 filter_store_key => undef,
cc4bef86 662 filter_store_value => undef,
f5be9b03 663 filter_fetch_key => undef,
cc4bef86 664 filter_fetch_value => undef,
cc4bef86 665 %$args,
666 }, $class;
667
714618f0 668 if ( $self->{fh} && !$self->{file_offset} ) {
669 $self->{file_offset} = tell( $self->{fh} );
670 }
671
cc4bef86 672 return $self;
673}
674
675sub DESTROY {
676 my $self = shift;
677 return unless $self;
678
679 close $self->{fh} if $self->{fh};
680
681 return;
682}
683
ffed8b01 6841;
ffed8b01 685__END__
686
687=head1 NAME
688
689DBM::Deep - A pure perl multi-level hash/array DBM
690
691=head1 SYNOPSIS
692
693 use DBM::Deep;
694 my $db = DBM::Deep->new( "foo.db" );
d0b74c17 695
ffed8b01 696 $db->{key} = 'value'; # tie() style
697 print $db->{key};
d0b74c17 698
cbaa107d 699 $db->put('key' => 'value'); # OO style
ffed8b01 700 print $db->get('key');
d0b74c17 701
ffed8b01 702 # true multi-level support
703 $db->{my_complex} = [
d0b74c17 704 'hello', { perl => 'rules' },
705 42, 99,
90f93b43 706 ];
ffed8b01 707
708=head1 DESCRIPTION
709
d0b74c17 710A unique flat-file database module, written in pure perl. True
711multi-level hash/array support (unlike MLDBM, which is faked), hybrid
712OO / tie() interface, cross-platform FTPable files, and quite fast. Can
713handle millions of keys and unlimited hash levels without significant
714slow-down. Written from the ground-up in pure perl -- this is NOT a
715wrapper around a C-based DBM. Out-of-the-box compatibility with Unix,
ffed8b01 716Mac OS X and Windows.
717
8db25060 718=head1 VERSION DIFFERENCES
719
720B<NOTE>: 0.99_01 and above have significant file format differences from 0.98 and
721before. While attempts have been made to be backwards compatible, no guarantees.
722
ffed8b01 723=head1 INSTALLATION
724
90f93b43 725Hopefully you are using Perl's excellent CPAN module, which will download
d0b74c17 726and install the module for you. If not, get the tarball, and run these
ffed8b01 727commands:
728
d0b74c17 729 tar zxf DBM-Deep-*
730 cd DBM-Deep-*
731 perl Makefile.PL
732 make
733 make test
734 make install
ffed8b01 735
736=head1 SETUP
737
d0b74c17 738Construction can be done OO-style (which is the recommended way), or using
ffed8b01 739Perl's tie() function. Both are examined here.
740
741=head2 OO CONSTRUCTION
742
743The recommended way to construct a DBM::Deep object is to use the new()
744method, which gets you a blessed, tied hash or array reference.
745
d0b74c17 746 my $db = DBM::Deep->new( "foo.db" );
ffed8b01 747
748This opens a new database handle, mapped to the file "foo.db". If this
d0b74c17 749file does not exist, it will automatically be created. DB files are
ffed8b01 750opened in "r+" (read/write) mode, and the type of object returned is a
751hash, unless otherwise specified (see L<OPTIONS> below).
752
ffed8b01 753You can pass a number of options to the constructor to specify things like
754locking, autoflush, etc. This is done by passing an inline hash:
755
d0b74c17 756 my $db = DBM::Deep->new(
757 file => "foo.db",
758 locking => 1,
759 autoflush => 1
760 );
ffed8b01 761
762Notice that the filename is now specified I<inside> the hash with
d0b74c17 763the "file" parameter, as opposed to being the sole argument to the
ffed8b01 764constructor. This is required if any options are specified.
765See L<OPTIONS> below for the complete list.
766
767
768
769You can also start with an array instead of a hash. For this, you must
770specify the C<type> parameter:
771
d0b74c17 772 my $db = DBM::Deep->new(
773 file => "foo.db",
774 type => DBM::Deep->TYPE_ARRAY
775 );
ffed8b01 776
777B<Note:> Specifing the C<type> parameter only takes effect when beginning
778a new DB file. If you create a DBM::Deep object with an existing file, the
90f93b43 779C<type> will be loaded from the file header, and an error will be thrown if
780the wrong type is passed in.
ffed8b01 781
782=head2 TIE CONSTRUCTION
783
90f93b43 784Alternately, you can create a DBM::Deep handle by using Perl's built-in
785tie() function. The object returned from tie() can be used to call methods,
786such as lock() and unlock(), but cannot be used to assign to the DBM::Deep
787file (as expected with most tie'd objects).
ffed8b01 788
d0b74c17 789 my %hash;
790 my $db = tie %hash, "DBM::Deep", "foo.db";
791
792 my @array;
793 my $db = tie @array, "DBM::Deep", "bar.db";
ffed8b01 794
795As with the OO constructor, you can replace the DB filename parameter with
796a hash containing one or more options (see L<OPTIONS> just below for the
797complete list).
798
d0b74c17 799 tie %hash, "DBM::Deep", {
800 file => "foo.db",
801 locking => 1,
802 autoflush => 1
803 };
ffed8b01 804
805=head2 OPTIONS
806
807There are a number of options that can be passed in when constructing your
808DBM::Deep objects. These apply to both the OO- and tie- based approaches.
809
810=over
811
812=item * file
813
814Filename of the DB file to link the handle to. You can pass a full absolute
d0b74c17 815filesystem path, partial path, or a plain filename if the file is in the
714618f0 816current working directory. This is a required parameter (though q.v. fh).
817
818=item * fh
819
820If you want, you can pass in the fh instead of the file. This is most useful for doing
821something like:
822
823 my $db = DBM::Deep->new( { fh => \*DATA } );
824
825You are responsible for making sure that the fh has been opened appropriately for your
826needs. If you open it read-only and attempt to write, an exception will be thrown. If you
827open it write-only or append-only, an exception will be thrown immediately as DBM::Deep
828needs to read from the fh.
829
830=item * file_offset
831
832This is the offset within the file that the DBM::Deep db starts. Most of the time, you will
833not need to set this. However, it's there if you want it.
834
835If you pass in fh and do not set this, it will be set appropriately.
ffed8b01 836
ffed8b01 837=item * type
838
839This parameter specifies what type of object to create, a hash or array. Use
840one of these two constants: C<DBM::Deep-E<gt>TYPE_HASH> or C<DBM::Deep-E<gt>TYPE_ARRAY>.
d0b74c17 841This only takes effect when beginning a new file. This is an optional
ffed8b01 842parameter, and defaults to C<DBM::Deep-E<gt>TYPE_HASH>.
843
844=item * locking
845
846Specifies whether locking is to be enabled. DBM::Deep uses Perl's Fnctl flock()
847function to lock the database in exclusive mode for writes, and shared mode for
d0b74c17 848reads. Pass any true value to enable. This affects the base DB handle I<and
849any child hashes or arrays> that use the same DB file. This is an optional
ffed8b01 850parameter, and defaults to 0 (disabled). See L<LOCKING> below for more.
851
852=item * autoflush
853
d0b74c17 854Specifies whether autoflush is to be enabled on the underlying filehandle.
855This obviously slows down write operations, but is required if you may have
856multiple processes accessing the same DB file (also consider enable I<locking>).
857Pass any true value to enable. This is an optional parameter, and defaults to 0
ffed8b01 858(disabled).
859
860=item * autobless
861
862If I<autobless> mode is enabled, DBM::Deep will preserve blessed hashes, and
863restore them when fetched. This is an B<experimental> feature, and does have
864side-effects. Basically, when hashes are re-blessed into their original
865classes, they are no longer blessed into the DBM::Deep class! So you won't be
866able to call any DBM::Deep methods on them. You have been warned.
867This is an optional parameter, and defaults to 0 (disabled).
868
869=item * filter_*
870
871See L<FILTERS> below.
872
ffed8b01 873=back
874
875=head1 TIE INTERFACE
876
877With DBM::Deep you can access your databases using Perl's standard hash/array
90f93b43 878syntax. Because all DBM::Deep objects are I<tied> to hashes or arrays, you can
879treat them as such. DBM::Deep will intercept all reads/writes and direct them
880to the right place -- the DB file. This has nothing to do with the
881L<TIE CONSTRUCTION> section above. This simply tells you how to use DBM::Deep
882using regular hashes and arrays, rather than calling functions like C<get()>
883and C<put()> (although those work too). It is entirely up to you how to want
884to access your databases.
ffed8b01 885
886=head2 HASHES
887
888You can treat any DBM::Deep object like a normal Perl hash reference. Add keys,
889or even nested hashes (or arrays) using standard Perl syntax:
890
d0b74c17 891 my $db = DBM::Deep->new( "foo.db" );
892
893 $db->{mykey} = "myvalue";
894 $db->{myhash} = {};
895 $db->{myhash}->{subkey} = "subvalue";
ffed8b01 896
d0b74c17 897 print $db->{myhash}->{subkey} . "\n";
ffed8b01 898
899You can even step through hash keys using the normal Perl C<keys()> function:
900
d0b74c17 901 foreach my $key (keys %$db) {
902 print "$key: " . $db->{$key} . "\n";
903 }
ffed8b01 904
905Remember that Perl's C<keys()> function extracts I<every> key from the hash and
d0b74c17 906pushes them onto an array, all before the loop even begins. If you have an
907extra large hash, this may exhaust Perl's memory. Instead, consider using
908Perl's C<each()> function, which pulls keys/values one at a time, using very
ffed8b01 909little memory:
910
d0b74c17 911 while (my ($key, $value) = each %$db) {
912 print "$key: $value\n";
913 }
ffed8b01 914
915Please note that when using C<each()>, you should always pass a direct
916hash reference, not a lookup. Meaning, you should B<never> do this:
917
d0b74c17 918 # NEVER DO THIS
919 while (my ($key, $value) = each %{$db->{foo}}) { # BAD
ffed8b01 920
921This causes an infinite loop, because for each iteration, Perl is calling
922FETCH() on the $db handle, resulting in a "new" hash for foo every time, so
d0b74c17 923it effectively keeps returning the first key over and over again. Instead,
ffed8b01 924assign a temporary variable to C<$db->{foo}>, then pass that to each().
925
926=head2 ARRAYS
927
928As with hashes, you can treat any DBM::Deep object like a normal Perl array
d0b74c17 929reference. This includes inserting, removing and manipulating elements,
ffed8b01 930and the C<push()>, C<pop()>, C<shift()>, C<unshift()> and C<splice()> functions.
d0b74c17 931The object must have first been created using type C<DBM::Deep-E<gt>TYPE_ARRAY>,
ffed8b01 932or simply be a nested array reference inside a hash. Example:
933
d0b74c17 934 my $db = DBM::Deep->new(
935 file => "foo-array.db",
936 type => DBM::Deep->TYPE_ARRAY
937 );
938
939 $db->[0] = "foo";
940 push @$db, "bar", "baz";
941 unshift @$db, "bah";
942
943 my $last_elem = pop @$db; # baz
944 my $first_elem = shift @$db; # bah
945 my $second_elem = $db->[1]; # bar
946
947 my $num_elements = scalar @$db;
ffed8b01 948
949=head1 OO INTERFACE
950
951In addition to the I<tie()> interface, you can also use a standard OO interface
952to manipulate all aspects of DBM::Deep databases. Each type of object (hash or
d0b74c17 953array) has its own methods, but both types share the following common methods:
ffed8b01 954C<put()>, C<get()>, C<exists()>, C<delete()> and C<clear()>.
955
956=over
957
4d35d856 958=item * new() / clone()
959
960These are the constructor and copy-functions.
961
90f93b43 962=item * put() / store()
ffed8b01 963
964Stores a new hash key/value pair, or sets an array element value. Takes two
965arguments, the hash key or array index, and the new value. The value can be
966a scalar, hash ref or array ref. Returns true on success, false on failure.
967
d0b74c17 968 $db->put("foo", "bar"); # for hashes
969 $db->put(1, "bar"); # for arrays
ffed8b01 970
90f93b43 971=item * get() / fetch()
ffed8b01 972
973Fetches the value of a hash key or array element. Takes one argument: the hash
d0b74c17 974key or array index. Returns a scalar, hash ref or array ref, depending on the
ffed8b01 975data type stored.
976
d0b74c17 977 my $value = $db->get("foo"); # for hashes
978 my $value = $db->get(1); # for arrays
ffed8b01 979
980=item * exists()
981
d0b74c17 982Checks if a hash key or array index exists. Takes one argument: the hash key
ffed8b01 983or array index. Returns true if it exists, false if not.
984
d0b74c17 985 if ($db->exists("foo")) { print "yay!\n"; } # for hashes
986 if ($db->exists(1)) { print "yay!\n"; } # for arrays
ffed8b01 987
988=item * delete()
989
990Deletes one hash key/value pair or array element. Takes one argument: the hash
991key or array index. Returns true on success, false if not found. For arrays,
992the remaining elements located after the deleted element are NOT moved over.
993The deleted element is essentially just undefined, which is exactly how Perl's
d0b74c17 994internal arrays work. Please note that the space occupied by the deleted
995key/value or element is B<not> reused again -- see L<UNUSED SPACE RECOVERY>
ffed8b01 996below for details and workarounds.
997
d0b74c17 998 $db->delete("foo"); # for hashes
999 $db->delete(1); # for arrays
ffed8b01 1000
1001=item * clear()
1002
d0b74c17 1003Deletes B<all> hash keys or array elements. Takes no arguments. No return
1004value. Please note that the space occupied by the deleted keys/values or
1005elements is B<not> reused again -- see L<UNUSED SPACE RECOVERY> below for
ffed8b01 1006details and workarounds.
1007
d0b74c17 1008 $db->clear(); # hashes or arrays
ffed8b01 1009
4d35d856 1010=item * lock() / unlock()
1011
1012q.v. Locking.
1013
1014=item * optimize()
1015
1016Recover lost disk space.
1017
1018=item * import() / export()
1019
1020Data going in and out.
1021
1022=item * set_digest() / set_pack() / set_filter()
1023
1024q.v. adjusting the interal parameters.
1025
ffed8b01 1026=back
1027
1028=head2 HASHES
1029
d0b74c17 1030For hashes, DBM::Deep supports all the common methods described above, and the
ffed8b01 1031following additional methods: C<first_key()> and C<next_key()>.
1032
1033=over
1034
1035=item * first_key()
1036
d0b74c17 1037Returns the "first" key in the hash. As with built-in Perl hashes, keys are
1038fetched in an undefined order (which appears random). Takes no arguments,
ffed8b01 1039returns the key as a scalar value.
1040
d0b74c17 1041 my $key = $db->first_key();
ffed8b01 1042
1043=item * next_key()
1044
1045Returns the "next" key in the hash, given the previous one as the sole argument.
1046Returns undef if there are no more keys to be fetched.
1047
d0b74c17 1048 $key = $db->next_key($key);
ffed8b01 1049
1050=back
1051
1052Here are some examples of using hashes:
1053
d0b74c17 1054 my $db = DBM::Deep->new( "foo.db" );
1055
1056 $db->put("foo", "bar");
1057 print "foo: " . $db->get("foo") . "\n";
1058
1059 $db->put("baz", {}); # new child hash ref
1060 $db->get("baz")->put("buz", "biz");
1061 print "buz: " . $db->get("baz")->get("buz") . "\n";
1062
1063 my $key = $db->first_key();
1064 while ($key) {
1065 print "$key: " . $db->get($key) . "\n";
1066 $key = $db->next_key($key);
1067 }
1068
1069 if ($db->exists("foo")) { $db->delete("foo"); }
ffed8b01 1070
1071=head2 ARRAYS
1072
d0b74c17 1073For arrays, DBM::Deep supports all the common methods described above, and the
1074following additional methods: C<length()>, C<push()>, C<pop()>, C<shift()>,
ffed8b01 1075C<unshift()> and C<splice()>.
1076
1077=over
1078
1079=item * length()
1080
1081Returns the number of elements in the array. Takes no arguments.
1082
d0b74c17 1083 my $len = $db->length();
ffed8b01 1084
1085=item * push()
1086
d0b74c17 1087Adds one or more elements onto the end of the array. Accepts scalars, hash
ffed8b01 1088refs or array refs. No return value.
1089
d0b74c17 1090 $db->push("foo", "bar", {});
ffed8b01 1091
1092=item * pop()
1093
1094Fetches the last element in the array, and deletes it. Takes no arguments.
1095Returns undef if array is empty. Returns the element value.
1096
d0b74c17 1097 my $elem = $db->pop();
ffed8b01 1098
1099=item * shift()
1100
d0b74c17 1101Fetches the first element in the array, deletes it, then shifts all the
1102remaining elements over to take up the space. Returns the element value. This
1103method is not recommended with large arrays -- see L<LARGE ARRAYS> below for
ffed8b01 1104details.
1105
d0b74c17 1106 my $elem = $db->shift();
ffed8b01 1107
1108=item * unshift()
1109
d0b74c17 1110Inserts one or more elements onto the beginning of the array, shifting all
1111existing elements over to make room. Accepts scalars, hash refs or array refs.
1112No return value. This method is not recommended with large arrays -- see
ffed8b01 1113<LARGE ARRAYS> below for details.
1114
d0b74c17 1115 $db->unshift("foo", "bar", {});
ffed8b01 1116
1117=item * splice()
1118
d0b74c17 1119Performs exactly like Perl's built-in function of the same name. See L<perldoc
ffed8b01 1120-f splice> for usage -- it is too complicated to document here. This method is
1121not recommended with large arrays -- see L<LARGE ARRAYS> below for details.
1122
1123=back
1124
1125Here are some examples of using arrays:
1126
d0b74c17 1127 my $db = DBM::Deep->new(
1128 file => "foo.db",
1129 type => DBM::Deep->TYPE_ARRAY
1130 );
1131
1132 $db->push("bar", "baz");
1133 $db->unshift("foo");
1134 $db->put(3, "buz");
1135
1136 my $len = $db->length();
1137 print "length: $len\n"; # 4
1138
1139 for (my $k=0; $k<$len; $k++) {
1140 print "$k: " . $db->get($k) . "\n";
1141 }
1142
1143 $db->splice(1, 2, "biz", "baf");
1144
1145 while (my $elem = shift @$db) {
1146 print "shifted: $elem\n";
1147 }
ffed8b01 1148
1149=head1 LOCKING
1150
d0b74c17 1151Enable automatic file locking by passing a true value to the C<locking>
ffed8b01 1152parameter when constructing your DBM::Deep object (see L<SETUP> above).
1153
d0b74c17 1154 my $db = DBM::Deep->new(
1155 file => "foo.db",
1156 locking => 1
1157 );
ffed8b01 1158
d0b74c17 1159This causes DBM::Deep to C<flock()> the underlying filehandle with exclusive
1160mode for writes, and shared mode for reads. This is required if you have
1161multiple processes accessing the same database file, to avoid file corruption.
1162Please note that C<flock()> does NOT work for files over NFS. See L<DB OVER
ffed8b01 1163NFS> below for more.
1164
1165=head2 EXPLICIT LOCKING
1166
d0b74c17 1167You can explicitly lock a database, so it remains locked for multiple
1168transactions. This is done by calling the C<lock()> method, and passing an
90f93b43 1169optional lock mode argument (defaults to exclusive mode). This is particularly
d0b74c17 1170useful for things like counters, where the current value needs to be fetched,
ffed8b01 1171then incremented, then stored again.
1172
d0b74c17 1173 $db->lock();
1174 my $counter = $db->get("counter");
1175 $counter++;
1176 $db->put("counter", $counter);
1177 $db->unlock();
1178
1179 # or...
ffed8b01 1180
d0b74c17 1181 $db->lock();
1182 $db->{counter}++;
1183 $db->unlock();
ffed8b01 1184
1185You can pass C<lock()> an optional argument, which specifies which mode to use
d0b74c17 1186(exclusive or shared). Use one of these two constants: C<DBM::Deep-E<gt>LOCK_EX>
1187or C<DBM::Deep-E<gt>LOCK_SH>. These are passed directly to C<flock()>, and are the
ffed8b01 1188same as the constants defined in Perl's C<Fcntl> module.
1189
d0b74c17 1190 $db->lock( DBM::Deep->LOCK_SH );
1191 # something here
1192 $db->unlock();
ffed8b01 1193
ffed8b01 1194=head1 IMPORTING/EXPORTING
1195
1196You can import existing complex structures by calling the C<import()> method,
1197and export an entire database into an in-memory structure using the C<export()>
1198method. Both are examined here.
1199
1200=head2 IMPORTING
1201
1202Say you have an existing hash with nested hashes/arrays inside it. Instead of
d0b74c17 1203walking the structure and adding keys/elements to the database as you go,
1204simply pass a reference to the C<import()> method. This recursively adds
ffed8b01 1205everything to an existing DBM::Deep object for you. Here is an example:
1206
d0b74c17 1207 my $struct = {
1208 key1 => "value1",
1209 key2 => "value2",
1210 array1 => [ "elem0", "elem1", "elem2" ],
1211 hash1 => {
1212 subkey1 => "subvalue1",
1213 subkey2 => "subvalue2"
1214 }
1215 };
1216
1217 my $db = DBM::Deep->new( "foo.db" );
1218 $db->import( $struct );
1219
1220 print $db->{key1} . "\n"; # prints "value1"
1221
1222This recursively imports the entire C<$struct> object into C<$db>, including
ffed8b01 1223all nested hashes and arrays. If the DBM::Deep object contains exsiting data,
d0b74c17 1224keys are merged with the existing ones, replacing if they already exist.
1225The C<import()> method can be called on any database level (not just the base
ffed8b01 1226level), and works with both hash and array DB types.
1227
ffed8b01 1228B<Note:> Make sure your existing structure has no circular references in it.
1229These will cause an infinite loop when importing.
1230
1231=head2 EXPORTING
1232
d0b74c17 1233Calling the C<export()> method on an existing DBM::Deep object will return
1234a reference to a new in-memory copy of the database. The export is done
ffed8b01 1235recursively, so all nested hashes/arrays are all exported to standard Perl
1236objects. Here is an example:
1237
d0b74c17 1238 my $db = DBM::Deep->new( "foo.db" );
1239
1240 $db->{key1} = "value1";
1241 $db->{key2} = "value2";
1242 $db->{hash1} = {};
1243 $db->{hash1}->{subkey1} = "subvalue1";
1244 $db->{hash1}->{subkey2} = "subvalue2";
1245
1246 my $struct = $db->export();
1247
1248 print $struct->{key1} . "\n"; # prints "value1"
ffed8b01 1249
1250This makes a complete copy of the database in memory, and returns a reference
d0b74c17 1251to it. The C<export()> method can be called on any database level (not just
1252the base level), and works with both hash and array DB types. Be careful of
1253large databases -- you can store a lot more data in a DBM::Deep object than an
ffed8b01 1254in-memory Perl structure.
1255
ffed8b01 1256B<Note:> Make sure your database has no circular references in it.
1257These will cause an infinite loop when exporting.
1258
1259=head1 FILTERS
1260
1261DBM::Deep has a number of hooks where you can specify your own Perl function
1262to perform filtering on incoming or outgoing data. This is a perfect
1263way to extend the engine, and implement things like real-time compression or
d0b74c17 1264encryption. Filtering applies to the base DB level, and all child hashes /
1265arrays. Filter hooks can be specified when your DBM::Deep object is first
1266constructed, or by calling the C<set_filter()> method at any time. There are
ffed8b01 1267four available filter hooks, described below:
1268
1269=over
1270
1271=item * filter_store_key
1272
d0b74c17 1273This filter is called whenever a hash key is stored. It
ffed8b01 1274is passed the incoming key, and expected to return a transformed key.
1275
1276=item * filter_store_value
1277
d0b74c17 1278This filter is called whenever a hash key or array element is stored. It
ffed8b01 1279is passed the incoming value, and expected to return a transformed value.
1280
1281=item * filter_fetch_key
1282
d0b74c17 1283This filter is called whenever a hash key is fetched (i.e. via
ffed8b01 1284C<first_key()> or C<next_key()>). It is passed the transformed key,
1285and expected to return the plain key.
1286
1287=item * filter_fetch_value
1288
d0b74c17 1289This filter is called whenever a hash key or array element is fetched.
ffed8b01 1290It is passed the transformed value, and expected to return the plain value.
1291
1292=back
1293
1294Here are the two ways to setup a filter hook:
1295
d0b74c17 1296 my $db = DBM::Deep->new(
1297 file => "foo.db",
1298 filter_store_value => \&my_filter_store,
1299 filter_fetch_value => \&my_filter_fetch
1300 );
1301
1302 # or...
1303
1304 $db->set_filter( "filter_store_value", \&my_filter_store );
1305 $db->set_filter( "filter_fetch_value", \&my_filter_fetch );
ffed8b01 1306
1307Your filter function will be called only when dealing with SCALAR keys or
1308values. When nested hashes and arrays are being stored/fetched, filtering
d0b74c17 1309is bypassed. Filters are called as static functions, passed a single SCALAR
ffed8b01 1310argument, and expected to return a single SCALAR value. If you want to
1311remove a filter, set the function reference to C<undef>:
1312
d0b74c17 1313 $db->set_filter( "filter_store_value", undef );
ffed8b01 1314
1315=head2 REAL-TIME ENCRYPTION EXAMPLE
1316
d0b74c17 1317Here is a working example that uses the I<Crypt::Blowfish> module to
ffed8b01 1318do real-time encryption / decryption of keys & values with DBM::Deep Filters.
d0b74c17 1319Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
ffed8b01 1320on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.
1321
d0b74c17 1322 use DBM::Deep;
1323 use Crypt::Blowfish;
1324 use Crypt::CBC;
1325
1326 my $cipher = Crypt::CBC->new({
1327 'key' => 'my secret key',
1328 'cipher' => 'Blowfish',
1329 'iv' => '$KJh#(}q',
1330 'regenerate_key' => 0,
1331 'padding' => 'space',
1332 'prepend_iv' => 0
1333 });
1334
1335 my $db = DBM::Deep->new(
1336 file => "foo-encrypt.db",
1337 filter_store_key => \&my_encrypt,
1338 filter_store_value => \&my_encrypt,
1339 filter_fetch_key => \&my_decrypt,
1340 filter_fetch_value => \&my_decrypt,
1341 );
1342
1343 $db->{key1} = "value1";
1344 $db->{key2} = "value2";
1345 print "key1: " . $db->{key1} . "\n";
1346 print "key2: " . $db->{key2} . "\n";
1347
1348 undef $db;
1349 exit;
1350
1351 sub my_encrypt {
1352 return $cipher->encrypt( $_[0] );
1353 }
1354 sub my_decrypt {
1355 return $cipher->decrypt( $_[0] );
1356 }
ffed8b01 1357
1358=head2 REAL-TIME COMPRESSION EXAMPLE
1359
1360Here is a working example that uses the I<Compress::Zlib> module to do real-time
1361compression / decompression of keys & values with DBM::Deep Filters.
d0b74c17 1362Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
ffed8b01 1363more on I<Compress::Zlib>.
1364
d0b74c17 1365 use DBM::Deep;
1366 use Compress::Zlib;
1367
1368 my $db = DBM::Deep->new(
1369 file => "foo-compress.db",
1370 filter_store_key => \&my_compress,
1371 filter_store_value => \&my_compress,
1372 filter_fetch_key => \&my_decompress,
1373 filter_fetch_value => \&my_decompress,
1374 );
1375
1376 $db->{key1} = "value1";
1377 $db->{key2} = "value2";
1378 print "key1: " . $db->{key1} . "\n";
1379 print "key2: " . $db->{key2} . "\n";
1380
1381 undef $db;
1382 exit;
1383
1384 sub my_compress {
1385 return Compress::Zlib::memGzip( $_[0] ) ;
1386 }
1387 sub my_decompress {
1388 return Compress::Zlib::memGunzip( $_[0] ) ;
1389 }
ffed8b01 1390
1391B<Note:> Filtering of keys only applies to hashes. Array "keys" are
1392actually numerical index numbers, and are not filtered.
1393
1394=head1 ERROR HANDLING
1395
1396Most DBM::Deep methods return a true value for success, and call die() on
95967a5e 1397failure. You can wrap calls in an eval block to catch the die.
ffed8b01 1398
d0b74c17 1399 my $db = DBM::Deep->new( "foo.db" ); # create hash
1400 eval { $db->push("foo"); }; # ILLEGAL -- push is array-only call
1401
90f93b43 1402 print $@; # prints error message
429e4192 1403
ffed8b01 1404=head1 LARGEFILE SUPPORT
1405
1406If you have a 64-bit system, and your Perl is compiled with both LARGEFILE
1407and 64-bit support, you I<may> be able to create databases larger than 2 GB.
1408DBM::Deep by default uses 32-bit file offset tags, but these can be changed
1409by calling the static C<set_pack()> method before you do anything else.
1410
d0b74c17 1411 DBM::Deep::set_pack(8, 'Q');
ffed8b01 1412
d0b74c17 1413This tells DBM::Deep to pack all file offsets with 8-byte (64-bit) quad words
1414instead of 32-bit longs. After setting these values your DB files have a
ffed8b01 1415theoretical maximum size of 16 XB (exabytes).
1416
ffed8b01 1417B<Note:> Changing these values will B<NOT> work for existing database files.
d0b74c17 1418Only change this for new files, and make sure it stays set consistently
1419throughout the file's life. If you do set these values, you can no longer
1420access 32-bit DB files. You can, however, call C<set_pack(4, 'N')> to change
ffed8b01 1421back to 32-bit mode.
1422
d0b74c17 1423B<Note:> I have not personally tested files > 2 GB -- all my systems have
1424only a 32-bit Perl. However, I have received user reports that this does
ffed8b01 1425indeed work!
1426
1427=head1 LOW-LEVEL ACCESS
1428
90f93b43 1429If you require low-level access to the underlying filehandle that DBM::Deep uses,
4d35d856 1430you can call the C<_fh()> method, which returns the handle:
ffed8b01 1431
d0b74c17 1432 my $fh = $db->_fh();
ffed8b01 1433
1434This method can be called on the root level of the datbase, or any child
1435hashes or arrays. All levels share a I<root> structure, which contains things
90f93b43 1436like the filehandle, a reference counter, and all the options specified
d0b74c17 1437when you created the object. You can get access to this root structure by
ffed8b01 1438calling the C<root()> method.
1439
d0b74c17 1440 my $root = $db->_root();
ffed8b01 1441
1442This is useful for changing options after the object has already been created,
f5be9b03 1443such as enabling/disabling locking. You can also store your own temporary user
1444data in this structure (be wary of name collision), which is then accessible from
1445any child hash or array.
ffed8b01 1446
1447=head1 CUSTOM DIGEST ALGORITHM
1448
1449DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing
1450keys. However you can override this, and use another algorithm (such as SHA-256)
d0b74c17 1451or even write your own. But please note that DBM::Deep currently expects zero
ffed8b01 1452collisions, so your algorithm has to be I<perfect>, so to speak.
1453Collision detection may be introduced in a later version.
1454
1455
1456
d0b74c17 1457You can specify a custom digest algorithm by calling the static C<set_digest()>
1458function, passing a reference to a subroutine, and the length of the algorithm's
1459hashes (in bytes). This is a global static function, which affects ALL DBM::Deep
1460objects. Here is a working example that uses a 256-bit hash from the
1461I<Digest::SHA256> module. Please see
ffed8b01 1462L<http://search.cpan.org/search?module=Digest::SHA256> for more.
1463
d0b74c17 1464 use DBM::Deep;
1465 use Digest::SHA256;
1466
1467 my $context = Digest::SHA256::new(256);
1468
1469 DBM::Deep::set_digest( \&my_digest, 32 );
1470
1471 my $db = DBM::Deep->new( "foo-sha.db" );
1472
1473 $db->{key1} = "value1";
1474 $db->{key2} = "value2";
1475 print "key1: " . $db->{key1} . "\n";
1476 print "key2: " . $db->{key2} . "\n";
1477
1478 undef $db;
1479 exit;
1480
1481 sub my_digest {
1482 return substr( $context->hash($_[0]), 0, 32 );
1483 }
ffed8b01 1484
1485B<Note:> Your returned digest strings must be B<EXACTLY> the number
1486of bytes you specify in the C<set_digest()> function (in this case 32).
1487
1488=head1 CIRCULAR REFERENCES
1489
1490DBM::Deep has B<experimental> support for circular references. Meaning you
1491can have a nested hash key or array element that points to a parent object.
1492This relationship is stored in the DB file, and is preserved between sessions.
1493Here is an example:
1494
d0b74c17 1495 my $db = DBM::Deep->new( "foo.db" );
1496
1497 $db->{foo} = "bar";
1498 $db->{circle} = $db; # ref to self
1499
4b93c86a 1500 print $db->{foo} . "\n"; # prints "bar"
1501 print $db->{circle}->{foo} . "\n"; # prints "bar" again
ffed8b01 1502
69c94980 1503B<Note>: Passing the object to a function that recursively walks the
ffed8b01 1504object tree (such as I<Data::Dumper> or even the built-in C<optimize()> or
69c94980 1505C<export()> methods) will result in an infinite loop. This will be fixed in
1506a future release.
ffed8b01 1507
1508=head1 CAVEATS / ISSUES / BUGS
1509
1510This section describes all the known issues with DBM::Deep. It you have found
1511something that is not listed here, please send e-mail to L<jhuckaby@cpan.org>.
1512
1513=head2 UNUSED SPACE RECOVERY
1514
14a3acb6 1515One major caveat with DBM::Deep is that space occupied by existing keys and
ffed8b01 1516values is not recovered when they are deleted. Meaning if you keep deleting
1517and adding new keys, your file will continuously grow. I am working on this,
d0b74c17 1518but in the meantime you can call the built-in C<optimize()> method from time to
ffed8b01 1519time (perhaps in a crontab or something) to recover all your unused space.
1520
d0b74c17 1521 $db->optimize(); # returns true on success
ffed8b01 1522
1523This rebuilds the ENTIRE database into a new file, then moves it on top of
1524the original. The new file will have no unused space, thus it will take up as
d0b74c17 1525little disk space as possible. Please note that this operation can take
1526a long time for large files, and you need enough disk space to temporarily hold
15272 copies of your DB file. The temporary file is created in the same directory
1528as the original, named with a ".tmp" extension, and is deleted when the
1529operation completes. Oh, and if locking is enabled, the DB is automatically
ffed8b01 1530locked for the entire duration of the copy.
1531
d0b74c17 1532B<WARNING:> Only call optimize() on the top-level node of the database, and
1533make sure there are no child references lying around. DBM::Deep keeps a reference
ffed8b01 1534counter, and if it is greater than 1, optimize() will abort and return undef.
1535
1536=head2 AUTOVIVIFICATION
1537
d0b74c17 1538Unfortunately, autovivification doesn't work with tied hashes. This appears to
1539be a bug in Perl's tie() system, as I<Jakob Schmidt> encountered the very same
ffed8b01 1540issue with his I<DWH_FIle> module (see L<http://search.cpan.org/search?module=DWH_File>),
d0b74c17 1541and it is also mentioned in the BUGS section for the I<MLDBM> module <see
ffed8b01 1542L<http://search.cpan.org/search?module=MLDBM>). Basically, on a new db file,
1543this does not work:
1544
d0b74c17 1545 $db->{foo}->{bar} = "hello";
ffed8b01 1546
1547Since "foo" doesn't exist, you cannot add "bar" to it. You end up with "foo"
1548being an empty hash. Try this instead, which works fine:
1549
d0b74c17 1550 $db->{foo} = { bar => "hello" };
ffed8b01 1551
1552As of Perl 5.8.7, this bug still exists. I have walked very carefully through
1553the execution path, and Perl indeed passes an empty hash to the STORE() method.
1554Probably a bug in Perl.
1555
eea0d863 1556=head2 REFERENCES
1557
1558(The reasons given assume a high level of Perl understanding, specifically of
1559references. You can safely skip this section.)
1560
1561Currently, the only references supported are HASH and ARRAY. The other reference
1562types (SCALAR, CODE, GLOB, and REF) cannot be supported for various reasons.
1563
1564=over 4
1565
1566=item * GLOB
1567
1568These are things like filehandles and other sockets. They can't be supported
1569because it's completely unclear how DBM::Deep should serialize them.
1570
1571=item * SCALAR / REF
1572
1573The discussion here refers to the following type of example:
1574
1575 my $x = 25;
1576 $db->{key1} = \$x;
1577
1578 $x = 50;
1579
1580 # In some other process ...
1581
1582 my $val = ${ $db->{key1} };
1583
1584 is( $val, 50, "What actually gets stored in the DB file?" );
1585
1586The problem is one of synchronization. When the variable being referred to
1587changes value, the reference isn't notified. This means that the new value won't
1588be stored in the datafile for other processes to read. There is no TIEREF.
1589
1590It is theoretically possible to store references to values already within a
1591DBM::Deep object because everything already is synchronized, but the change to
1592the internals would be quite large. Specifically, DBM::Deep would have to tie
1593every single value that is stored. This would bloat the RAM footprint of
1594DBM::Deep at least twofold (if not more) and be a significant performance drain,
1595all to support a feature that has never been requested.
1596
1597=item * CODE
1598
1599L<http://search.cpan.org/search?module=Data::Dump::Streamer> provides a
1600mechanism for serializing coderefs, including saving off all closure state.
1601However, just as for SCALAR and REF, that closure state may change without
1602notifying the DBM::Deep object storing the reference.
1603
1604=back
1605
ffed8b01 1606=head2 FILE CORRUPTION
1607
14a3acb6 1608The current level of error handling in DBM::Deep is minimal. Files I<are> checked
1609for a 32-bit signature when opened, but other corruption in files can cause
1610segmentation faults. DBM::Deep may try to seek() past the end of a file, or get
ffed8b01 1611stuck in an infinite loop depending on the level of corruption. File write
1612operations are not checked for failure (for speed), so if you happen to run
d0b74c17 1613out of disk space, DBM::Deep will probably fail in a bad way. These things will
ffed8b01 1614be addressed in a later version of DBM::Deep.
1615
1616=head2 DB OVER NFS
1617
14a3acb6 1618Beware of using DB files over NFS. DBM::Deep uses flock(), which works well on local
d0b74c17 1619filesystems, but will NOT protect you from file corruption over NFS. I've heard
1620about setting up your NFS server with a locking daemon, then using lockf() to
1621lock your files, but your mileage may vary there as well. From what I
1622understand, there is no real way to do it. However, if you need access to the
1623underlying filehandle in DBM::Deep for using some other kind of locking scheme like
ffed8b01 1624lockf(), see the L<LOW-LEVEL ACCESS> section above.
1625
1626=head2 COPYING OBJECTS
1627
d0b74c17 1628Beware of copying tied objects in Perl. Very strange things can happen.
1629Instead, use DBM::Deep's C<clone()> method which safely copies the object and
ffed8b01 1630returns a new, blessed, tied hash or array to the same level in the DB.
1631
d0b74c17 1632 my $copy = $db->clone();
ffed8b01 1633
90f93b43 1634B<Note>: Since clone() here is cloning the object, not the database location, any
1635modifications to either $db or $copy will be visible in both.
1636
ffed8b01 1637=head2 LARGE ARRAYS
1638
1639Beware of using C<shift()>, C<unshift()> or C<splice()> with large arrays.
1640These functions cause every element in the array to move, which can be murder
1641on DBM::Deep, as every element has to be fetched from disk, then stored again in
90f93b43 1642a different location. This will be addressed in the forthcoming version 1.00.
ffed8b01 1643
9be51a89 1644=head2 WRITEONLY FILES
1645
1646If you pass in a filehandle to new(), you may have opened it in either a readonly or
1647writeonly mode. STORE will verify that the filehandle is writable. However, there
1648doesn't seem to be a good way to determine if a filehandle is readable. And, if the
1649filehandle isn't readable, it's not clear what will happen. So, don't do that.
1650
ffed8b01 1651=head1 PERFORMANCE
1652
1653This section discusses DBM::Deep's speed and memory usage.
1654
1655=head2 SPEED
1656
d0b74c17 1657Obviously, DBM::Deep isn't going to be as fast as some C-based DBMs, such as
ffed8b01 1658the almighty I<BerkeleyDB>. But it makes up for it in features like true
1659multi-level hash/array support, and cross-platform FTPable files. Even so,
1660DBM::Deep is still pretty fast, and the speed stays fairly consistent, even
1661with huge databases. Here is some test data:
d0b74c17 1662
1663 Adding 1,000,000 keys to new DB file...
1664
1665 At 100 keys, avg. speed is 2,703 keys/sec
1666 At 200 keys, avg. speed is 2,642 keys/sec
1667 At 300 keys, avg. speed is 2,598 keys/sec
1668 At 400 keys, avg. speed is 2,578 keys/sec
1669 At 500 keys, avg. speed is 2,722 keys/sec
1670 At 600 keys, avg. speed is 2,628 keys/sec
1671 At 700 keys, avg. speed is 2,700 keys/sec
1672 At 800 keys, avg. speed is 2,607 keys/sec
1673 At 900 keys, avg. speed is 2,190 keys/sec
1674 At 1,000 keys, avg. speed is 2,570 keys/sec
1675 At 2,000 keys, avg. speed is 2,417 keys/sec
1676 At 3,000 keys, avg. speed is 1,982 keys/sec
1677 At 4,000 keys, avg. speed is 1,568 keys/sec
1678 At 5,000 keys, avg. speed is 1,533 keys/sec
1679 At 6,000 keys, avg. speed is 1,787 keys/sec
1680 At 7,000 keys, avg. speed is 1,977 keys/sec
1681 At 8,000 keys, avg. speed is 2,028 keys/sec
1682 At 9,000 keys, avg. speed is 2,077 keys/sec
1683 At 10,000 keys, avg. speed is 2,031 keys/sec
1684 At 20,000 keys, avg. speed is 1,970 keys/sec
1685 At 30,000 keys, avg. speed is 2,050 keys/sec
1686 At 40,000 keys, avg. speed is 2,073 keys/sec
1687 At 50,000 keys, avg. speed is 1,973 keys/sec
1688 At 60,000 keys, avg. speed is 1,914 keys/sec
1689 At 70,000 keys, avg. speed is 2,091 keys/sec
1690 At 80,000 keys, avg. speed is 2,103 keys/sec
1691 At 90,000 keys, avg. speed is 1,886 keys/sec
1692 At 100,000 keys, avg. speed is 1,970 keys/sec
1693 At 200,000 keys, avg. speed is 2,053 keys/sec
1694 At 300,000 keys, avg. speed is 1,697 keys/sec
1695 At 400,000 keys, avg. speed is 1,838 keys/sec
1696 At 500,000 keys, avg. speed is 1,941 keys/sec
1697 At 600,000 keys, avg. speed is 1,930 keys/sec
1698 At 700,000 keys, avg. speed is 1,735 keys/sec
1699 At 800,000 keys, avg. speed is 1,795 keys/sec
1700 At 900,000 keys, avg. speed is 1,221 keys/sec
1701 At 1,000,000 keys, avg. speed is 1,077 keys/sec
1702
1703This test was performed on a PowerMac G4 1gHz running Mac OS X 10.3.2 & Perl
17045.8.1, with an 80GB Ultra ATA/100 HD spinning at 7200RPM. The hash keys and
1705values were between 6 - 12 chars in length. The DB file ended up at 210MB.
ffed8b01 1706Run time was 12 min 3 sec.
1707
1708=head2 MEMORY USAGE
1709
1710One of the great things about DBM::Deep is that it uses very little memory.
1711Even with huge databases (1,000,000+ keys) you will not see much increased
14a3acb6 1712memory on your process. DBM::Deep relies solely on the filesystem for storing
ffed8b01 1713and fetching data. Here is output from I</usr/bin/top> before even opening a
1714database handle:
1715
d0b74c17 1716 PID USER PRI NI SIZE RSS SHARE STAT %CPU %MEM TIME COMMAND
1717 22831 root 11 0 2716 2716 1296 R 0.0 0.2 0:07 perl
ffed8b01 1718
d0b74c17 1719Basically the process is taking 2,716K of memory. And here is the same
ffed8b01 1720process after storing and fetching 1,000,000 keys:
1721
d0b74c17 1722 PID USER PRI NI SIZE RSS SHARE STAT %CPU %MEM TIME COMMAND
1723 22831 root 14 0 2772 2772 1328 R 0.0 0.2 13:32 perl
ffed8b01 1724
d0b74c17 1725Notice the memory usage increased by only 56K. Test was performed on a 700mHz
ffed8b01 1726x86 box running Linux RedHat 7.2 & Perl 5.6.1.
1727
1728=head1 DB FILE FORMAT
1729
1730In case you were interested in the underlying DB file format, it is documented
d0b74c17 1731here in this section. You don't need to know this to use the module, it's just
ffed8b01 1732included for reference.
1733
1734=head2 SIGNATURE
1735
1736DBM::Deep files always start with a 32-bit signature to identify the file type.
1737This is at offset 0. The signature is "DPDB" in network byte order. This is
90f93b43 1738checked for when the file is opened and an error will be thrown if it's not found.
ffed8b01 1739
1740=head2 TAG
1741
1742The DBM::Deep file is in a I<tagged format>, meaning each section of the file
d0b74c17 1743has a standard header containing the type of data, the length of data, and then
1744the data itself. The type is a single character (1 byte), the length is a
ffed8b01 174532-bit unsigned long in network byte order, and the data is, well, the data.
1746Here is how it unfolds:
1747
1748=head2 MASTER INDEX
1749
d0b74c17 1750Immediately after the 32-bit file signature is the I<Master Index> record.
1751This is a standard tag header followed by 1024 bytes (in 32-bit mode) or 2048
1752bytes (in 64-bit mode) of data. The type is I<H> for hash or I<A> for array,
ffed8b01 1753depending on how the DBM::Deep object was constructed.
1754
d0b74c17 1755The index works by looking at a I<MD5 Hash> of the hash key (or array index
1756number). The first 8-bit char of the MD5 signature is the offset into the
1757index, multipled by 4 in 32-bit mode, or 8 in 64-bit mode. The value of the
ffed8b01 1758index element is a file offset of the next tag for the key/element in question,
1759which is usually a I<Bucket List> tag (see below).
1760
ffed8b01 1761The next tag I<could> be another index, depending on how many keys/elements
1762exist. See L<RE-INDEXING> below for details.
1763
1764=head2 BUCKET LIST
1765
d0b74c17 1766A I<Bucket List> is a collection of 16 MD5 hashes for keys/elements, plus
1767file offsets to where the actual data is stored. It starts with a standard
1768tag header, with type I<B>, and a data size of 320 bytes in 32-bit mode, or
ffed8b01 1769384 bytes in 64-bit mode. Each MD5 hash is stored in full (16 bytes), plus
1770the 32-bit or 64-bit file offset for the I<Bucket> containing the actual data.
d0b74c17 1771When the list fills up, a I<Re-Index> operation is performed (See
ffed8b01 1772L<RE-INDEXING> below).
1773
1774=head2 BUCKET
1775
1776A I<Bucket> is a tag containing a key/value pair (in hash mode), or a
1777index/value pair (in array mode). It starts with a standard tag header with
1778type I<D> for scalar data (string, binary, etc.), or it could be a nested
1779hash (type I<H>) or array (type I<A>). The value comes just after the tag
1780header. The size reported in the tag header is only for the value, but then,
d0b74c17 1781just after the value is another size (32-bit unsigned long) and then the plain
1782key itself. Since the value is likely to be fetched more often than the plain
ffed8b01 1783key, I figured it would be I<slightly> faster to store the value first.
1784
ffed8b01 1785If the type is I<H> (hash) or I<A> (array), the value is another I<Master Index>
1786record for the nested structure, where the process begins all over again.
1787
1788=head2 RE-INDEXING
1789
1790After a I<Bucket List> grows to 16 records, its allocated space in the file is
d0b74c17 1791exhausted. Then, when another key/element comes in, the list is converted to a
1792new index record. However, this index will look at the next char in the MD5
1793hash, and arrange new Bucket List pointers accordingly. This process is called
1794I<Re-Indexing>. Basically, a new index tag is created at the file EOF, and all
179517 (16 + new one) keys/elements are removed from the old Bucket List and
1796inserted into the new index. Several new Bucket Lists are created in the
1797process, as a new MD5 char from the key is being examined (it is unlikely that
ffed8b01 1798the keys will all share the same next char of their MD5s).
1799
ffed8b01 1800Because of the way the I<MD5> algorithm works, it is impossible to tell exactly
d0b74c17 1801when the Bucket Lists will turn into indexes, but the first round tends to
1802happen right around 4,000 keys. You will see a I<slight> decrease in
1803performance here, but it picks back up pretty quick (see L<SPEED> above). Then
1804it takes B<a lot> more keys to exhaust the next level of Bucket Lists. It's
1805right around 900,000 keys. This process can continue nearly indefinitely --
1806right up until the point the I<MD5> signatures start colliding with each other,
1807and this is B<EXTREMELY> rare -- like winning the lottery 5 times in a row AND
1808getting struck by lightning while you are walking to cash in your tickets.
1809Theoretically, since I<MD5> hashes are 128-bit values, you I<could> have up to
1810340,282,366,921,000,000,000,000,000,000,000,000,000 keys/elements (I believe
ffed8b01 1811this is 340 unodecillion, but don't quote me).
1812
1813=head2 STORING
1814
d0b74c17 1815When a new key/element is stored, the key (or index number) is first run through
1816I<Digest::MD5> to get a 128-bit signature (example, in hex:
ffed8b01 1817b05783b0773d894396d475ced9d2f4f6). Then, the I<Master Index> record is checked
37c5bcf0 1818for the first char of the signature (in this case I<b0>). If it does not exist,
d0b74c17 1819a new I<Bucket List> is created for our key (and the next 15 future keys that
1820happen to also have I<b> as their first MD5 char). The entire MD5 is written
ffed8b01 1821to the I<Bucket List> along with the offset of the new I<Bucket> record (EOF at
d0b74c17 1822this point, unless we are replacing an existing I<Bucket>), where the actual
ffed8b01 1823data will be stored.
1824
1825=head2 FETCHING
1826
d0b74c17 1827Fetching an existing key/element involves getting a I<Digest::MD5> of the key
1828(or index number), then walking along the indexes. If there are enough
1829keys/elements in this DB level, there might be nested indexes, each linked to
1830a particular char of the MD5. Finally, a I<Bucket List> is pointed to, which
1831contains up to 16 full MD5 hashes. Each is checked for equality to the key in
1832question. If we found a match, the I<Bucket> tag is loaded, where the value and
ffed8b01 1833plain key are stored.
1834
ffed8b01 1835Fetching the plain key occurs when calling the I<first_key()> and I<next_key()>
1836methods. In this process the indexes are walked systematically, and each key
1837fetched in increasing MD5 order (which is why it appears random). Once the
d0b74c17 1838I<Bucket> is found, the value is skipped and the plain key returned instead.
1839B<Note:> Do not count on keys being fetched as if the MD5 hashes were
1840alphabetically sorted. This only happens on an index-level -- as soon as the
1841I<Bucket Lists> are hit, the keys will come out in the order they went in --
1842so it's pretty much undefined how the keys will come out -- just like Perl's
ffed8b01 1843built-in hashes.
1844
261d1296 1845=head1 CODE COVERAGE
1846
37c5bcf0 1847We use B<Devel::Cover> to test the code coverage of our tests, below is the
90f93b43 1848B<Devel::Cover> report on this module's test suite.
7910cf68 1849
386bab6c 1850 ----------------------------------- ------ ------ ------ ------ ------ ------
1851 File stmt bran cond sub time total
1852 ----------------------------------- ------ ------ ------ ------ ------ ------
1853 blib/lib/DBM/Deep.pm 94.9 80.6 73.0 100.0 37.9 90.4
1854 blib/lib/DBM/Deep/Array.pm 100.0 91.1 100.0 100.0 18.2 98.1
1855 blib/lib/DBM/Deep/Engine.pm 98.9 87.3 80.0 100.0 34.2 95.2
1856 blib/lib/DBM/Deep/Hash.pm 100.0 87.5 100.0 100.0 9.7 97.3
1857 Total 97.9 85.9 79.7 100.0 100.0 94.3
1858 ----------------------------------- ------ ------ ------ ------ ------ ------
37c5bcf0 1859
1860=head1 MORE INFORMATION
1861
1862Check out the DBM::Deep Google Group at L<http://groups.google.com/group/DBM-Deep>
1863or send email to L<DBM-Deep@googlegroups.com>.
261d1296 1864
aeeb5497 1865=head1 AUTHORS
ffed8b01 1866
1867Joseph Huckaby, L<jhuckaby@cpan.org>
37c5bcf0 1868
aeeb5497 1869Rob Kinyon, L<rkinyon@cpan.org>
ffed8b01 1870
1871Special thanks to Adam Sah and Rich Gaushell! You know why :-)
1872
1873=head1 SEE ALSO
1874
1875perltie(1), Tie::Hash(3), Digest::MD5(3), Fcntl(3), flock(2), lockf(3), nfs(5),
1876Digest::SHA256(3), Crypt::Blowfish(3), Compress::Zlib(3)
1877
1878=head1 LICENSE
1879
aeeb5497 1880Copyright (c) 2002-2006 Joseph Huckaby. All Rights Reserved.
ffed8b01 1881This is free software, you may use it and distribute it under the
1882same terms as Perl itself.
1883
1884=cut