Arc::FileLock Class Reference

A general file locking class. More...

#include <arc/FileLock.h>

Public Member Functions
	FileLock (const std::string &filename, unsigned int timeout=DEFAULT_LOCK_TIMEOUT, bool use_pid=true)
	Create a new FileLock object. More...
bool	acquire (bool &lock_removed)
	Acquire the lock. More...
bool	acquire ()
	Acquire the lock. More...
bool	release (bool force=false)
	Release the lock. More...
int	check (bool log_error=true)
	Check the lock is valid. More...

Static Public Member Functions
static std::string	getLockSuffix ()
	Get the lock suffix used. More...

Static Public Attributes
static const int	DEFAULT_LOCK_TIMEOUT
	Default timeout for a lock. More...
static const std::string	LOCK_SUFFIX
	Suffix added to file name to make lock file. More...

Detailed Description

A general file locking class.

This class can be used when protected access is required to files which are used by multiple processes or threads. Call acquire() to obtain a lock and release() to release it when finished. check() can be used to verify if a lock is valid for the current process. Locks are independent of FileLock objects - locks are only created and destroyed through acquire() and release(), not on creation or destruction of FileLock objects.

Unless use_pid is set false, the process ID and hostname of the calling process are stored in a file filename.lock in the form pid@hostname. This information is used to determine whether a lock is still valid. It is also possible to specify a timeout on the lock.

To ensure an atomic locking operation, acquire() first creates a temporary lock file filename.lock.XXXXXX, then attempts to rename this file to filename.lock. After a successful rename the lock file is checked to make sure the correct process ID and hostname are inside. This eliminates race conditions where multiple processes compete to obtain the lock.

Constructor & Destructor Documentation

FileLock()

Arc::FileLock::FileLock	(	const std::string &	filename,
		unsigned int	timeout = DEFAULT_LOCK_TIMEOUT,
		bool	use_pid = true
	)

Create a new FileLock object.

Parameters

filename	The name of the file to be locked
timeout	The timeout of the lock
use_pid	If true, use process id in the lock and to determine lock validity

Member Function Documentation

acquire() [1/2]

bool Arc::FileLock::acquire

(

bool &

lock_removed

)

Acquire the lock.

Returns true if the lock was acquired successfully. Locks are acquired if no lock file currently exists, or if the current lock file is invalid. A lock is invalid if the process ID inside the lock no longer exists on the host inside the lock, or the age of the lock file is greater than the lock timeout.

Parameters

lock_removed

Set to true if an existing lock was removed due to being invalid. In this case the caller may decide to check or delete the file as it is potentially corrupted.

Returns

True if lock is successfully acquired

acquire() [2/2]

bool Arc::FileLock::acquire

(

)

Acquire the lock.

Callers can use this version of acquire() if they do not care whether an invalid lock was removed in the process of obtaining the lock.

Returns

True if lock is successfully acquired

check()

int Arc::FileLock::check

(

bool

log_error = true

)

Check the lock is valid.

Parameters

log_error

may be set to false to log error messages at INFO level, in cases where the lock not existing or being owned by another host are not errors.

Returns

0 if the lock is valid for the current process, the pid inside the lock if the lock is owned by another process on the same host, or -1 if the lock is owned by another host or any other error occurred.

getLockSuffix()

static std::string Arc::FileLock::getLockSuffix ( )

static

Get the lock suffix used.

release()

bool Arc::FileLock::release

(

bool

force = false

)

Release the lock.

Parameters

force

Remove the lock without checking ownership or timeout

Returns

True if lock is successfully released

Field Documentation

DEFAULT_LOCK_TIMEOUT

const int Arc::FileLock::DEFAULT_LOCK_TIMEOUT

static

Default timeout for a lock.

LOCK_SUFFIX

const std::string Arc::FileLock::LOCK_SUFFIX

static

Suffix added to file name to make lock file.

---

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

• FileLock.h