SDF::Lock::Advisory - Lock/Unlock a file or filehandle using ADVISORY locking

Obtain lock on a filename or filepath
Obtain lock on an open filehandle
Obtain lock on an instance of an 'SDF::<module>' class
Invoke lock method from within an 'SDF::<module>' class

DESCRIPTION

Constructor
Public Methods
Private Methods

INHERITANCE
SEE ALSO
AUTHOR
COPYRIGHT

NAME

SDF::Lock::Advisory - Lock/Unlock a file or filehandle using ADVISORY locking

VERSION

This document describes version 0.07, released Feb 15, 2003.

SYNOPSIS

Obtain lock on a filename or filepath

     use PTools::SDF::Lock::Advisory;

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

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

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

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

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

The '$lockMode' parameter is valid for the PTools::SDF::Lock::Selective class but is not currently used in this parent class, and is ignored here.

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::Advisory;

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

     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 );

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 );

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

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

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 the PTools::SDF::File manpage or the Extender manpage 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.

WARNING: This module implements simple advisory 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 an advisory 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

The '$lockMode' parameter is valid for the PTools::SDF::Lock::Selective class but is not currently used in this parent class, and is ignored here.

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 advisory 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 advisory lock in the lock method.
SDFReference: The same parameter used to obtain the advisory lock in the lock method.

Examples:

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

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

status

stat

err

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

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

 $stat  = $lockObj->stat;           # scalar context returns status number
 ($err) = $lockObj->stat;           # array context returns error message

 ($err) = $lockObj->err;

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 an advisory lock on a FileHandle.

INHERITANCE

None currently.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

SDF::Lock::Advisory - Lock/Unlock a file or filehandle using ADVISORY locking