DataFile - master class for managing data files
Shane P. McCarron <shane@aptest.com>
Copyright 2001-2011 Applied Testing and Technology, Inc. All Rights Reserved.
use DataFile; # create a new DataFile object my $file = new DataFile(path, readwrite, timeout); # update an object $status = $file->save(); # release the object, unlocking it $status = $file->release();
The DataFile class is a template class that manages accessing files composed of arbitrary data. The files can be in either serialized object format or in DBM file format. The methods in this class are expected to be extended in sub-classes that manage the data in the "data" attribute, and also manage any specialized attributes outside of the "data" attribute.
The data structure of this object is optimized to be most efficient when used in conjunction with MLDBM and a single key hashed database. This object CAN use serialized objects as well, but it is MUCH slower. Note that when using MLDBM, the save method doesn't do anything (except possibly for the first time it is called if the database had not yet been converted to MLDBM format).
a handle to the locked "lockfile" that is set for the object.
a boolean that indicates whether the datafile is open read/write
a boolean to indicate if the file is from a DBM source
a handle to the active, TIEd DBM file. This can be used by sub-classes to flush out the file, for example. NOTE: classes that use this class as a basis should either either use this handle directly to ensure that the data is flushed at obvious points in their implementation, or should call the save() method to ensure that it gets flushed.
The contents of the data attribute are up to the user, but it must be a pointer to a hash, and the keys of that hash should be sensibly structured.
$file = new DataFile(path, readWrite, timeout);
Creates a new DataFile object:
the name of the file to access.
boolean set to True if the existing session needs to be writeable. Defaults to readOnly.
the number of seconds to wait for a lock. Defaults to 60 seconds.
returns a reference to the DataFile object.
$file->release();
This method undefines the data structures associated with the session and releases the lock on the session.
Returns nothing.
$dataFile->initialize() ;
Removes all entries from the database. Asserts a lock locally, but you should ensure that you have a lock before you call this, since you are likely doing more than just clearing the database.
returns true if it succeeded, false if it did not.
Returns 1 if we are actively Locked, 0 if not. Only meaningful under MLDBM::Sync.
Lock uses the class' writeable flag to determine whether a read or a write lock is needed.
Note that this method attempts to use a pessimistic locking strategy - write locks set a write pending flag before trying to get the lock. Read locks look for such a flag and pause if it is there so that other reads have a change to finish and writes can get in.
Returns 1 on success, 0 on failure.
$ref->Relock() ;
Returns nothing.
Returns 1 on success, 0 on failure.
$state = $self->writeable() ;
Returns true if the database can be written to, and false if it cannot.
Returns the path to the object.
returns undef if the save failed. Returns the path saved into if the save succeeded.
$file->cache(size) ;
size is the number of bytes to set aside as a cache.
Sets up a database cache for items so that they are automatically kept resident to speed access on subsequent calls.
Returns nothing.
$file->dirtyFlag(); $file->dirtyFlag( 1 | 0 );
Calling this method with no arguments will return whether or not any data has changed since the ojbect was originally created.
When ever you DO change part of the object (most notably "data") you should call this method with the true value.
$lock = _flock($path, $readWrite, $timeout, $bailout, $suffix);
path is the path to lock.
readWrite is a boolean indicating whether the lock should be shared (a read lock), or exclusive (a write lock). Default is readOnly.
timeout is a timeout to try for the lock in seconds (default is 60).
bailout is a boolean - if true, then if timeout expires without the lock being set, the system bailOut method will be called, effectively aborting the operation. This boolean defaults to true.
suffix is an optional suffix to add to the lock name. The default is to use no suffix.
Copyright © 2000-2013 Applied Testing and Technology, Inc. All rights reserved.