.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Cpanel::CacheFile::FileLocker 3"
.TH Cpanel::CacheFile::FileLocker 3 "2011-01-04" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cpanel::CacheFile::FileLocker \- Lock and unlock files using \f(CW\*(C`flock\*(C'\fR.
.SH "VERSION"
.IX Header "VERSION"
This document describes Cpanel::CacheFile::FileLocker version 0.307
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Cpanel::CacheFile::FileLocker;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provide the ability to lock and unlock a file. This class uses the \f(CW\*(C`flock\*(C'\fR
system call to lock the file.
.SH "INTERFACE"
.IX Header "INTERFACE"
.IP "Cpanel::CacheFile::FileLocker\->\fInew()\fR" 4
.IX Item "Cpanel::CacheFile::FileLocker->new()"
Create a new \f(CW\*(C`FileLocker\*(C'\fR object. The constructor takes an optional hash
reference that can be used to customize the behavior of the \f(CW\*(C`FileLocker\*(C'\fR.
.RS 4
.IP "attempts" 4
.IX Item "attempts"
The maximum number of times to try to create a lock file. This defaults to 5.
.IP "max_wait" 4
.IX Item "max_wait"
Maximum number of seconds to wait for a lock file to be unlocked. The default
value is 300 (5 minutes).
.IP "max_age" 4
.IX Item "max_age"
Maximum number of seconds that a lock file can remain on disk. If a \f(CW\*(C`FileLocker\*(C'\fR
finds a lock file older than this, it is assumed to be stale and is removed.
This value should be no less than the \fImax_wait\fR value. The default value is
300 (5 minutes).
.IP "flock_timeout" 4
.IX Item "flock_timeout"
Maximum number of seconds to wait for the \f(CW\*(C`flock\*(C'\fR call to complete. This time
should be significantly less than the \fImax_wait\fR value. The default value is
60 (1 minute).
.IP "sleep_secs" 4
.IX Item "sleep_secs"
The number of seconds to sleep between attempts to check the lock file. Higher
numbers reduce \s-1CPU\s0 and disk load, but reduce responsiveness. The default value
is the lowest allowed, 1.
.RE
.RS 4
.RE
.ie n .IP "$locker\->file_lock( $filename )" 4
.el .IP "$locker\->file_lock( \f(CW$filename\fR )" 4
.IX Item "$locker->file_lock( $filename )"
Lock the file named \f(CW$filename\fR and return a lock object to be used to unlock
the file later.
.ie n .IP "$locker\->file_unlock( $lock )" 4
.el .IP "$locker\->file_unlock( \f(CW$lock\fR )" 4
.IX Item "$locker->file_unlock( $lock )"
Unlock the file associated with the \f(CW$lock\fR.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP """Argument to new must be a hash reference.""" 4
.el .IP "\f(CWArgument to new must be a hash reference.\fR" 4
.IX Item "Argument to new must be a hash reference."
The constructor was called with an argument that is not a hash reference.
.ie n .IP """Attempt to unlock file '%s' locked by another process '%s'.""" 4
.el .IP "\f(CWAttempt to unlock file '%s' locked by another process '%s'.\fR" 4
.IX Item "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.
.ie n .IP """Attempting to relock '%s'.""" 4
.el .IP "\f(CWAttempting to relock '%s'.\fR" 4
.IX Item "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.
.ie n .IP """Cannot open lock file '%s' for reading.""" 4
.el .IP "\f(CWCannot open lock file '%s' for reading.\fR" 4
.IX Item "Cannot open lock file '%s' for reading."
The lock file is not readable.
.ie n .IP """Failed to acquire lock for '%s'.""" 4
.el .IP "\f(CWFailed to acquire lock for '%s'.\fR" 4
.IX Item "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.
.ie n .IP """Inconsistent lock: my PID but process named '%s': removing lock""" 4
.el .IP "\f(CWInconsistent lock: my PID but process named '%s': removing lock\fR" 4
.IX Item "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 \s-1PID\s0 as the current program. There are two
ways this could occur:
.RS 4
.IP "1." 4
A previous program locked the file and then terminated without locking. We
happen to have the same \s-1PID\s0 as that program.
.IP "2." 4
This program locked the file and then changed it's name.
.RE
.RS 4
.Sp
The lock is removed because in either case, we are waiting for a lock that
will never be released.
.RE
.ie n .IP """Invalid lock file: '%s' is not a PID.""" 4
.el .IP "\f(CWInvalid lock file: '%s' is not a PID.\fR" 4
.IX Item "Invalid lock file: '%s' is not a PID."
The lockfile does not have the expected contents. Are you sure a lockfile
name was supplied?
.ie n .IP """Lockfile '%s' lost!""" 4
.el .IP "\f(CWLockfile '%s' lost!\fR" 4
.IX Item "Lockfile '%s' lost!"
The lockfile name supplied to \f(CW\*(C`file_unlock\*(C'\fR refers to a non-existent file.
Either someone deleted your lockfile, or the name you supplied is not valid.
.ie n .IP """Missing lockfile name.""" 4
.el .IP "\f(CWMissing lockfile name.\fR" 4
.IX Item "Missing lockfile name."
The \f(CW\*(C`file_unlock\*(C'\fR method was called without the name of the lockfile to
unlock.
.ie n .IP """Old, but empty lock file deleted.""" 4
.el .IP "\f(CWOld, but empty lock file deleted.\fR" 4
.IX Item "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.
.ie n .IP """Removing abandoned lock file.""" 4
.el .IP "\f(CWRemoving abandoned lock file.\fR" 4
.IX Item "Removing abandoned lock file."
The program associated with this lock file is no longer running. The lockfile
is being removed.
.ie n .IP """Stale lock file '%s': lock expired %s seconds ago, removing...""" 4
.el .IP "\f(CWStale lock file '%s': lock expired %s seconds ago, removing...\fR" 4
.IX Item "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. \f(CW\*(C`FileLocker\*(C'\fR is resolving this case by removing the
lock and continuing.
.ie n .IP """Timeout reading lockfile '%s'.""" 4
.el .IP "\f(CWTimeout reading lockfile '%s'.\fR" 4
.IX Item "Timeout reading lockfile '%s'."
When attempting to read the lock file, the file was \f(CW\*(C`flock\*(C'\fRed for more than
\&\f(CW\*(C`flock_timeout\*(C'\fR seconds. This can be caused by another process access the
file and crashing.
.ie n .IP """Timeout writing lockfile '%s'.""" 4
.el .IP "\f(CWTimeout writing lockfile '%s'.\fR" 4
.IX Item "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 \f(CW\*(C`flock\*(C'\fRs the file we just opened and
leaves it \f(CW\*(C`flock\*(C'\fRed.
.ie n .IP """Unable to create the lockfile, waiting""" 4
.el .IP "\f(CWUnable to create the lockfile, waiting\fR" 4
.IX Item "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 \f(CW\*(C`FileLocker\*(C'\fR will try again.
.ie n .IP """Unable to read lockfile '%s'""" 4
.el .IP "\f(CWUnable to read lockfile '%s'\fR" 4
.IX Item "Unable to read lockfile '%s'"
We failed to read the lock file, so the attempt to lock has been abandonded.
.ie n .IP """Zero\-length lockfile deleted.""" 4
.el .IP "\f(CWZero\-length lockfile deleted.\fR" 4
.IX Item "Zero-length lockfile deleted."
The lockfile name supplied to \f(CW\*(C`file_unlock\*(C'\fR refers to an empty file.
Either someone deleted your lockfile, or the name you supplied is not valid.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Cpanel::CacheFile::FileLocker requires no configuration files or environment variables.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
None.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
None reported.
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
G. Wade Johnson  \f(CW\*(C`wade@cpanel.net\*(C'\fR
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2009, cPanel, Inc. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENCE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.