File::Pid::Quick - Quick PID file implementation
use File::Pid::Quick qw( /var/run/myjob.pid );
use File::Pid::Quick qw( /var/run/myjob.pid verbose );
use File::Pid::Quick qw( /var/run/myjob.pid timeout 120 );
This module associates a PID file with your script for the purpose of keeping
more than one copy from running (concurrency prevention). It creates the PID
file, checks for its existence when the script is run, terminates the script
if there is already an instance running, and removes the PID file when the
This module's objective is to provide a completely simplified interface that
makes adding PID-file-based concurrency prevention to your script as quick and
simple as possible; hence File::Pid::Quick. For a more nuanced implementation
of PID files, please see File::Pid.
The absolute simplest way to use this module is:
A default PID file will be used, located in "File::Spec->tmpdir"
and named "File::Basename::basename($0) . '.pid'"; for example, if
$0 is ~/bin/run
, the PID file will be /tmp/run.pid
. The PID file
will be checked and/or generated immediately on use of the module.
Alternately, an import list may be provided to the module. It can contain three
kinds of things:
use File::Pid::Quick qw( verbose );
If the string 'verbose' is passed in the import list, the module will do more
reporting on its activities than otherwise. It will use warn()
use File::Pid::Quick qw( timeout 60 );
If the string 'timeout' is passed in the import list, the next item in the
import list will be interpreted as a timeout after which, instead of
terminating itself because another instance was found, the script should send
a SIGTERM to the other instance and go ahead itself. The timeout must be a
use File::Pid::Quick qw( manual );
If the string 'manual' is passed in the import list, the normal behavior of
generating a default PID file will be suppressed. This is essentially for
cases where you want to control exactly when the PID file check is performed
by using File::Pid::Quick-> check()
, below. The check will still be
performed immediately if a filename is also provided in the import list.
use File::Pid::Quick qw( /var/run/myscript.pid );
Any other string passed in the import list is interpreted as a filename to be
used instead of the default for the PID file. If more than one such string is
found, this is an error.
Any combination of the above import list options may be used.
File::Pid::Quick->check(undef, undef, 1);
Performs a check of the specified PID file, including generating it if
necessary, finding whether another instance is actually running, and
terminating the current process if necesasry.
All arguments are optional.
The first argument, $pid_file, is the filename to check; an undefined value
results in the default (described above) being used.
The second argument, $use_timeout, is a PID file timeout. If an already-running
script instance started more than this many seconds ago, don't terminate the
current instance; instead, terminate the already-running instance (by sending
a SIGTERM) and proceed. If defined, this must be a non-negative integer. An
undefined value results in the timeout value set by this module's import list
being used, if any; a value of 0 causes no timeout to be applied, overriding
the value set by the import list if necessary.
The third argument, $warn_and_exit, controls how the script terminates. If it is
is used. If it is true,
is used to issue the appropriate message and
(1) is used to terminate. This allows the module to terminate the
script from inside an eval()
; PID file checks performed based on the
module's import list use this option.
Used to reverify that the running process is the owner of the appropriate PID
file. Checks all PID files which were created by the current process.
All arguments are optional.
The first argument, $timeout, is a timeout value which will be applied to PID
file checks in exactly the same manner as describe for check()
The second argument, $warn_and_exit, works identically to the $warn_and_exit
argument described for check()
Matthew Sheahan, <firstname.lastname@example.org>
Copyright (c) 2007, 2010 Matthew Sheahan. All rights reserved. This module is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.