view release on metacpan or  search on metacpan

DirDB.pm  view on Meta::CPAN

		# warn "key: <$key>";
		if ($key =~ m/^ /){
			# we have unescaped a leading space.
		}elsif ($key eq 'EMPTY'){
			$key = ''
		#}elsif($key eq 'REF'){
		# 	return $ref->NEXTKEY();	# next
		#}elsif($key =~ m/^ARRAY){
		# 	return $ref->NEXTKEY();	# next
		}else{
			# per-container metadata does not
			# appear in iterations through data.
			return $ref->NEXTKEY();	# next
		}
	};
	wantarray or return $key;
	return @{[$key, $ref->FETCH($key)]};
   };
   
   sub DESTROY{
       delete $IteratorListings{$_[0]};
       delete $ArrayImpl{$_[0]};
   };
 
}; # end visibility of %IteratorListings

sub lock{
	my $path = ${shift @_};
	my $key= '';
	if(@_){
		$key = shift;
		length $key or $key = ' EMPTY';
	};
	return obtain DirDB::lock "$path$key";
};

package DirDB::lock;
use Carp;
my %OldLocks;
sub obtain{
	my $path = shift;
	while(!mkdir "$path LOCK",0777){
		select(undef,undef,undef,0.2); 
	};
	bless \$path;
};
sub release{
	rmdir "$$_[0] LOCK" or croak "failure releasing $$_[0]: $!";
	$OldLocks{"$_[0]"} = 1;
};
sub DESTROY{
	delete $OldLocks{"$_[0]"} or
	rmdir "$$_[0] LOCK" or croak "failure releasing $$_[0]: $!";
};

1;
__END__

=head1 NAME

DirDB - use a directory as a persistence back end for (multi-level) (blessed) hashes (that may contain array references) (and can be advisorialy locked)

=head1 SYNOPSIS

  use DirDB;
  tie my %session, 'DirDB', "./data/session";
  $session{$sessionID}{email} = get_emailaddress();
  $session{$sessionID}{objectcache}{fribble} ||= new fribble;
  #
  use Tie::File; # see below -- any array-in-a-filesystem representation
                 # is supported
  push @{$session{$sessionID}{events}}, $event;

=head1 DESCRIPTION

DirDB is a package that lets you access a directory
as a hash. The final directory will be created, but not
the whole path to it. It is similar to Tie::Persistent, but different
in that all accesses are immediately reflected in the file system,
and very little is kept in perl memory. (your OS's file cacheing
takes care of that -- DirDB only hits the disk a lot on poorly
designed operating systems without file system caches, which isn't
any of them any more.)

The empty string, used as a key, will be translated into
' EMPTY' for purposes of storage and retrieval.  File names
beginning with a space are reserved for metadata for subclasses,
such as object type or array size or whatever.  Key names beginning
with a space get an additional space prepended to the name
for purposes of naming the file to store that value.

As of version 0.05, DirDB can store hash references. references
to tied hashes are recursively copied, references to plain
hashes are first tied to DirDB and then recursively copied. Storing
a circular hash reference structure will cause DirDB to croak.

As of version 0.06, DirDB now recursively copies subdirectory contents
into an in-memory hash and returns a reference to that hash when
a previously stored hash reference is deleted in non-void context.

As of version 0.07, non-HASH references are stored using L<Storable>

As of version 0.08, non-HASH references cause croaking again: the
Storable functioning has been moved to L<DirDB::Storable>

Version 0.10 will store and retrieve blessed hash-references and
blesses them back into what they were when they were stored.

Version 0.12 closes some directory handles which were not
being closed automatically on cygwin, interfering with tests
passing.

=head2 ARRAY tie-time argument

Version 0.11 allows storing and retrieval of references to arrays
through taking an 'ARRAY' tie-time argument, which is an arrayref
of the args used to tie the array before returning it. A token that
is string-equal to 'DATAPATH' will be replaced with a place in the
file system for the array tieing implementation to do it's thing.
At this version, the default array implementation is