19.6.1. tie( )-ing Once and Forever

This module imports two symbols from the Fcntl package that we will use to tie the DBM file. The first one is O_RDONLY, as we want the file to be opened only for reading. It is important to note that in the case of the tie( ) interface, nothing prevents you from updating the DBM file, even if the file was tied with the O_RDONLY flag. The second flag, O_CREAT, is used just in case the DBM file wasn't found where it was expected—in this case, an empty file will be created instead, since otherwise tie( ) will fail and the code execution will be aborted.

When Book::DBMCache::init( ) is called with a path to the DBM file as its argument, the global variable %dbm is tied to this file. We want the tie operation to happen before the first request is made, so we do it in the ChildInitHandler code executed from startup.pl:

use Book::DBMCache;
Apache->push_handlers(PerlChildInitHandler => sub {
                        Book::DBMCache::init("/tmp/foo.db");
                    });

When this is executed as an Apache::Registry script (assuming the DBM file was populated with the foo, bar key/value pair), we will see the following output:

The value of foo: [bar]

There's an easy way to guarantee that a tied hash is read-only: use a subclass of the tie module you're using that prevents writing. For example, you can subclass DB_File as follows:

package DB_File::ReadOnly;

use strict;
require DB_File;
$DB_File::ReadOnly::ISA = qw(DB_File);

sub STORE  {  }
sub DELETE {  }
sub CLEAR  {  }

1;

As you can see, the methods of the tie( ) interface that can alter the DBM file are overriden with methods that do nothing. Of course, you may want to use warn( ) or die( ) inside these methods, depending on how you want to flag writes. Any attempts to write probably should be considered serious problems.

Now you can use DB_File::ReadOnly just like you were using DB_File before, but you can be sure that the DBM file won't be modified through this interface.

19.6.2. Read/Write Access

The next step is to tie the existing /tmp/foo.db file, or create a new one if it doesn't already exist. Notice that the last argument for the tie is 'write', which tells DB_File::Lock to obtain an exclusive (write) lock before moving on. Once the exclusive lock is acquired and the DBM file is tied, the code assigns a random letter as a value and saves the change by calling untie( ), which unlocks the DBM and closes it. It's important to stress here that in our example the section of code between the calls to tie( ) and untie( ) is called a critical section, because while we are inside of it, no other process can read from or write to the DBM file. Therefore, it's important to keep it the execution time of this section as short as possible.

The next section is similar to the first one, but this time we ask for a shared (read) lock, as we only want to read the value from the DBM file. Once the value is read, it's printed. Since the letter was picked randomly, you will see something like this:

The value of foo: [d]

then this (when reloading again):

The value of foo: [z]

and so on.

Based on this example you can build more evolved code, and of course you may choose to use other locking wrapper modules, as discussed earlier.

19.6.3. Storing Complex Data Structures

As you can see, this example is very similar to the normal use of DB_File; we just use MLDBM instead, and tell it to use DB_File as an underlying DBM implementation. You can choose any other available implementation instead. If you don't specify one, SDBM_File is used.

The script creates a complicated nested data structure and stores it in the $rhscalar. Then we open the database and store this value as usual.

$VAR1 = {
          'bar' => [
                     'a',
                     'b',
                     'c'
                   ],
          'tar' => {
                     '1' => '1',
                     '2' => '4',
                     '3' => '9',
                     '4' => '16'
                   }
        };

That's exactly what we inserted into the DBM file.

There is one important note, though. If you want to modify a value that is a reference to a data structure, you cannot modify it directly. You have to retrieve the value, modify it, and store it back.

For example, in the above example you cannot do:

tie my %dbm, 'MLDBM', $dbfile, O_RDWR|O_CREAT, 
    0600, $DB_HASH or die $!;
# update the existing key
$dbm{foo}->{bar} = ['a'..'z']; # this doesn't work
untie %dbm;

if the key bar existed before. Instead, you should do the following:

tie my %dbm, 'MLDBM', $dbfile, O_RDWR|O_CREAT, 
    0600, $DB_HASH or die $!;
# update the existing key
my $tmp     = $dbm{foo};
$tmp->{bar} = ['a'..'z'];
$dbm{foo}   = $tmp;       # this works
untie %dbm;

This limitation exists because the perl TIEHASH interface currently has no support for multidimensional ties.

By default, MLDBM uses Data::Dumper to serialize the nested data structures. You may want to use the FreezeThaw or Storableserializer instead. In fact, Storable is the preferred one. To use Storable in our example, you should do:

use MLDBM qw(DB_File Storable);

at the beginning of the script.

Refer to the MLDBM manpage to find out more information about it.