cPanel::StateFile::FileLocker - Lock and unlock files using flock.
flock
This document describes cPanel::StateFile::FileLocker version 0.604
use cPanel::StateFile::FileLocker;
Provide the ability to lock and unlock a file. This class uses the flock system call to lock the file.
Create a new FileLocker object. The constructor takes an optional hash reference that can be used to customize the behavior of the FileLocker.
FileLocker
The maximum number of times to try to create a lock file. This defaults to 5.
Maximum number of seconds to wait for a lock file to be unlocked. The default value is 300 (5 minutes).
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).
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).
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.
Lock the file named $filename and return a lock object to be used to unlock the file later.
Unlock the file associated with the $lock.
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:
A previous program locked the file and then terminated without locking. We happen to have the same PID as that program.
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.
file_unlock
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.
flock_timeout
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.
cPanel::StateFile::FileLocker requires no configuration files or environment variables.
None.
None reported.
No bugs have been reported.
G. Wade Johnson wade@cpanel.net
wade@cpanel.net
Copyright (c) 2012, 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.
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.
To install cPanel::TaskQueue, copy and paste the appropriate command in to your terminal.
cpanm
cpanm cPanel::TaskQueue
CPAN shell
perl -MCPAN -e shell install cPanel::TaskQueue
For more information on module installation, please visit the detailed CPAN module installation guide.