casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes
casa::LockFile Class Reference

Class to handle file locking and synchronization. More...

#include <LockFile.h>

List of all members.

Public Member Functions

 LockFile (const String &fileName, double inspectInterval=0, Bool create=False, Bool addToRequestList=True, Bool mustExist=True, uInt seqnr=0, Bool permLocking=False)
 Create or open the lock file with the given name.
 ~LockFile ()
 The destructor does not delete the file, because it is not known when the last process using the lock file will stop.
Bool isMultiUsed ()
 Is the file associated with the LockFile object in use in another process?
Bool acquire (FileLocker::LockType=FileLocker::Write, uInt nattempts=0)
 Acquire a read or write lock.
Bool acquire (MemoryIO &info, FileLocker::LockType=FileLocker::Write, uInt nattempts=0)
Bool acquire (MemoryIO *info, FileLocker::LockType type, uInt nattempts)
Bool release ()
 Release a lock and write the information (if given) into the lock file.
Bool release (const MemoryIO &info)
Bool release (const MemoryIO *info)
Bool inspect (Bool always=False)
 Inspect if another process wants to access the file (i.e.
Bool canLock (FileLocker::LockType=FileLocker::Write)
 Test if the file can be locked for read or write.
Bool hasLock (FileLocker::LockType=FileLocker::Write) const
 Test if the process has a lock for read or write on the file.
int lastError () const
 Get the last error.
String lastMessage () const
 Get the message belonging to the last error.
const Stringname () const
 Get the name of the lock file.
const Block< Int > & reqIds () const
 Get the block of request id's.
void getInfo (MemoryIO &info)
 Get the request id's and the info from the lock file.
void putInfo (const MemoryIO &info) const
 Put the info into the file (after the request id's).

Static Public Member Functions

static uInt showLock (uInt &pid, Bool &permLocked, const String &fileName)
 Tell if another process holds a read or write lock on the given file or has the file opened.

Private Member Functions

 LockFile (const LockFile &)
 The copy constructor cannot be used (its semantics are too difficult).
LockFileoperator= (const LockFile &)
 Assignment cannot be used (its semantics are too difficult).
Int getInt (const uChar *buffer, uInt leng, uInt offset) const
 Get an Int from the buffer at the given offset and convert it from canonical to local format.
void addReqId ()
 Add the request id of this process to the list.
void removeReqId ()
 Remove the request id of this process from the list (and all the ones before it).
void getReqId ()
 Get the request list from the file.
void putReqId (int fd) const
 Put the request list into the file.
void convReqId (const uChar *buffer, uInt leng)
 Convert the request id from canonical to local format.
Int getNrReqId () const
 Get the number of request id's.

Private Attributes

FileLocker itsLocker
FileLocker itsUseLocker
FiledesIOitsFileIO
CanonicalIOitsCanIO
Bool itsWritable
Bool itsAddToList
double itsInterval
Time itsLastTime
String itsName
uInt itsPid
uInt itsHostId
Block< IntitsReqId
Int itsInspectCount

Detailed Description

Class to handle file locking and synchronization.

Intended use:

Public interface

Review Status

Reviewed By:
UNKNOWN
Date Reviewed:
before2004/08/25
Test programs:
tLockFile

Prerequisite

Synopsis

This class handles file locking by means of a special lock file which serves as the locking mechanism for another file or group of files. It is for instance used to lock a table in the AIPS++ table system.

The lock file has in principle world read/write access, so every process accessing the main file can write information in it. The lock file contains the following information (in canonical format):

Acquiring a lock works as follows:

Releasing a lock writes the synchronization info into the lock file and tells FileLocker to release the lock.

When the lock file cannot be opened as read/write, it is opened as readonly. It means that the request list cannot be stored in it, so the process has no way to tell the other processes it wants access to the file. It has to wait until the lock is released.
In principle a lock file should always be there. However, it is possible (with a constructor option) that there is no lock file. In that case each lock request succeeds without doing actual locking. This mode is needed to be able to handle readonly tables containing no lock file.

After each write the fsync function is called to make sure that the contents of the file are written to disk. This is necessary for correct file synchronization in NFS. However, at the moment this feature is switched off, because it degraded performance severely.

Apart from the read/write lock handling, the LockFile also contains a mechanism to detect if a file is opened by another process. This can be used to test if a process can safely delete the file. For this purpose it sets another read lock when the file gets opened. The function isMultiUsed tests this lock to see if the file is used in other processes.
This lock is also used to tell if the file is permanently locked. If that is the case, the locked block is 2 bytes instead of 1.

When in the same process multiple LockFile objects are created for the same file, deleting one object releases all locks on the file, thus also the locks held by the other LockFile objects. This behaviour is due to the way file locking is working on UNIX machines (certainly on Solaris 2.6). One can use the test program tLockFile to test for this behaviour.

Example

    // Create/open the lock file (with 1 sec inspection interval).
    // Acquire the lock and get the synchronization info.
    LockFile lock ("file.name", 1);
    MemoryIO syncInfo;
    if (! lock.acquire (syncInfo)) {
        throw (AipsError ("Locking failed: " + lock.message()));
    }
    while (...) {
         ... do something with the table files ..\.
         // Test if another process needs the files.
         // If so, synchronize files and release lock.
         if (lock.inspect()) {
            do fsync for all other files
            syncInfo.seek (0);
            syncInfo.write (...);
            lock.release (syncInfo);
            // At this point another process can grab the lock.
            // Reacquire the lock
            lock.acquire (syncInfo);
                throw (AipsError ("Locking failed: " + lock.message()));
            }
        }
    }

Motivation

Make it possible to lock and synchronize tables in an easy and efficient way.

Definition at line 171 of file LockFile.h.


Constructor & Destructor Documentation

casa::LockFile::LockFile ( const String fileName,
double  inspectInterval = 0,
Bool  create = False,
Bool  addToRequestList = True,
Bool  mustExist = True,
uInt  seqnr = 0,
Bool  permLocking = False 
) [explicit]

Create or open the lock file with the given name.

It is created if create=True or if the file does not exist yet. The interval (in seconds) defines how often function inspect inspects the request list in the lock file. An interval>0 means that it is only inspected if the last inspect was at least inspectInterval seconds ago. An interval<=0 means that inspect always inspects the request list.
When addToRequestList=False, function acquire does not add the request to the lock file when a lock cannot be acquired. This may result in better performance, but should be used with care.
If create==True, a new lock file will always be created. Otherwise it will be created if it does not exist yet.
If mustExist==False, it is allowed that the LockFile does not exist and cannot be created either.
The seqnr is used to set the offset where LockFile will use 2 bytes to set the locks on. Only in special cases it should be other than 0. At the moment the offset is 2*seqnr.
The permLocking argument is used to indicate if permanent locking will be used. If so, it'll indicate so. In that way showLock() can find out if if table is permanently locked.

The destructor does not delete the file, because it is not known when the last process using the lock file will stop.

For the table system this is no problem, because the lock file is contained in the directory of the table, thus deleted when the table gets deleted.

casa::LockFile::LockFile ( const LockFile ) [private]

The copy constructor cannot be used (its semantics are too difficult).


Member Function Documentation

Bool casa::LockFile::acquire ( FileLocker::LockType  type = FileLocker::Write,
uInt  nattempts = 0 
) [inline]

Acquire a read or write lock.

It reads the information (if the info argument is given) from the lock file. The user is responsible for interpreting the information (e.g. converting from canonical to local format). The seek pointer in the MemoryIO object is set to 0, so the user can simply start reading the pointer.
The argument nattempts tells how often it is attempted (with 1 second intervals) to acquire the lock if it does not succeed. 0 means forever, while 1 means do not retry.

Definition at line 337 of file LockFile.h.

Referenced by acquire().

Bool casa::LockFile::acquire ( MemoryIO info,
FileLocker::LockType  type = FileLocker::Write,
uInt  nattempts = 0 
) [inline]

Definition at line 341 of file LockFile.h.

References acquire().

Bool casa::LockFile::acquire ( MemoryIO info,
FileLocker::LockType  type,
uInt  nattempts 
)
void casa::LockFile::addReqId ( ) [private]

Add the request id of this process to the list.

Test if the file can be locked for read or write.

Definition at line 354 of file LockFile.h.

References casa::FileLocker::canLock(), itsFileIO, itsLocker, and casa::True.

void casa::LockFile::convReqId ( const uChar buffer,
uInt  leng 
) [private]

Convert the request id from canonical to local format.

Get the request id's and the info from the lock file.

Referenced by casa::TableLockData::getInfo().

Int casa::LockFile::getInt ( const uChar buffer,
uInt  leng,
uInt  offset 
) const [private]

Get an Int from the buffer at the given offset and convert it from canonical to local format.

If the buffer is too short (i.e. does not contain the value), a zero value is returned.

Int casa::LockFile::getNrReqId ( ) const [private]

Get the number of request id's.

void casa::LockFile::getReqId ( ) [private]

Get the request list from the file.

Test if the process has a lock for read or write on the file.

Definition at line 358 of file LockFile.h.

References casa::False, casa::FileLocker::hasLock(), itsFileIO, and itsLocker.

Referenced by casa::TableLockData::hasLock().

Inspect if another process wants to access the file (i.e.

if the request list is not empty). It only inspects if the time passed since the last inspection exceeds the inspection interval as given in the constructor. If the time passed is too short, False is returned (indicating that no access is needed). If always==True, no test on inspection interval is done, so the inspect is always done.

Referenced by casa::TableLockData::autoRelease().

Is the file associated with the LockFile object in use in another process?

Referenced by casa::TableLockData::isMultiUsed().

int casa::LockFile::lastError ( ) const [inline]

Get the last error.

Definition at line 362 of file LockFile.h.

References itsLocker, and casa::FileLocker::lastError().

String casa::LockFile::lastMessage ( ) const [inline]

Get the message belonging to the last error.

Definition at line 366 of file LockFile.h.

References itsLocker, and casa::FileLocker::lastMessage().

const String & casa::LockFile::name ( ) const [inline]

Get the name of the lock file.

Definition at line 370 of file LockFile.h.

References itsName.

LockFile& casa::LockFile::operator= ( const LockFile ) [private]

Assignment cannot be used (its semantics are too difficult).

void casa::LockFile::putInfo ( const MemoryIO info) const

Put the info into the file (after the request id's).

Referenced by casa::TableLockData::putInfo().

void casa::LockFile::putReqId ( int  fd) const [private]

Put the request list into the file.

Release a lock and write the information (if given) into the lock file.

The user is responsible for making the information machine-independent (e.g. converting from local to canonical format).

Definition at line 346 of file LockFile.h.

Referenced by release().

Bool casa::LockFile::release ( const MemoryIO info) [inline]

Definition at line 350 of file LockFile.h.

References release().

void casa::LockFile::removeReqId ( ) [private]

Remove the request id of this process from the list (and all the ones before it).

const Block< Int > & casa::LockFile::reqIds ( ) const [inline]

Get the block of request id's.

Definition at line 374 of file LockFile.h.

References itsReqId.

static uInt casa::LockFile::showLock ( uInt pid,
Bool permLocked,
const String fileName 
) [static]

Tell if another process holds a read or write lock on the given file or has the file opened.

It returns:
3 if write-locked elsewhere.
2 if read-locked elsewhere.
1 if opened elsewhere.
0 if locked nor opened.
It fills in the PID of the process having the file locked or opened.
If locked, it also tells if it is permanently locked.
An exception is thrown if the file does not exist or cannot be opened.


Member Data Documentation

Definition at line 322 of file LockFile.h.

Definition at line 320 of file LockFile.h.

Definition at line 319 of file LockFile.h.

Referenced by canLock(), and hasLock().

Definition at line 327 of file LockFile.h.

Definition at line 331 of file LockFile.h.

double casa::LockFile::itsInterval [private]

Definition at line 323 of file LockFile.h.

Definition at line 324 of file LockFile.h.

Definition at line 317 of file LockFile.h.

Referenced by canLock(), hasLock(), lastError(), and lastMessage().

Definition at line 325 of file LockFile.h.

Referenced by name().

Definition at line 326 of file LockFile.h.

Definition at line 328 of file LockFile.h.

Referenced by reqIds().

Definition at line 318 of file LockFile.h.

Definition at line 321 of file LockFile.h.


The documentation for this class was generated from the following file: