berkeleydb.pod

关于Berkelay数据库的共享源码

=head1 NAME

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

=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::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 ;

  $status = $db->db_get()
  $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);

  $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() ;

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

  $status = $env->txn_checkpoint()
  $hash_ref = $env->txn_stat()
  $status = $env->setmutexlocks()
  $status = $env->set_flags()
  $status = $env->set_timeout()
  $status = $env->lsn_reset()

  $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 and 4. 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 DB 4.x 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/4.x. 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, ]
             [ -ErrPrefix    => "string", ]
             [ -Flags        => number, ]
             [ -SetFlags     => bitmask, ]
             [ -LockDetect   => number, ]
             [ -SharedMemKey => number, ]
             [ -Verbose      => boolean, ]
             [ -Encrypt      => { Password => "string",
	                          Flags    => number }, ]

All the parameters to the BerkeleyDB::Env constructor are optional.

=over 5

=item -Home

If present, this parameter should point to an existing directory. Any
files that I<aren't> specified with an absolute path in the sub-systems
that are initialised by the BerkeleyDB::Env class will be assumed to
live in the B<Home> directory.

For example, in the code fragment below the database "fred.db" will be
opened in the directory "/home/databases" because it was specified as a
relative path, but "joe.db" will be opened in "/other" because it was
part of an absolute path.

    $env = new BerkeleyDB::Env
             -Home         => "/home/databases"
    ...

    $db1 = new BerkeleyDB::Hash
	     -Filename = "fred.db",
	     -Env => $env
    ...

    $db2 = new BerkeleyDB::Hash
	     -Filename = "/other/joe.db",
	     -Env => $env
    ...

=item -Server

If present, this parameter should be the hostname of a server that is running
the Berkeley DB RPC server. All databases will be accessed via the RPC server.

=item -Encrypt

If present, this parameter will enable encryption of  all data before
it is written to the database. This parameters must be given a hash
reference. The format is shown below.

    -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }

Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.

This option requires Berkeley DB 4.1 or better.

=item -Cachesize

If present, this parameter sets the size of the environments shared memory
buffer pool.

=item -SharedMemKey

If present, this parameter sets the base segment ID for the shared memory
region used by Berkeley DB. 

This option requires Berkeley DB 3.1 or better.

Use C<$env-E<gt>get_shm_key($id)> to find out the base segment ID used
once the environment is open.


=item -Config

This is a variation on the C<-Home> parameter, but it allows finer
control of where specific types of files will be stored.

The parameter expects a reference to a hash. Valid keys are:
B<DB_DATA_DIR>, B<DB_LOG_DIR> and B<DB_TMP_DIR>

The code below shows an example of how it can be used.

    $env = new BerkeleyDB::Env
             -Config => { DB_DATA_DIR => "/home/databases",
                          DB_LOG_DIR  => "/home/logs",
                          DB_TMP_DIR  => "/home/tmp"
                        }
    ...

=item -ErrFile

Expects a filename or filenhandle. Any errors generated internally by
Berkeley DB will be logged to this file. A useful debug setting is to
open environments with either

    -ErrFile => *STDOUT

or 

    -ErrFile => *STDERR

=item -ErrPrefix

Allows a prefix to be added to the error messages before they are sent
to B<-ErrFile>.

=item -Flags

The B<Flags> parameter specifies both which sub-systems to initialise,
as well as a number of environment-wide options.
See the Berkeley DB documentation for more details of these options.

Any of the following can be specified by OR'ing them:

B<DB_CREATE>

If any of the files specified do not already exist, create them.

B<DB_INIT_CDB>

Initialise the Concurrent Access Methods  

B<DB_INIT_LOCK>

Initialise the Locking sub-system.

B<DB_INIT_LOG>

Initialise the Logging sub-system.

B<DB_INIT_MPOOL>

Initialise the ...

B<DB_INIT_TXN>

Initialise the ...

B<DB_MPOOL_PRIVATE>

Initialise the ...

B<DB_INIT_MPOOL> is also specified.

Initialise the ...

B<DB_NOMMAP>

Initialise the ...

B<DB_RECOVER>



B<DB_RECOVER_FATAL>

B<DB_THREAD>

B<DB_TXN_NOSYNC>

B<DB_USE_ENVIRON>

B<DB_USE_ENVIRON_ROOT>

=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> 

B<DB_LOCK_OLDEST>

B<DB_LOCK_RANDOM>

B<DB_LOCK_YOUNGEST>

=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 environemt to set the
base segment ID.

=item $env->set_timeout($timeout, $flags)

=item $env->status()

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

=back

=head2 Examples

TODO.

=head1 Global Classes

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

=head1 THE DATABASE CLASSES

B<BerkeleyDB> supports the following database formats:

=over 5

=item B<BerkeleyDB::Hash>

This database type allows arbitrary key/value pairs to be stored in data
files. This is equivalent to the functionality provided by other
hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
the files created using B<BerkeleyDB::Hash> are not compatible with any
of the other packages mentioned.

A default hashing algorithm, which will be adequate for most applications,
is built into BerkeleyDB. If you do need to use your own hashing algorithm
it is possible to write your own in Perl and have B<BerkeleyDB> use
it instead.

=item B<BerkeleyDB::Btree>

The Btree format allows arbitrary key/value pairs to be stored in a
B+tree.

As with the B<BerkeleyDB::Hash> format, it is possible to provide a
user defined Perl routine to perform the comparison of keys. By default,
though, the keys are stored in lexical order.

=item B<BerkeleyDB::Recno>

TODO.


=item B<BerkeleyDB::Queue>

TODO.

=item B<BerkeleyDB::Unknown>

This isn't a database format at all. It is used when you want to open an
existing Berkeley DB database without having to know what type is it. 

=back


Each of the database formats described above is accessed via a
corresponding B<BerkeleyDB> class. These will be described in turn in
the next sections.

=head1 BerkeleyDB::Hash

Equivalent to calling B<db_open> with type B<DB_HASH> in Berkeley DB 2.x and
calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_HASH> in
Berkeley DB 3.x or greater. 

Two forms of constructor are supported:

    $db = new BerkeleyDB::Hash
                [ -Filename      => "filename", ]
                [ -Subname       => "sub-database name", ]
                [ -Flags         => flags,]
                [ -Property      => flags,]
                [ -Mode          => number,]
                [ -Cachesize     => number,]
                [ -Lorder        => number,]
                [ -Pagesize      => number,]
                [ -Env           => $env,]
                [ -Txn           => $txn,]
                [ -Encrypt       => { Password => "string",
	                              Flags    => number }, ],
                # BerkeleyDB::Hash specific
                [ -Ffactor       => number,]
                [ -Nelem         => number,]
                [ -Hash          => code reference,]