/ 
Tie-MLDBM-1.00
River stage zero No dependents
/ Tie::MLDBM

NAME

Tie::MLDBM - Multi-Level Storage and Locking Class

SYNOPSIS

use Tie::MLDBM;

my $obj = tie my %hash, 'Tie::MLDBM', {
    'Lock'      =>  'File',
    'Serialise' =>  'Storable',
    'Store'     =>  'DB_File'
} [.. other DBM arguments..] or die $!;

DESCRIPTION

This module provides the means to store arbitrary perl data, including nested references, in a serialised form within persistent data back-ends. This module builds upon the storage and locking mechanisms of MLDBM and MLDBM::Sync by incorporating a more expandible framework that allows for a much wider variety of component modules for serialisation, storage and resource locking. Indeed, all storage components of this framework exist as a direct IS-A inherited class of their parent storage module such that almost any module employing a tied-interface can now store multi-level nested data structures and incorporate locking synchronisation.

The Tie::MLDBM framework consists of four components: the interface, the locking component, the serialisation component and the storage component. The interface is implemented as a TIEHASH by the Tie::MLDBM module which in turn depends upon the functions provided by component modules. The locking or synchronisation component implements shared and exclusive access to the underlying storage component by means of semaphores. The serialisation component is that which serialises the nested data structure into a flat form ready for storage in the underlying storage component. The storage component can be any new or existing module which implements a TIEHASH interface to a persistent store. All storage modules of this framework inherit directly from the storage mechanism which they represent.

INTERFACE

The interface to the Tie::MLDBM module is intended to be simple and impose little in the way of a learning curve in its usage.

The mandatory first argument of the TIEHASH interface of this module is a hash reference which contains configuration parameters for the Tie::MLDBM framework. These configuration parameters define the behaviour and component modules of the Tie::MLDBM.

The following configuration parameters are mandatory:

Lock

The Lock parameter defines the Tie::MLDBM::Lock::* component module to be employed by the Tie::MLDBM framework for locking and synchronisation.

If left unspecified, this parameter defaults to Null which calls upon the Tie::MLDBM::Lock::Null module for locking and synchronisation - This module fulfills the locking component of the Tie::MLDBM framework, without actually implementing any resource synchronisation or locking.

The available locking and synchronisation mechanisms are dictated by those modules installed in the Tie::MLDBM::Lock::* namespace.

Serialisation

The Serialisation parameter defines the Tie::MLDBM::Serialisation::* component module to be employed by the Tie::MLDBM framework for the serialisation of nested data structures into flat forms ready for persistent storage.

The available serialisation mechanisms are dictated by those modules installed in the Tie::MLDBM::Serialisation::* namespace.

Store

The Store parameter defines the Tie::MLDBM::Store::* component module to be employed by the Tie::MLDBM framework for the persistent storage of serialised data.

The available serialisation mechanisms are dictated by those modules installed in the Tie::MLDBM::Store::* namespace.

In addition to these configuration parameters, component modules may require additional configuration parameters to be defined in order to change their behaviour. For example, the Tie::MLDBM::Lock::File module allows for the filename and directory location of the semaphore file employed to be defined via a Lockfile configuration argument.

The remaining arguments to the TIEHASH interface of the Tie::MLDBM module are passed directly onto the underlying storage TIEHASH, as defined by the Store configuration parameter. This arrangement allows for any module employing a TIEHASH interface to a persistent store to be used by the Tie::MLDBM framework, for the persistent storage of serialised data.

Example Using DB_File

An example of the TIEHASH interface of Tie::MLDBM, employing the DB_File TIEHASH interface for persistent storage:

use Tie::MLDBM;

tie my %test, 'Tie::MLDBM', {
    'Serialise' =>  'Storable',
    'Store'     =>  'DB_File'
}, 'testdb.dbm', O_CREAT|O_RDWR, 0640 or die $!;

The above example creates a persistent store for the hash %test called testdb.dbm with DB_File in which data is serialised using Storable.

Example Using DBI

An example of the TIEHASH interface of Tie::MLDBM, employing the TIEHASH interface of Tie::DBI (by means of Tie::MLDBM::Store::DBI for persistent storage:

use Tie::MLDBM;

tie my %db, 'Tie::MLDBM', {
    'Lock'      =>  'File',
    'Serialise' =>  'Storable',
    'Store'     =>  'DBI'
}, {
    'db'        =>  "Pg:dbname=@{[ DATABASE ]}",
    'table'     =>  'sessions',
    'key'       =>  'id',
    'user'      =>  USERNAME,
    'password'  =>  PASSWORD,
    'CLOBBER'   =>  0
} or die $!;

The above example creates a persistent store for the hash %db which employs the sessions table of a PostgreSQL database for the storage of data serialised by Storable.

WARNINGS

The addition or alteration of elements to nested data structures is not entirely transparent in Perl. As such, in order to store a reference or modify an existing reference value within a tied hash, the value must first be retrieved and stored in a temporary variable before modification. For example, the following will not work:

$hash{'key'}{'subkey'} = 'value';   #   Will not work

Instead, this operation should be performed in a two-step process, like thus:

$temp = $hash{'key'};               #   Retrieve element
$temp->{'subkey'} = 'value';
$hash{'key'} = $temp;               #   Store element

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

AUTHOR

Rob Casey <robau@cpan.org>

COPYRIGHT

Copyright 2002 Rob Casey, robau@cpan.org

SEE ALSO

MLDBM, MLDBM::Sync