/ 
PTools-SDF-0.01
/ PTools::SDF::Lock::Selective

NAME

SDF::Lock::Selective - Lock/Unlock a file or filehandle using 'selective' locking

VERSION

This document describes version 0.01, released Feb 05, 2003.

SYNOPSIS

Obtain lock on a filename or filepath

    use PTools::SDF::Lock::Selective;

    $lockObj = new PTools::SDF::Lock::Selective;

    ($stat,$err) = $lockObj->lock( $fileName );

or  $lockObj->lock( $fileName, $maxRetries, $sleepTime, $lockMode, $openMode );

    ($stat,$err) = $lockObj->status;

    ($stat,$err) = $lockObj->unlock;

The '$fileName' need not exist prior to calling the 'lock' method, but it will exist if the lock succeeds.

Default for the '$openMode' variable is 0644, or '-rw-r--r--')

Explicit unlock is unnecessary. Simply allow the '$lockObj' variable to fall out of scope (or exit the script, undefine, etc.) to release the lock.

Obtain lock on an open filehandle

    use Fcntl;
    use PTools::SDF::Lock::Selective;

    $lockObj = new PTools::SDF::Lock::Selective;

    local(*FH);
    sysopen(FH, "/some/file", O_RDWR|O_CREAT, 0644) || die $!;
    $fh = *FH;

    ($stat,$err) = $lockObj->lock( $fh );
or  ($stat,$err) = $lockObj->lock( $fh, $maxRetries, $sleepTime, $lockMode );

The 'status' and 'unlock' methods are the same as above, and an '$openMode' parameter is obviously not needed here.

Obtain lock on an instance of an 'SDF::<module>' class

use PTools::SDF::INI;        # or PTools::SDF::SDF,  or PTools::SDF::TAG 

$iniObj = new PTools::SDF::INI( $fileName );

$iniObj->extend( [ "lock","unlock" ], "PTools::SDF::Lock::Selective");

($stat,$err) = $iniObj->lock( $maxRetries, $sleepTime, $lockMode );

The 'status' and 'unlock' methods are the same as above.

Note that the braces ([, ]) used in the above example show the litersl syntax used to pass an array reference into a subroutine. They are not used here to imply optional parameters. Optionally, use:

$arrayRef = [ "lock", "unlock" ];

$iniObj->extend( $arrayRef, "PTools::SDF::Lock::Selective");

Invoke lock method from within an 'SDF::<module>' class

The lock and unlock methods are implemented as extendible methods in an abstract base class. See PTools::SDF::File or EPTools::xtender for discussion and examples of this mechanism.

DESCRIPTION

The discussion and syntax here is intended for:

1) anyone who would like to use this class as a 'standalone' mechanism to obtain a lock on an arbitrary filedescriptor or open filehandle

2) PTools::SDF::<module> designers who would like to incorporate a locking mechanism within their modules (whether extendible or not)

Note: For end users of the PTools::SDF::<module> classes (e.g., PTools::SDF::INI, SDF::SDF and PTools::SDF::TAG), refer to the documentation accompanying these classes for a discussion of the lock and unlock methods.

The explanations, below, are intended to be complete enough for the module designers without being too confusing for users wishing to use this as a 'standalone' lock/unlock mechanism.

FIX: is the following still true?

B<WARNING>: This module implements simple B<selective locking> only. Any
module that chooses not to check for and honor the existance of an advisory
lock has full access to modify and/or delete the 'locked' data file.

Constructor

new

Explicit use of the constructor is not necessary.

When using with a filename or filehandle, as shown in the Synopsis sections, above, the lock method will return the newly instantiated lock object.

When called from within a PTools::SDF::<module> class, this module is expected to be implemented as a extendible method. See the abstract base class PTools::SDF::File for further details.

Public Methods

lock ( FileParam [, MaxRetries [, SleepTime ]] [, LockMode ] [, OpenMode ] )
lock ( SDFReference [, MaxRetries [, SleepTime ]] [, LockMode ] [, OpenMode ] )

Use the first format when this class is used 'standalone' to lock a filepath or filehandle.

Use the second format of the lock method from within the various SDF::<module> classes to lock the file associated with that object.

(For information on how to obtain a lock on an instantiated PTools::SDF::<module> object, see the documentation accompanying that class.)

FileParam
SDFReference

The first parameter to this method must be either:

1) one of a filename, a filepath or a filehandle to an open file

2) a reference to an PTools::SDF::<module>

MaxRetries

An integer indicating the number of times that this class should attempt to obtain the lock.

SleepTime

An integer indicating the number of seconds this class should 'sleep' between retries. The default SleepTime, when a MaxRetries parameter is specified, is 1 second.

LockMode

Files can be locked using a LockMode of either 'read' or 'write'.

A 'read' lock allows multiple 'read' locks but no 'write' locks. Only one 'write' lock may be held at a time, and this disallows any concurrent 'read' locks.

OpenMode

An octal number that will be used for the 'open mode' of a FileParam of either filename or filepath. Obviously this is not used when the FileParam parameter passed is a currently open filehandle.

Examples of locking a filename or filehandle:

($stat,$err) = $lockObj->lock( "myFile" );

($stat,$err) = $lockObj->lock( "/some/path/to/myFile" );

($stat,$err) = $lockObj->lock( $fh );

See the Synopsis examples, above, for a full example of obtaining and passing an open filehandle.

An Example of invoking a lock from within an PTools::SDF::<module> class can be found in the abstract base class PTools::SDF::File.

unlock ( [ FH ] )
unlock ( SDFReference [, FH ]] )

Use the first format when using this class 'standalone' to unlock an open filehandle.

The second format of the unlock method is used by the various PTools::SDF::<module> classes to unlock the file associated with that object.

In either case the FH parameter is optional. The filehandle used to release the lock is expected to be maintained within the various objects involved. Module designers should make a note of this.

FH

The same filehandle used to obtain the lock in the lock method.

SDFReference

The same parameter used to obtain the lock in the lock method.

Examples:

($stat,$err) = $lockObj->unlock;

($stat,$err) = $lockObj->unlock( $fileHandle );
status

Obtain the status and, when non-zero, the accompanying error message.

($stat,$err) = $lockObj->status;

Module designers should note that the PTools::SDF::<module> objects should make any error status and message available from within the calling objects, too.

isLocked
notLocked
$boolean = $lockObj->isLocked;

$boolean = $lockObj->notLocked;

Private Methods

setErr ( [ Status ] [, Error ] )

Used to set an internal error state when problems are detected during method calls.

$self->setErr( 0, "" );               # initialize to "no error" state

$self->setErr( -1, "Error text" );    # set to an "error" state
_createFileHandle ( FileParam [, Mode ] )

Ensure the FileParam passed to the lock method is a FileHandle. If not, create one based on the FileParam.

_lockFileHandle ( FH [, Retry [, Sleep ]] )

Attempt to obtain a read or write lock on a FileHandle.

INHERITANCE

This class inherits directly from the PTools::SDF::Lock::Advisory class.

SEE ALSO

See PTools::SDF::Overview, PTools::SDF::ARRAY, PTools::SDF::CMD::BDF PTools::SDF::CSV, PTools::SDF::DB, PTools::SDF::DIR, PTools::SDF::DSET, PTools::SDF::File, PTools::SDF::IDX, PTools::SDF::INI, PTools::SDF::SDF, PTools::SDF::TAG, PTools::SDF::Lock::Advisory, PTools::SDF::Sort::Bubble, PTools::SDF::Sort::Quick and PTools::SDF::Sort::Shell.

Also see PTools::SDF::File::AutoHome, PTools::SDF::File::AutoView, PTools::SDF::File::Mnttab and PTools::SDF::File::Passwd. These are contained in the 'PTools-File-Cmd' distribution available on CPAN

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 2003-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.