.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Paranoid::BerkeleyDB 3pm"
.TH Paranoid::BerkeleyDB 3pm "2011-12-08" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Paranoid::BerkeleyDB \-\- BerkeleyDB CDS Object
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR BerkeleyDB.pm,v 0.85 2011/12/08 07:30:26 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Paranoid::BerkeleyDB;
\&
\&  $db = Paranoid::BerkeleyDB\->new(DbDir => \*(Aq/tmp\*(Aq, DbName => \*(Aqfoo.db\*(Aq, 
\&                                  DbMode => 0640);
\&  $rv = $db\->addDb($dbname);
\&
\&  $val = $db\->getVal($key);
\&  $val = $db\->getVal($key, $dbname);
\&
\&  $rv = $db\->setVal($key, $val);
\&  $rv = $db\->setVal($key, $val, $dbname);
\&
\&  @keys = $db\->getKeys();
\&  @keys = $db\->getKeys($dbname);
\&  @keys = $db\->getKeys(undef, \e&sub);
\&  @keys = $db\->getKeys($dbname, \e&sub);
\&
\&  $db\->purgeDb();
\&  $db\->purgeDb($dbname);
\&
\&  @dbs = $db\->listDbs();
\&
\&  $db\->cds_lock;
\&  $db\->cds_unlock;
\&
\&  # Close environment & databases
\&  $db = undef;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This provides a OO-based wrapper for BerkeleyDB that creates Concurrent Data
Store (\s-1CDS\s0) databases.  This is a feature of Berkeley \s-1DB\s0 v3.x and higher that
provides for concurrent use of Berkeley DBs.  It provides for multiple reader,
single writer locking, and multiple databases can share the same environment.
.PP
This module hides much of the complexity of the \s-1API\s0 (as provided by the
\&\fIBerkeleyDB\fR\|(3) module.  Conversely, it also severely limits the options and
flexibility of the module and libraries as well.  In short, if you want a
quick and easy way for local processes to have concurrent access to Berkeley
DBs without learning bdb internals, this is your module.  If you want full
access to all of the bdb features and tuning/scalability features, you'd
better learn dbd.
.PP
One particulary nice feature of this module, however, is that it's fork-safe.
That means you can open a \s-1CDS\s0 db in a parent process, fork, and continue r/w
operations without fear of corruption or lock contention due to stale
filehandles.
.PP
\&\fBlock\fR and \fBunlock\fR methods are also provided to allow mass changes as an
atomic operation.  Since the environment is always created with a single
global write lock (regardless of how many databases exist within the
environment) operations can be made on multiple databases.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  $db = Paranoid::BerkeleyDB\->new(DbDir => \*(Aq/tmp\*(Aq, DbName => \*(Aqfoo.db\*(Aq);
.Ve
.PP
This class method is the object instantiator.  Two arguments are required:  
\&\fBDbDir\fR which is the path to the directory where the database files will be 
stored, and \fBDbName\fR which is the filename of the database itself.  If 
\&\fBDbDir\fR doesn't exist it will be created for you automatically.
.PP
\&\fBDbMode\fR is optional, and if omitted defaults to 0700.  This affects the
database directory, files, and lockfile.
.PP
This method will create a BerkeleyDB Environment and will support 
multiprocess transactions.
.PP
Any errors in the operation will be stored in \fBParanoid::ERROR\fR.
.SS "addDb"
.IX Subsection "addDb"
.Vb 1
\&  $rv = $db\->addDb($dbname);
.Ve
.PP
This method adds another database to the current object and environment.  
Calling this method does require an exclusive write lock to the database 
to prevent race conditions.
.PP
Any errors in the operation will be stored in \fBParanoid::ERROR\fR.
.SS "getVal"
.IX Subsection "getVal"
.Vb 2
\&  $val = $db\->getVal($key);
\&  $val = $db\->getVal($key, $dbname);
.Ve
.PP
This method retrieves the associated string to the passed key.  Called with 
one argument the method uses the default database.  Otherwise, a second 
argument specifying the specific database is required.
.PP
Requesting a non-existent key or from a nonexistent database will result in 
an undef being returned.  In the case of the latter an error message will also
be set in \fBParanoid::ERROR\fR.
.SS "setVal"
.IX Subsection "setVal"
.Vb 2
\&  $rv = $db\->setVal($key, $val);
\&  $rv = $db\->setVal($key, $val, $dbname);
.Ve
.PP
This method adds or updates an associative pair.  If the passed value is
\&\fBundef\fR the key is deleted from the database.  If no database is explicitly
named it is assumed that the default database is the one to work on.
.PP
Requesting a non-existent key or from a nonexistent database will result in 
an undef being returned.  In the case of the latter an error message will also
be set in \fBParanoid::ERROR\fR.
.SS "getKeys"
.IX Subsection "getKeys"
.Vb 4
\&  @keys = $db\->getKeys();
\&  @keys = $db\->getKeys($dbname);
\&  @keys = $db\->getKeys(undef, \e&sub);
\&  @keys = $db\->getKeys($dbname, \e&sub);
.Ve
.PP
If this method is called without the optional subroutine reference it will
return all the keys in the hash in hash order.  If a subroutine reference is
called it will be called as each key/value pair is iterated over with three
arguments:
.PP
.Vb 1
\&    &$subRef($dbObj, $key, $value);
.Ve
.PP
with \f(CW$dbObj\fR being a handle to the current database object.  You may
use this ref to make changes to the database.  Anytime a code
reference is handed to this method it is automatically opened with a write
lock under the assumption that this might be a transformative operation.
.SS "purgeDb"
.IX Subsection "purgeDb"
.Vb 2
\&  $db\->purgeDb();
\&  $db\->purgeDb($dbname);
.Ve
.PP
This method purges all associative pairs from the designated database.  If no
database name was passed then the default database will be used.  This method
returns the number of records purged, or a \-1 if an invalid database was
requested.
.SS "listDbs"
.IX Subsection "listDbs"
.Vb 1
\&  @dbs = $db\->listDbs();
.Ve
.PP
This method returns a list of databases accessible by this object.
.SS "cds_lock"
.IX Subsection "cds_lock"
.Vb 1
\&    $db\->cds_lock;
.Ve
.PP
This method places a global write lock on the shared database environment.
Since environments are created with a global lock (covering all databases in
the environment) no writes or reads can be done by other processes until this
is unlocked.
.SS "cds_unlock"
.IX Subsection "cds_unlock"
.Vb 1
\&    $db\->cds_unlock;
.Ve
.PP
This method removes a global write lock on the shared database environment.
.SS "\s-1DESTROY\s0"
.IX Subsection "DESTROY"
A \s-1DESTROY\s0 method is provided which should sync and close an open database, as
well as release any locks.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Debug
.IP "o" 4
.IX Item "o"
Paranoid::Filesystem
.IP "o" 4
.IX Item "o"
Paranoid::Lockfile
.IP "o" 4
.IX Item "o"
BerkeleyDB
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Race conditions, particularly on database creation/opens, are worked around by
the use of external lock files and \fBflock\fR advisory file locks.  Lockfiles
are not used during normal operations on the database.
.PP
While \s-1CDS\s0 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.
.PP
Berkeley \s-1DB\s0 provides a handy \s-1CLI\s0 utility called \fIdb_stat\fR\|(1).  It can provide
some statistics on your shared database environment via invocation like so:
.PP
.Vb 1
\&  db_stat \-m \-h .
.Ve
.PP
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.
.PP
You can also show all existing locks via:
.PP
.Vb 1
\&    db_stat \-N \-Co \-h .
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&    L<BerkeleyDB(3)>
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
2011/12/06:  Added fork-safe operation
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005, Arthur Corliss (corliss@digitalmages.com)