NAME

Tie::SymlinkTree - interface to a directory tree of symlinks

SYNOPSIS

use Tie::SymlinkTree;
tie %hash, 'Tie::SymlinkTree', '/some_directory';
$hash{'one'} = "some text";         # Creates symlink /some_directory/one
                                    # with contents "some text"
$hash{'bar'} = "some beer";
$hash{'two'} = [ "foo", "bar", "baz" ];
 
# Warning: experimental and subject to change without notice:
my @entries = tied(%hash)->search(sub { m/some/ }); # returns ("some text","some beer")
my $firstmatch = $hash{'two'}->search(sub { m/b/ }); # returns "bar"
print $firstmatch->id; # prints out "1", as it is element nr. 1

DESCRIPTION

The Tie::SymlinkTree module is a TIEHASH/TIEARRAY interface which lets you tie a Perl hash or array to a directory on the filesystem. Each entry in the hash represents a symlink in the directory.

To use it, tie a hash to a directory:

tie %hash, "Tie::SymlinkTree", "/some_directory";

Any changes you make to the hash will create, modify, or delete symlinks in the given directory. 'undef' values are represented by an empty file instead of a symlink.

If the directory itself doesn't exist Tie::SymlinkTree will create it (or die trying).

This module is fully reentrant, multi-processing safe, and still real fast (as the OS permits; a modern filesystem is recommended when storing lots of keys/array elements).

CAVEATS

Tie::SymlinkTree is restricted in what it can store: Keys may not contain "/" or start with a dot, values may not contain "\0" and are limited in length, depending on OS limits. You may store scalars, hashrefs and arrayrefs, these will be transparently mapped to subdirs as neccessary, nested as deeply as you wish, but no objects are allowed. (Order me a pizza to get any of these missing features ;-)

This module will probably only work on UNIXish systems.

How fast are ties? I can't tell. That is the most important bottleneck left.

RATIONALE

This module was designed for quick prototyping of multi-processing applications as often found in CGI scripts. It uses the fastest way to store and retrive small bits of information: Symlinks. "Small bits" is the key: most web-centric tasks involve a need for permanent storage, yet the usage pattern and data set size usually doesn't require a full SQL database.

Setting up a database schema and designing queries can be quite tedious when you're doing a prototype. A tie is much easier to use, but the usual Tie::* modules are lacking mp-safety or performance (or both), since they usually store the hash data in one big chunk. Tie::SymlinkTree avoids this bottleneck and source of bugs by only using atomic OS primitives on individual keys. Locking is not completely avoidable, but reduces to a minimum.

The result is a reasonably fast module that scales very nicely. One day I may write an API-compatible counterpart that uses SQL as storage, then you'd get an easy upgrade path.

AUTHOR and LICENSE

Copyright (C) 2004, Jörg Walter.

This plugin is licensed under either the GNU GPL Version 2, or the Perl Artistic License.