Digital Mages

Digital Mages - Paranoid::BerkeleyDB(3)

Paranoid::BerkeleyDB

Section: User Contributed Perl Documentation (3)
Updated: 2017-02-06
Index  

NAME

Paranoid::BerkeleyDB -- BerkeleyDB Wrapper  

VERSION

$Id: lib/Paranoid/BerkeleyDB.pm, 2.03 2017/02/06 02:49:24 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 - 2016, Arthur Corliss (corliss@digitalmages.com)


 

Index

NAME
VERSION
SYNOPSIS
DESCRIPTION
SUBROUTINES/METHODS
new
dbh
cds_lock
DEPENDENCIES
BUGS AND LIMITATIONS
SEE ALSO
HISTORY
AUTHOR
LICENSE AND COPYRIGHT