NAME

cPanel::StateFile::FileLocker - Lock and unlock files using flock.

VERSION

This document describes cPanel::StateFile::FileLocker version 0.700

SYNOPSIS

use cPanel::StateFile::FileLocker;

DESCRIPTION

Provide the ability to lock and unlock a file. This class uses the flock system call to lock the file.

INTERFACE

cPanel::StateFile::FileLocker->new()

Create a new FileLocker object. The constructor takes an optional hash reference that can be used to customize the behavior of the FileLocker.

attempts

The maximum number of times to try to create a lock file. This defaults to 5.

max_wait

Maximum number of seconds to wait for a lock file to be unlocked. The default value is 300 (5 minutes).

max_age

Maximum number of seconds that a lock file can remain on disk. If a FileLocker finds a lock file older than this, it is assumed to be stale and is removed. This value should be no less than the max_wait value. The default value is 300 (5 minutes).

flock_timeout

Maximum number of seconds to wait for the flock call to complete. This time should be significantly less than the max_wait value. The default value is 60 (1 minute).

sleep_secs

The number of seconds to sleep between attempts to check the lock file. Higher numbers reduce CPU and disk load, but reduce responsiveness. The default value is the lowest allowed, 1.

$locker->file_lock( $filename )

Lock the file named $filename and return a lock object to be used to unlock the file later.

$locker->file_unlock( $lock )

Unlock the file associated with the $lock.

DIAGNOSTICS

Argument to new must be a hash reference.

The constructor was called with an argument that is not a hash reference.

Attempt to unlock file '%s' locked by another process '%s'.

You attempted to unlock a file locked by someone else. There is no legitimate reason to do this, so it must be a program error.

Attempting to relock '%s'.

According to the lockfile, the current program already attempted to lock this file, so the attempt to lock is terminated. This is likely caused by a programming error trying to lock and already-locked file.

Cannot open lock file '%s' for reading.

The lock file is not readable.

Failed to acquire lock for '%s'.

We ran out of time before being able to acquire the lock. This is probably caused by one or more other processes holding the lock for longer than we were willing to wait.

Inconsistent lock: my PID but process named '%s': removing lock

This warning describes a rare circumstance where the file was locked by a another process with the same PID as the current program. There are two ways this could occur:

1. A previous program locked the file and then terminated without locking. We happen to have the same PID as that program.

2. This program locked the file and then changed it's name.

The lock is removed because in either case, we are waiting for a lock that will never be released.

Invalid lock file: '%s' is not a PID.

The lockfile does not have the expected contents. Are you sure a lockfile name was supplied?

Lockfile '%s' lost!

The lockfile name supplied to file_unlock refers to a non-existent file. Either someone deleted your lockfile, or the name you supplied is not valid.

Missing lockfile name.

The file_unlock method was called without the name of the lockfile to unlock.

Old, but empty lock file deleted.

Informational message that the lock file is empty, but older than the maximum age expected. The file is discarded and we will try again.

Removing abandoned lock file.

The program associated with this lock file is no longer running. The lockfile is being removed.

Stale lock file '%s': lock expired %s seconds ago, removing...

Informational message stating that the lock file was older than the locking program expected. This probably means that either the locking program terminated unexpectedly or is hung. FileLocker is resolving this case by removing the lock and continuing.

Timeout reading lockfile '%s'.

When attempting to read the lock file, the file was flocked for more than flock_timeout seconds. This can be caused by another process access the file and crashing.

Timeout writing lockfile '%s'.

Although we were able to open the lockfile, we failed to lock it. This should not happen in normal use unless someone flocks the file we just opened and leaves it flocked.

Unable to create the lockfile, waiting

Informational message stating that this attempt to create a lock file was not successful. After a short pause, the FileLocker will try again.

Unable to read lockfile '%s'

We failed to read the lock file, so the attempt to lock has been abandonded.

Zero-length lockfile deleted.

The lockfile name supplied to file_unlock refers to an empty file. Either someone deleted your lockfile, or the name you supplied is not valid.

CONFIGURATION AND ENVIRONMENT

cPanel::StateFile::FileLocker requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

G. Wade Johnson wade@cpanel.net

LICENCE AND COPYRIGHT

Copyright (c) 2014, cPanel, Inc. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.