=head1 NAME

Cpanel::CacheFile::FileLocker - Lock and unlock files using C<flock>.


=head1 VERSION

This document describes Cpanel::CacheFile::FileLocker version 0.307


=head1 SYNOPSIS

    use Cpanel::CacheFile::FileLocker;

=head1 DESCRIPTION

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

=head1 INTERFACE 

=over 4

=item Cpanel::CacheFile::FileLocker->new()

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

=over 4

=item attempts

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

=item max_wait

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

=item max_age

Maximum number of seconds that a lock file can remain on disk. If a C<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 I<max_wait> value. The default value is
300 (5 minutes).

=item flock_timeout

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

=item 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.

=back

=item $locker->file_lock( $filename )

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

=item $locker->file_unlock( $lock )

Unlock the file associated with the $lock.

=back

=head1 DIAGNOSTICS

=over

=item C<< Argument to new must be a hash reference. >>

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

=item C<< 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.

=item C<< 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.

=item C<< Cannot open lock file '%s' for reading. >>

The lock file is not readable.

=item C<< 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.

=item C<< 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:

=over 4

=item 1.

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

=item 2.

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

=back

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

=item C<< Invalid lock file: '%s' is not a PID. >>

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

=item C<< Lockfile '%s' lost! >>

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

=item C<< Missing lockfile name. >>

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

=item C<< 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.

=item C<< Removing abandoned lock file. >>

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

=item C<< 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. C<FileLocker> is resolving this case by removing the
lock and continuing.

=item C<< Timeout reading lockfile '%s'. >>

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

=item C<< 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 C<flock>s the file we just opened and
leaves it C<flock>ed.

=item C<< 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 C<FileLocker> will try again.

=item C<< Unable to read lockfile '%s' >>

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

=item C<< Zero-length lockfile deleted. >>

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

=back


=head1 CONFIGURATION AND ENVIRONMENT

Cpanel::CacheFile::FileLocker requires no configuration files or environment variables.


=head1 DEPENDENCIES

None.


=head1 INCOMPATIBILITIES

None reported.


=head1 BUGS AND LIMITATIONS

No bugs have been reported.

=head1 AUTHOR

G. Wade Johnson  C<< wade@cpanel.net >>


=head1 LICENCE AND COPYRIGHT

Copyright (c) 2009, 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 L<perlartistic>.


=head1 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.