KVLockfile Class Reference

Detailed Description

Interface to (Linux) system lockfile command.

Created by KVClassFactory on Wed Feb 6 12:39:42 2008 Author: franklan

lockfile can be used to create one or more semaphore files, used to make sure that only one process can write to a given file at any one time.

If lockfile can't create all the specified files (in the specified order), because another process has already 'locked' the file, it waits sleeptime (defaults to 8) seconds and retries the last file that didn't succeed.

You can specify the number of retries to do until failure is returned. If the number of retries is -1 (default) lockfile will retry forever.

If the number of retries expires before all files have been created, lockfile returns failure and removes all the files it created up till that point.

If you specify a locktimeout then a lockfile will be removed by force after locktimeout seconds have passed since the lockfile was last modified/created (most likely by some other program that unexpectedly died a long time ago, and hence could not clean up any leftover lockfiles).

lockfile is clock skew immune. After a lockfile has been removed by force, a suspension of suspend seconds (defaults to 16) is taken into account, in order to prevent the inadvertent immediate removal of any newly created lockfile by another program (compare SUSPEND in procmail(1)).

To use a lockfile, create a KVLockfile object either using the constructor without arguments or by giving the name of the file to lock:

KVLockfile lox;
KVLockfile lox2("important.dat");

Then set the values you want for the number of retries, the sleeptime etc. Default values are as for Linux 'lockfile':

sleeptime = 8 sec.
retries = -1 (keep trying for ever)
suspend = 16 sec. (in case of timeout)

There is no timeout by default. If you want one, use SetTimeout() with timeout>0 seconds.

To lock the file:

lox.Lock("important.dat"); // filename not given to ctor
lox2.Lock(); // filename given to ctor

To unlock the file:

lox.Release();
lox2.Release();

Note that Release() is called automatically in the destructor in case e.g. the KVLockfile goes out of scope.

Definition at line 70 of file KVLockfile.h.

#include <KVLockfile.h>

Public Member Functions
	KVLockfile (const Char_t *filename="")
	Default constructor.
virtual	~KVLockfile ()
Bool_t	IsLocked () const
Bool_t	Lock (const Char_t *filename="")
Bool_t	Release ()
void	SetRetries (int r)
void	SetSleeptime (int s)
void	SetSuspend (int s)
void	SetTimeout (int t)

Private Member Functions
Bool_t	FindExecutable (TString &exec, const Char_t *path="$(PATH)")
	copied from KVBase to avoid circular dependency
void	init ()
int	testlock ()
void	writecmd ()
	Writes lockfile command with current values of parameters.

Private Attributes
KVString	cmd
	command to execute
KVString	fFile
	name of file
KVString	fLockfile
	full path to lockfile executable (if defined)
bool	have_exec
	kTRUE if lockfile found on system
bool	locked
	kTRUE when Lock() has been called successfully
int	locktimeout
	time after which lock automatically opens
int	retries
	number of times to retry
int	sleeptime
	time to wait before retrying lock
int	suspend
	suspend time after timeout

Constructor & Destructor Documentation

KVLockfile()

KVLockfile::KVLockfile

(

const Char_t *

filename = ""

)

Default constructor.

Definition at line 25 of file KVLockfile.cpp.

~KVLockfile()

KVLockfile::~KVLockfile ( )

virtual

Destructor If file is still locked, we call Release

Definition at line 39 of file KVLockfile.cpp.

Member Function Documentation

FindExecutable()

Bool_t KVLockfile::FindExecutable ( TString &  exec, const Char_t *  path = "$(PATH)"  )

private

copied from KVBase to avoid circular dependency

Definition at line 75 of file KVLockfile.cpp.

init()

void KVLockfile::init ( )

private

Initialisation Look for 'lockfile' executable and store path if found Set value of have_exec accordingly

Definition at line 55 of file KVLockfile.cpp.

IsLocked()

Bool_t KVLockfile::IsLocked ( ) const

inline

Definition at line 110 of file KVLockfile.h.

Lock()

Bool_t KVLockfile::Lock

(

const Char_t *

filename = ""

)

Definition at line 165 of file KVLockfile.cpp.

Release()

Bool_t KVLockfile::Release

(

)

Definition at line 195 of file KVLockfile.cpp.

SetRetries()

void KVLockfile::SetRetries ( int  r )

inline

Definition at line 94 of file KVLockfile.h.

SetSleeptime()

void KVLockfile::SetSleeptime ( int  s )

inline

Definition at line 90 of file KVLockfile.h.

SetSuspend()

void KVLockfile::SetSuspend ( int  s )

inline

Definition at line 102 of file KVLockfile.h.

SetTimeout()

void KVLockfile::SetTimeout ( int  t )

inline

Definition at line 98 of file KVLockfile.h.

testlock()

int KVLockfile::testlock ( )

private

Executes lockfile command with current values of parameters (call KVLockfile::writecmd() before)

Definition at line 152 of file KVLockfile.cpp.

writecmd()

void KVLockfile::writecmd ( )

private

Writes lockfile command with current values of parameters.

Definition at line 122 of file KVLockfile.cpp.

Member Data Documentation

cmd

KVString KVLockfile::cmd

private

command to execute

Definition at line 78 of file KVLockfile.h.

fFile

KVString KVLockfile::fFile

private

name of file

Definition at line 71 of file KVLockfile.h.

fLockfile

KVString KVLockfile::fLockfile

private

full path to lockfile executable (if defined)

Definition at line 72 of file KVLockfile.h.

have_exec

bool KVLockfile::have_exec

private

kTRUE if lockfile found on system

Definition at line 73 of file KVLockfile.h.

locked

bool KVLockfile::locked

private

kTRUE when Lock() has been called successfully

Definition at line 79 of file KVLockfile.h.

locktimeout

int KVLockfile::locktimeout

private

time after which lock automatically opens

Definition at line 76 of file KVLockfile.h.

retries

int KVLockfile::retries

private

number of times to retry

Definition at line 75 of file KVLockfile.h.

sleeptime

int KVLockfile::sleeptime

private

time to wait before retrying lock

Definition at line 74 of file KVLockfile.h.

suspend

int KVLockfile::suspend

private

suspend time after timeout

Definition at line 77 of file KVLockfile.h.