NAME

Paranoid::BerkeleyDB -- BerkeleyDB Wrapper

VERSION

$Id: lib/Paranoid/BerkeleyDB.pm, 2.06 2022/03/08 22:26:06 acorliss Exp $

SYNOPSIS

            

              
              
tie %db, 'Paranoid::BerkeleyDB', Filename => './dbdir/data.db';
# Normal hash activities...
# Ensure atomic updates
$dref = tied %db;
$lock = $dref->cds_lock;
$db{$key}++;
$lock->cds_unlock;
untie %db;
            
          

DESCRIPTION

This module provides an OO/tie-based wrapper for BerkeleyDB CDS implementations intended for use in tied hashes.

NOTE: This module breaks significantly with previous incarnations of this module. The primary differences are as follows:

            

              
              
Pros
-------------------------------------------------------------
* Places no limitations on the developer regarding BerekelyDB
  environment and database options
* Automatically reuses existing environments for multiple 
  tied hashses
* Uses Btree databases in lieu of hashes, which tended to 
  have issues when the database size grew too large
* Has a fully implemented tied hash interface incorporating 
  CDS locks
* Has pervasive debugging built in using L<Paranoid::Debug>
Cons
-------------------------------------------------------------
* Is no longer considered fork-safe, attempted accesses will
  case the child process to B<croak>.
* Uses Btree databases in lieu of hashes, which does add 
  some additional memory overhead
            
          

SUBROUTINES/METHODS

new

            

              
              
tie %db, 'Paranoid::BerkeleyDB', 
  Filename => './dbdir/data.db';
tie %db, 'Paranoid::BerkeleyDB', 
  Home     => './dbenv';
  Filename => './dbdir/data.db';
            
          

This method is called implicitly when an object is tied. It supports a few differnet invocation styles. The simplest involves simply providing the Home and Filename options. This will set up a CDS environment using the defaults documented in Paranoid::BerkeleyDB::Env(3) and Paranoid::BerkeleyDB::Db(3).

Alternately, you can provide it with Filename and a Paranoid::BerkeleyDB::Env(3) object (or subclassed object) that you instantiated yourself:

            

              
              
tie %db, 'Paranoid::BerkeleyDB', 
  Env      => $env,
  Filename => 'data.db';
            
          

Finally, you can provide it with two hash options to fully control the environment and database instantiation of Paranoid::BerkeleyDB::Env(3) and Paranoid::BerkeleyDB::Db(3):

            

              
              
tie %db, 'Paranoid::BerkeleyDB', 
  Env      => { %envOpts },
  Db       => { %dbOpts };
            
          

dbh

            

              
              
$dref = tied %db;
$dbh  = $dref->dbh;
            
          

This method provides access to the BerkeleyDB::Btree(3) object reference.

cds_lock

            

              
              
$dref = tied %db;
$lock = $dref->cds_lock;
            
          

This method provides access to the CDS locks for atomic updates.

DEPENDENCIES

o

BerkeleyDB

o

Carp

o

Class::EHierarchy

o

Fcntl

o

Paranoid

o

Paranoid::BerkeleyDB::Db

o

Paranoid::BerkeleyDB::Env

o

Paranoid::Debug

o

Paranoid::IO

o

Paranoid::IO::Lockfile

BUGS AND LIMITATIONS

-Filename is interpreted differently depending on whether you're using an environment or not. If you're using this module as a standalone DB object any relative paths are interpreted according to your current working directory. If you are using an environment, however, it is interpreted relative to that environment's -Home.

SEE ALSO

            

              
              
L<BerkeleyDB(3)>, L<Paranoid::BerkeleyDB::Env>,
L<Paranoid::BerkeleyDB::Db>
            
          

HISTORY

02/12/2016 Complete rewrite

AUTHOR

Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

This software is licensed under the same terms as Perl, itself. Please see http://dev.perl.org/licenses/ for more information.

(c) 2005 - 2022, Arthur Corliss (corliss@digitalmages.com)

cpanm Paranoid::BerkeleyDB

perl -MCPAN -e shell
install Paranoid::BerkeleyDB