DWH_File 0.24

DWH_File module contains data and object persistence in deep and wide hashes.

SYNOPSIS

use DWH_File qw/ GDBM_File /;
# the use argument set the DBM module used

tie( %h, DWH_File, myFile, O_RDWR|O_CREAT, 0644 );

untie( %h ); # essential!

Note: the files produced by DWH_File 0.22 are in a different format and are incompatible with the files produced by previous versions.

DWH_File is used in a manner resembling NDBM_File, DB_File etc. These DBM modules are limited to storing flat scalar values. References to data such as arrays or hashes are stored as useless strings and the data in the referenced structures will be lost.

DWH_File uses one of the DBM modules (configurable through the parameters to use()), but extends the functionality to not only save referenced data structures but even object systems.

This is why I made it. It makes it extremely simple to achieve persistence in object oriented Perl programs and you can skip the cumbersome interaction with a conventional database.

DWH_File tries to make the tied hash behave as much like a standard Perl hash as possible. Besides the capability to store nested data structures DWH_File also implements exists(), delete() and undef() functionality like that of a standard hash (as opposed to all the DBM modules).

MULTIPLE DBM FILES

It is possible to distribute for instance an object system over several files if wanted. This might be practical to avoid huge single files and may also make it easier make a reasonable structure in the data. If this feature is used the same set of files should be tied each time if any of the contents that may refer across files is altered. See MODELS.

GARBAGE COLLECTION

DWH_File uses a garbage collection scheme similar to that of Perl itself. This means that you actually dont have to worry about freeing anything (see the cyclic reference caveat though). Just like Perl DWH_File will remove entries that nothing is pointing to (and therefore noone can ever get at). If youve got a key whose value refers to an array for instance, that array will be swept away if you assign something else to the key. Unless theres a reference to the array somewhere else in the structure. This works even across different dbm files when using multiple files.

The garbage collection housekeeping is performed at untie time - so it is mandatory to call untie (and if you keep any references to the tied object to undef those in advance). Otherwise youll leave the object at the mercy of global destruction and garbage wont be properly collected.

MUTUAL EXCLUSION

Ealier versions had some specialized locking schemes to deal with concurrency in eg. web-applications. I havnt put any into this version, and I think Ill leave them out to avoid scope creep.

The reason for having those features were that locking dbm-files isnt as straightforward as locking ordinary files. I find now, that the best solution is to use some of the generalized mechanisms for handling concurrency. There are some fine perl modules for facilitating the use of semaphores for instance.

LOGGING

Earlier versions had a logging feature. I havent put it into this new generation of DWH_File yet. If you need it, send me a mail. That might tempt me.