berkeleydb.pod.p

BerkeleyDB源码

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,]
                [ -DupCompare    => code reference,]

and this

    [$db =] tie %hash, '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,]
                [ -DupCompare    => code reference,]


When the "tie" interface is used, reading from and writing to the database
is achieved via the tied hash. In this case the database operates like
a Perl associative array that happens to be stored on disk.

In addition to the high-level tied hash interface, it is possible to
make use of the underlying methods provided by Berkeley DB

=head2 Options

In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Hash> supports these options:

=over 5

=item -Property

Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:

B<DB_DUP>

When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.

B<DB_DUPSORT>

Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.

=item -Ffactor

=item -Nelem

See the Berkeley DB documentation for details of these options.

=item -Hash

Allows you to provide a user defined hash function. If not specified, 
a default hash function is used. Here is a template for a user-defined
hash function

    sub hash
    {
        my ($data) = shift ;
        ...
        # return the hash value for $data
	return $hash ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename => $filename, 
    	-Hash     => \&hash,
	...

See L<""> for an example.

=item -DupCompare

Used in conjunction with the B<DB_DUPOSRT> flag. 

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
	-Property   => DB_DUP|DB_DUPSORT,
    	-DupCompare => \&compare,
	...

=back


=head2 Methods

B<BerkeleyDB::Hash> only supports the standard database methods.
See L<COMMON DATABASE METHODS>.

=head2 A Simple Tied Hash Example

## simpleHash

here is the output:

    Banana Exists
    
    orange -> orange
    tomato -> red
    banana -> yellow

Note that the like ordinary associative arrays, the order of the keys
retrieved from a Hash database are in an apparently random order.

=head2 Another Simple Hash Example

Do the same as the previous example but not using tie.

## simpleHash2

=head2 Duplicate keys

The code below is a variation on the examples above. This time the hash has
been inverted. The key this time is colour and the value is the fruit name.
The B<DB_DUP> flag has been specified to allow duplicates.

##dupHash

here is the output:

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> banana
    green -> apple

=head2 Sorting Duplicate Keys

In the previous example, when there were duplicate keys, the values are
sorted in the order they are stored in. The code below is
identical to the previous example except the B<DB_DUPSORT> flag is
specified.

##dupSortHash

Notice that in the output below the duplicate values are sorted.

    orange -> orange
    yellow -> banana
    red -> apple
    red -> tomato
    green -> apple
    green -> banana

=head2 Custom Sorting Duplicate Keys

Another variation 

TODO

=head2 Changing the hash

TODO

=head2 Using db_stat

TODO

=head1 BerkeleyDB::Btree

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

Two forms of constructor are supported:


    $db = new BerkeleyDB::Btree
                [ -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::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

and this

    [$db =] tie %hash, 'BerkeleyDB::Btree', 
                [ -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::Btree specific
                [ -Minkey        => number,]
                [ -Compare       => code reference,]
                [ -DupCompare    => code reference,]
                [ -Prefix        => code reference,]

=head2 Options

In addition to the standard set of options (see L<COMMON OPTIONS>)
B<BerkeleyDB::Btree> supports these options:

=over 5

=item -Property

Used to specify extra flags when opening a database. The following
flags may be specified by bitwise OR'ing together one or more of the
following values:

B<DB_DUP>

When creating a new database, this flag enables the storing of duplicate
keys in the database. If B<DB_DUPSORT> is not specified as well, the
duplicates are stored in the order they are created in the database.

B<DB_DUPSORT>

Enables the sorting of duplicate keys in the database. Ignored if
B<DB_DUP> isn't also specified.

=item Minkey

TODO

=item Compare

Allow you to override the default sort order used in the database. See
L<"Changing the sort order"> for an example.

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Compare    => \&compare,
	...

=item Prefix

    sub prefix
    {
	my ($key, $key2) = @_ ;
        ...
        # return number of bytes of $key2 which are 
        # necessary to determine that it is greater than $key1
        return $bytes ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-Prefix     => \&prefix,
	...
=item DupCompare

    sub compare
    {
	my ($key, $key2) = @_ ;
        ...
        # return  0 if $key1 eq $key2
        #        -1 if $key1 lt $key2
        #         1 if $key1 gt $key2
        return (-1 , 0 or 1) ;
    }

    tie %h, "BerkeleyDB::Hash", 
        -Filename   => $filename, 
    	-DupCompare => \&compare,
	...

=back

=head2 Methods

B<BerkeleyDB::Btree> supports the following database methods.
See also L<COMMON DATABASE METHODS>.

All the methods below return 0 to indicate success.

=over 5

=item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])

Given a key, C<$key>, this method returns the proportion of keys less than 
C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
proportion greater than C<$key> in C<$greater>.

The proportion is returned as a double in the range 0.0 to 1.0.

=back

=head2 A Simple Btree Example

The code below is a simple example of using a btree database.

## btreeSimple

Here is the output from the code above. The keys have been sorted using
Berkeley DB's default sorting algorithm.

    Smith
    Wall
    mouse


=head2 Changing the sort order

It is possible to supply your own sorting algorithm if the one that Berkeley
DB used isn't suitable. The code below is identical to the previous example
except for the case insensitive compare function.

## btreeSortOrder

Here is the output from the code above.

    mouse
    Smith
    Wall