casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::LockFile Class Reference

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

#include <LockFile.h>

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, Bool noLocking=False)
 Create or open the lock file with the given name. More...
 
 ~LockFile ()
 The destructor does not delete the file, because it is not known when the last process using the lock file will stop. More...
 
Bool isMultiUsed ()
 Is the file associated with the LockFile object in use in another process? More...
 
Bool acquire (FileLocker::LockType=FileLocker::Write, uInt nattempts=0)
 Acquire a read or write lock. More...
 
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. More...
 
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. More...
 
Bool canLock (FileLocker::LockType=FileLocker::Write)
 Test if the file can be locked for read or write. More...
 
Bool hasLock (FileLocker::LockType=FileLocker::Write) const
 Test if the process has a lock for read or write on the file. More...
 
int lastError () const
 Get the last error. More...
 
String lastMessage () const
 Get the message belonging to the last error. More...
 
const Stringname () const
 Get the name of the lock file. More...
 
const Block< Int > & reqIds () const
 Get the block of request id's. More...
 
void getInfo (MemoryIO &info)
 Get the request id's and the info from the lock file. More...
 
void putInfo (const MemoryIO &info) const
 Put the info into the file (after the request id's). More...
 

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. More...
 

Private Member Functions

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

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 Casacore 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

casacore::LockFile::LockFile ( const String fileName,
double  inspectInterval = 0,
Bool  create = False,
Bool  addToRequestList = True,
Bool  mustExist = True,
uInt  seqnr = 0,
Bool  permLocking = False,
Bool  noLocking = 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 noLocking argument is used to indicate that no locking is needed. It means that acquiring a lock always succeeds.

casacore::LockFile::~LockFile ( )

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.

casacore::LockFile::LockFile ( const LockFile )
private

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

Member Function Documentation

Bool casacore::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 339 of file LockFile.h.

Referenced by acquire().

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

Definition at line 343 of file LockFile.h.

References acquire().

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

Add the request id of this process to the list.

Bool casacore::LockFile::canLock ( FileLocker::LockType  type = FileLocker::Write)
inline

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

Definition at line 356 of file LockFile.h.

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

void casacore::LockFile::convReqId ( const uChar buffer,
uInt  leng 
)
private

Convert the request id from canonical to local format.

void casacore::LockFile::getInfo ( MemoryIO info)

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

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

Int casacore::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 casacore::LockFile::getNrReqId ( ) const
private

Get the number of request id's.

void casacore::LockFile::getReqId ( )
private

Get the request list from the file.

Bool casacore::LockFile::hasLock ( FileLocker::LockType  type = FileLocker::Write) const
inline

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

Definition at line 360 of file LockFile.h.

References casacore::FileLocker::hasLock(), itsFileIO, itsLocker, and casacore::True.

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

Bool casacore::LockFile::inspect ( Bool  always = False)

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 casacore::TableLockData::autoRelease().

Bool casacore::LockFile::isMultiUsed ( )

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

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

int casacore::LockFile::lastError ( ) const
inline

Get the last error.

Definition at line 364 of file LockFile.h.

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

String casacore::LockFile::lastMessage ( ) const
inline

Get the message belonging to the last error.

Definition at line 368 of file LockFile.h.

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

const String & casacore::LockFile::name ( ) const
inline

Get the name of the lock file.

Definition at line 372 of file LockFile.h.

References itsName.

LockFile& casacore::LockFile::operator= ( const LockFile )
private

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

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

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

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

void casacore::LockFile::putReqId ( int  fd) const
private

Put the request list into the file.

Bool casacore::LockFile::release ( )
inline

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 348 of file LockFile.h.

Referenced by release().

Bool casacore::LockFile::release ( const MemoryIO info)
inline

Definition at line 352 of file LockFile.h.

References release().

Bool casacore::LockFile::release ( const MemoryIO info)
void casacore::LockFile::removeReqId ( )
private

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

const Block< Int > & casacore::LockFile::reqIds ( ) const
inline

Get the block of request id's.

Definition at line 376 of file LockFile.h.

References itsReqId.

static uInt casacore::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

Bool casacore::LockFile::itsAddToList
private

Definition at line 324 of file LockFile.h.

CanonicalIO* casacore::LockFile::itsCanIO
private

Definition at line 322 of file LockFile.h.

FiledesIO* casacore::LockFile::itsFileIO
private

Definition at line 321 of file LockFile.h.

Referenced by canLock(), and hasLock().

uInt casacore::LockFile::itsHostId
private

Definition at line 329 of file LockFile.h.

Int casacore::LockFile::itsInspectCount
private

Definition at line 333 of file LockFile.h.

double casacore::LockFile::itsInterval
private

Definition at line 325 of file LockFile.h.

Time casacore::LockFile::itsLastTime
private

Definition at line 326 of file LockFile.h.

FileLocker casacore::LockFile::itsLocker
private

Definition at line 319 of file LockFile.h.

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

String casacore::LockFile::itsName
private

Definition at line 327 of file LockFile.h.

Referenced by name().

uInt casacore::LockFile::itsPid
private

Definition at line 328 of file LockFile.h.

Block<Int> casacore::LockFile::itsReqId
private

Definition at line 330 of file LockFile.h.

Referenced by reqIds().

FileLocker casacore::LockFile::itsUseLocker
private

Definition at line 320 of file LockFile.h.

Bool casacore::LockFile::itsWritable
private

Definition at line 323 of file LockFile.h.


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