/ 
Paranoid-BerkeleyDB-2.00
River stage zero No dependents
/ Paranoid::BerkeleyDB::Env

NAME

Paranoid::BerkeleyDB::Env -- BerkeleyDB CDS Env Object

VERSION

$Id: lib/Paranoid/BerkeleyDB/Env.pm, 2.00 2016/05/13 19:47:47 acorliss Exp $

SYNOPSIS

$db = Paranoid::BerkeleyDB::Env->new(-Home => './dbdir');

$env = $dbe->env;
@dbs = $dbe->dbs;

DESCRIPTION

This module provides an OO-based wrapper for the BerkeleyDB::Env class. Using this module in lieu of BerkeleyDB::Env directly provides fork-safe operation as well as clean shutdown of any databases using the environment.

While this class places no restrictions on the use of any available BerkeleyDB::Env options it does automatically deploy some defaults options oriented towards CDS access. These can be overridden, but if you're focused on CDS this will simplify their use.

SUBROUTINES/METHODS

new

$db = Paranoid::BerkeleyDB::Env->new(-Home => './dbdir');

The only required argument is -Home. For a complete list of all available options please see the document in BerkeleyDB.

By default the following settings are applied unless overridden:

Parameter   Value
---------------------------------------------------
-Flags      DB_CREATE | DB_INIT_CDB | DB_INIT_MPOOL
-ErrFile    {-Home}/db_err.log
-Verbose    1

env

$env = $dbe->env;

This returns a handle to the current BerkeleyDB::Env object. Calling this in a child will cause the class to automatically reopen an object to avoid conflicts with the parent process.

dbs

@dbs = $dbe->dbs;

This method returns a list of objects currently using this environment. Typically these will be Paranoid::BerkeleyDB::Db objects.

DESTROY

A DESTROY method is provided which should sync and close an open database, as well as release any locks.

DEPENDENCIES

o

BerkeleyDB

o

Class::EHierarchy

o

Fcntl

o

Paranoid

o

Paranoid::Debug

o

Paranoid::IO

o

Paranoid::IO::Lockfile

BUGS AND LIMITATIONS

Race conditions, particularly on environment creation/opens, are worked around by the use of external lock files and flock advisory file locks. Lockfiles are not used during normal operations on the environment.

While CDS allows for safe concurrent use of database files, it makes no allowances for recovery from stale locks. If a process exits badly and fails to release a write lock (which causes all other process operations to block indefinitely) you have to intervene manually. The brute force intervention would mean killing all accessing processes and deleting the environment files (files in the same directory call __db.*). Those will be recreated by the next process to access them.

Berkeley DB provides a handy CLI utility called db_stat(1). It can provide some statistics on your shared database environment via invocation like so:

db_stat -m -h .

The last argument, of course, is the directory in which the environment was created. The example above would work fine if your working directory was that directory.

You can also show all existing locks via:

db_stat -N -Co -h .

SEE ALSO

L<BerkeleyDB(3)>

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)