Lazy::Lockfile - File based locking for the lazy.
use Lazy::Lockfile; my $lockfile = Lazy::Lockfile->new() || die "Couldn't get lock!"; ... # Lock is released when $lockfile goes out of scope or your program exits.
Lazy::Lockfile is a module designed for simple locking through the use of lockfiles, requiring very little effort on the part of the developer. Once the object is instanced, the lock will be held as long as object exists. When the object is destroyed, the lock is released.
Locks are based around the existence of a named file, not around the use of flock (though flock is used to synchronize access to the lock file). Lazy::Lockfile is (usually) smart enough to detect stale lockfiles from PIDs no longer running by placing the PID of the process holding the lock inside the lockfile.
Lazy::Lockfile is not safe for use on NFS volumes.
Lazy::Lockfile is not tested to interact correctly with other file locking systems when used on the same lockfile.
Lazy::Lockfile uses kill (with signal zero) to determine if the lockfile is stale. This works on most systems running as most users but there are likely instances where this will fail. If this applies to your system, you can use the no_pid option to disable the check.
If Lazy::Lockfile encounters a malformed lockfile (empty, containing other text, etc), it will treat it as a corrupt file and overwrite it, assuming the lock. The author believes this behavior should be changed (and malformed files should be left untouched), but has kept this behavior for backwards compatibility.
All of the magic in Lazy::Lockfile is done through the constructor and destructor.
Constructor for Lazy::Lockfile.
Accepts a single optional parameter, a hashref containing the following options:
Specifies the full path to the location of the lockfile. Defaults to:
'/tmp/' . (fileparse($0))[0] . '.pid'
i.e., the name of the program being run, with a ".pid" extension, in /tmp/.
If true, instead of writing the PID file, a value of "0" is written instead. When read by another instance of Lazy::Lockfile attempting to acquire the lock, no PID check will be performed and the lock will be assumed to be active as long as the file exists. Defaults to false.
If true, sets the "delete on destroy" flag. This flag defaults to true, which causes the lockfile to be removed when the object is destroyed. Generally, this is the desired behavior. When set to false, this flag prevents the lockfile from being removed automatically when the object is destroyed. See also delete_on_destroy.
delete_on_destroy
For compatibility with older versions of Lazy::Lockfile (pre-1.0), a single optional parameter is accepted, the path to the lockfile. This parameter functions the same as the 'location' parameter described above.
As stated above, malformed lockfiles will be overwritten, though this may be subject to change in a future version.
If the lock can not be obtained, undef is returned (and $! will contain useful information). Otherwise, the lock is exclusive to this process, as long as the object exists.
my $lockfile = Lazy::Lockfile->new( { location => "/var/lock", no_pid => 1 } ) || die "Couldn't get lock!";
Returns the file name of the lockfile.
Gets or sets the "delete on destroy" flag.
If called without a parameter (or with undef), delete_on_destroy will return the current state of the "delete on destroy" flag. If called with a parameter, this flag will be set.
Explicitly removes the lockfile, just as if the object were destroyed. Once this has been called, delete_on_destroy will be set to false, since the lock has already been deleted. Once this method is called, there is not much use left for the object, so the user may as well delete it now.
unlock should be used when the lockfile needs to be removed deterministically while the program is running. If you simply remove all references to the Lazy::Lockfile object, the lock will be freed when garbage collection is run, which is not guaranteed to happen until the program exits (though it will likely happen immediately).
Returns a true value if the lockfile was found and removed, false otherwise.
Detect and bail out on errors when writing to the lockfile (RT#121894).
Thanks MRDVT.
Add missing dependency.
Re-package to make it easier to convert to RPM, etc.
Updated documentation, thanks Alister W.
Change to unit tests to appease cpantesters.
Implement suggestion by srezic to check PIDs belonging to other users (RT#69185).
Clean up documentation.
Update unlock to return a useful status.
Version bumps for migration to CPAN.
Fix a bug causing lockfiles with no_pid to not be deleted on destroy/unlink.
Add the unlock method, to allow for deterministic lockfile removal at runtime.
Update documentation to clarify delete_on_destroy parameter default setting.
Fix error thrown when running with taint checking enabled.
Fix a bug with lockfile location being overwritten with the default.
Add new parameter, no_pid, which disabled active lockfile checks.
Allow constructor to accept multiple parameters via hashref.
Introduce the delete_on_destroy flag.
Open pid file with O_NOFOLLOW, to avoid symlink attacks.
Change default pid file location from /var/tmp to /tmp.
Correct dates in CHANGES section.
Add useful error indicators, documentation on error detection.
Fix a bug with unspecified lockfile paths trying to create impossible file names.
Initial release.
To install Lazy::Lockfile, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Lazy::Lockfile
CPAN shell
perl -MCPAN -e shell install Lazy::Lockfile
For more information on module installation, please visit the detailed CPAN module installation guide.