BerkeleyDB

 view release on metacpan or  search on metacpan

BerkeleyDB.pod.P  view on Meta::CPAN

=head1 NAME

BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4, 5 or 6

=head1 SYNOPSIS

  use BerkeleyDB;

  $env = new BerkeleyDB::Env [OPTIONS] ;

  $db  = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
  $db  = new BerkeleyDB::Hash [OPTIONS] ;

  $db  = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
  $db  = new BerkeleyDB::Btree [OPTIONS] ;

  $db  = tie @array, 'BerkeleyDB::Recno', [OPTIONS] ;
  $db  = new BerkeleyDB::Recno [OPTIONS] ;

  $db  = tie @array, 'BerkeleyDB::Queue', [OPTIONS] ;
  $db  = new BerkeleyDB::Queue [OPTIONS] ;

  $db  = new BerkeleyDB::Heap [OPTIONS] ;

  $db  = new BerkeleyDB::Unknown [OPTIONS] ;

  $status = BerkeleyDB::db_remove [OPTIONS]
  $status = BerkeleyDB::db_rename [OPTIONS]
  $status = BerkeleyDB::db_verify [OPTIONS]

  $hash{$key} = $value ;
  $value = $hash{$key} ;
  each %hash ;
  keys %hash ;
  values %hash ;

  $env = $db->Env()
  $status = $db->db_get()
  $status = $db->db_exists() ;
  $status = $db->db_put() ;
  $status = $db->db_del() ;
  $status = $db->db_sync() ;
  $status = $db->db_close() ;
  $status = $db->db_pget()
  $hash_ref = $db->db_stat() ;
  $status = $db->db_key_range();
  $type = $db->type() ;
  $status = $db->status() ;
  $boolean = $db->byteswapped() ;
  $status = $db->truncate($count) ;
  $status = $db->compact($start, $stop, $c_data, $flags, $end);
  $status = $db->get_blob_threshold($t1) ;
  $status = $db->get_blob_dir($dir) ;

  $bool = $env->cds_enabled();
  $bool = $db->cds_enabled();
  $lock = $db->cds_lock();
  $lock->cds_unlock();

  ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
  ($flag, $old_offset, $old_length) = $db->partial_clear() ;

  $cursor = $db->db_cursor([$flags]) ;
  $newcursor = $cursor->c_dup([$flags]);
  $status = $cursor->c_get() ;
  $status = $cursor->c_put() ;
  $status = $cursor->c_del() ;
  $status = $cursor->c_count() ;
  $status = $cursor->c_pget() ;
  $status = $cursor->status() ;
  $status = $cursor->c_close() ;
  $stream = $cursor->db_stream() ;

  $cursor = $db->db_join() ;
  $status = $cursor->c_get() ;
  $status = $cursor->c_close() ;

  $status = $stream->size($S);
  $status = $stream->read($data, $offset, $size);
  $status = $stream->write($data, $offset);

  $status = $env->txn_checkpoint()
  $hash_ref = $env->txn_stat()
  $status = $env->set_mutexlocks()
  $status = $env->set_flags()
  $status = $env->set_timeout()
  $status = $env->lock_detect()
  $status = $env->lsn_reset()
  $status = $env->get_blob_threshold($t1) ;
  $status = $env->get_blob_dir($dir) ;

  $txn = $env->txn_begin() ;
  $db->Txn($txn);
  $txn->Txn($db1, $db2,...);
  $status = $txn->txn_prepare()
  $status = $txn->txn_commit()
  $status = $txn->txn_abort()
  $status = $txn->txn_id()
  $status = $txn->txn_discard()
  $status = $txn->set_timeout()

  $status = $env->set_lg_dir();
  $status = $env->set_lg_bsize();
  $status = $env->set_lg_max();

  $status = $env->set_data_dir() ;
  $status = $env->set_tmp_dir() ;
  $status = $env->set_verbose() ;
  $db_env_ptr = $env->DB_ENV() ;

  $BerkeleyDB::Error
  $BerkeleyDB::db_version

  # DBM Filters
  $old_filter = $db->filter_store_key  ( sub { ... } ) ;
  $old_filter = $db->filter_store_value( sub { ... } ) ;
  $old_filter = $db->filter_fetch_key  ( sub { ... } ) ;
  $old_filter = $db->filter_fetch_value( sub { ... } ) ;

  # deprecated, but supported
  $txn_mgr = $env->TxnMgr();
  $status = $txn_mgr->txn_checkpoint()
  $hash_ref = $txn_mgr->txn_stat()
  $txn = $txn_mgr->txn_begin() ;

=head1 DESCRIPTION

B<NOTE: This document is still under construction. Expect it to be
incomplete in places.>

This Perl module provides an interface to most of the functionality
available in Berkeley DB versions 2, 3, 5 and 6. In general it is safe to assume
that the interface provided here to be identical to the Berkeley DB
interface. The main changes have been to make the Berkeley DB API work
in a Perl way. Note that if you are using Berkeley DB 2.x, the new
features available in Berkeley DB 3.x or later are not available via
this module.

The reader is expected to be familiar with the Berkeley DB
documentation. Where the interface provided here is identical to the
Berkeley DB library and the... TODO

The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are
particularly relevant.

The interface to Berkeley DB is implemented with a number of Perl
classes.

=head1 The BerkeleyDB::Env Class

The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB
function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and
B<DBENV-E<gt>open> in Berkeley DB 3.x (or later). Its purpose is to initialise a
number of sub-systems that can then be used in a consistent way in all
the databases you make use of in the environment.

If you don't intend using transactions, locking or logging, then you
shouldn't need to make use of B<BerkeleyDB::Env>.

Note that an environment consists of a number of files that Berkeley DB
manages behind the scenes for you. When you first use an environment, it
needs to be explicitly created. This is done by including C<DB_CREATE>
with the C<Flags> parameter, described below.

=head2 Synopsis

    $env = new BerkeleyDB::Env
             [ -Home         => $path, ]
             [ -Server       => $name, ]
             [ -CacheSize    => $number, ]
             [ -Config       => { name => value, name => value }, ]
             [ -ErrFile      => filename, ]
             [ -MsgFile      => filename, ]
             [ -ErrPrefix    => "string", ]
             [ -Flags        => number, ]
             [ -SetFlags     => bitmask, ]
             [ -LockDetect   => number, ]
             [ -TxMax        => number, ]
             [ -LogConfig    => number, ]
             [ -MaxLockers   => number, ]
             [ -MaxLocks     => number, ]
             [ -MaxObjects   => number, ]
             [ -SharedMemKey => number, ]

BerkeleyDB.pod.P  view on Meta::CPAN

=item -SetFlags

Calls ENV->set_flags with the supplied bitmask. Use this when you need to make
use of DB_ENV->set_flags before DB_ENV->open is called.

Only valid when Berkeley DB 3.x or better is used.

=item -LockDetect

Specifies what to do when a lock conflict occurs. The value should be one of

B<DB_LOCK_DEFAULT>

Use the default policy as specified by db_deadlock.

B<DB_LOCK_OLDEST>

Abort the oldest transaction.

B<DB_LOCK_RANDOM>

Abort a random transaction involved in the deadlock.

B<DB_LOCK_YOUNGEST>

Abort the youngest transaction.


=item -Verbose

Add extra debugging information to the messages sent to B<-ErrFile>.

=back

=head2 Methods

The environment class has the following methods:

=over 5

=item $env->errPrefix("string") ;

This method is identical to the B<-ErrPrefix> flag. It allows the
error prefix string to be changed dynamically.

=item $env->set_flags(bitmask, 1|0);

=item $txn = $env->TxnMgr()

Constructor for creating a B<TxnMgr> object.
See L<"TRANSACTIONS"> for more details of using transactions.

This method is deprecated. Access the transaction methods using the B<txn_>
methods below from the environment object directly.

=item $env->txn_begin()

TODO

=item $env->txn_stat()

TODO

=item $env->txn_checkpoint()

TODO

=item $env->status()

Returns the status of the last BerkeleyDB::Env method.


=item $env->DB_ENV()

Returns a pointer to the underlying DB_ENV data structure that Berkeley
DB uses.

=item $env->get_shm_key($id)

Writes the base segment ID for the shared memory region used by the
Berkeley DB environment into C<$id>. Returns 0 on success.

This option requires Berkeley DB 4.2 or better.

Use the C<-SharedMemKey> option when opening the environmet to set the
base segment ID.

=item $env->set_isalive()

Set the callback that determines if the thread of control, identified by
the pid and tid arguments, is still running.  This method should only be
used in combination with $env->failchk.

This option requires Berkeley DB 4.4 or better.

=item $env->failchk($flags)

The $env->failchk method checks for threads of control (either a true
thread or a process) that have exited while manipulating Berkeley DB
library data structures, while holding a logical database lock, or with an
unresolved transaction (that is, a transaction that was never aborted or
committed).

If $env->failchk determines a thread of control exited while holding
database read locks, it will release those locks. If $env->failchk
determines a thread of control exited with an unresolved transaction, the
transaction will be aborted.

Applications calling the $env->failchk method must have already called the
$env->set_isalive method, on the same DB environment, and must have
configured their database environment using the -ThreadCount flag. The
ThreadCount flag cannot be used on an environment that wasn't previously
initialized with it.

This option requires Berkeley DB 4.4 or better.

=item $env->stat_print

Prints statistical information.

BerkeleyDB.pod.P  view on Meta::CPAN

=item B<DB_RMW>

TODO.

=back

=head2 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;

TODO

=head2 ($flag, $old_offset, $old_length) = $db->partial_clear() ;

TODO

=head2 $db->byteswapped()

TODO

=head2 $status = $db->get_blob_threshold($t1) ;

Sets the parameter $t1 to the threshold value (in bytes) that is used to
determine when a data item is stored as a Blob.

=head2 $status = $db->get_blob_dir($dir) ;

Sets the $dir parameter to the directory where blob files are stored.

=head2 $db->type()

Returns the type of the database. The possible return code are B<DB_HASH>
for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree>
database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method
is typically used when a database has been opened with
B<BerkeleyDB::Unknown>.

=head2   $bool = $env->cds_enabled();

Returns true if the Berkeley DB environment C<$env> has been opened on
CDS mode.

=head2   $bool = $db->cds_enabled();

Returns true if the database C<$db> has been opened on CDS mode.

=head2 $lock = $db->cds_lock();

Creates a CDS write lock object C<$lock>.

It is a fatal error to attempt to create a cds_lock if the Berkeley DB
environment has not been opened in CDS mode.

=head2 $lock->cds_unlock();

Removes a CDS lock. The destruction of the CDS lock object automatically
calls this method.

Note that if multiple CDS lock objects are created, the underlying write
lock will not be released until all CDS lock objects are either explicitly
unlocked with this method, or the CDS lock objects have been destroyed.

=head2 $ref = $db->db_stat()

Returns a reference to an associative array containing information about
the database. The keys of the associative array correspond directly to the
names of the fields defined in the Berkeley DB documentation. For example,
in the DB documentation, the field B<bt_version> stores the version of the
Btree database. Assuming you called B<db_stat> on a Btree database the
equivalent field would be accessed as follows:

    $version = $ref->{'bt_version'} ;

If you are using Berkeley DB 3.x or better, this method will work will
all database formats. When DB 2.x is used, it only works with
B<BerkeleyDB::Btree>.

=head2 $status = $db->status()

Returns the status of the last C<$db> method called.

=head2 $status = $db->truncate($count)

Truncates the database and returns the number or records deleted
in C<$count>.

=head2  $status = $db->compact($start, $stop, $c_data, $flags, $end);

Compacts the database C<$db>.

All the parameters are optional - if only want to make use of some of them,
use C<undef> for those you don't want.  Trailing unused parameters can be
omitted. For example, if you only want to use the C<$c_data> parameter to
set the C<compact_fillpercent>, write you code like this

    my %hash;
    $hash{compact_fillpercent} = 50;
    $db->compact(undef, undef, \%hash);

The parameters operate identically to the C equivalent of this method.
The C<$c_data> needs a bit of explanation - it must be a hash reference.
The values of the following keys can be set before calling C<compact> and
will affect the operation of the compaction.

=over 5

=item * compact_fillpercent

=item * compact_timeout

=back

The following keys, along with associated values, will be created in the
hash reference if the C<compact> operation was successful.

=over 5

=item * compact_deadlock

=item * compact_levels

=item * compact_pages_free