No::Worries::PidFile(3User Contributed Perl DocumentatiNo::Worries::PidFile(3)NAMENo::Worries::PidFile - pid file handling without worries
SYNOPSIS
use No::Worries::PidFile qw(pf_set pf_check pf_touch pf_unset pf_status pf_quit);
# idiomatic daemon code
pf_set($pidfile);
while (1) {
...
$action = pf_check($pidfile);
last if $action eq "quit";
pf_touch($pidfile);
...
}
pf_unset($pidfile);
# here is how to handle a --status option
if ($Option{status}) {
($status, $message, $code) = pf_status($pidfile, freshness => 10);
printf("myprog %s\n", $message);
exit($code);
}
# here is how to handle a --quit option
if ($Option{quit}) {
pf_quit($pidfile,
linger => 10,
callback => sub { printf("myprog %s\n", $_[0]) },
);
}
DESCRIPTION
This module eases pid file handling by providing high level functions
to set, check, touch and unset pid files. All the functions die() on
error.
The pid file usually contains the process id on a single line, followed
by a newline. However, it can also be followed by an optional action,
also followed by a newline. This allows some kind of inter-process
communication: a process using pf_quit() will append the "quit" action
to the pid file and the owning process will detect this via pf_check().
All the functions properly handle concurrency. For instance, when two
processes start at the exact same time and call pf_set(), only one will
succeed and the other one will get an error.
Since an existing pid file will make pf_set() fail, it is very
important to remove the pid file in all situations, including errors.
The recommended way to do so is to use an END block:
# we need to know about transient processes
use No::Worries::Proc qw();
# we need to record what needs to be cleaned up
our(%NeedsCleanup);
# we set the pid file here and remember to clean it up
pf_set($pidfile);
$NeedsCleanup{pidfile} = 1;
# ... anything can happen here ...
# cleanup code in an END block
END {
# transient processes do not need cleanup
return if $No::Worries::Proc::Transient;
# cleanup the pid file if needed
pf_unset($pidfile) if $NeedsCleanup{pidfile};
}
FUNCTIONS
This module provides the following functions (none of them being
exported by default):
pf_set(PATH[, OPTIONS])
set the pid file by writing the given pid at the given path;
supported options:
· "pid": the pid to use (default: $$)
pf_check(PATH[, OPTIONS])
check the pid file and make sure the given pid is present, also
return the action in the pid file or the empty string; supported
options:
· "pid": the pid to use (default: $$)
pf_touch(PATH)
touch the pid file (i.e. update the file modification time) to show
that the owning process is alive
pf_unset(PATH)
unset the pid file by removing the given path
pf_status(PATH[, OPTIONS])
use information from the pid file (including its last modification
time) to guess the status of the corresponding process, return the
status (true means that the process seems to be running); in list
context, also return an informative message and an LSB compatible
exit code; supported options:
· "freshness": maximum age allowed for an active pid file
pf_quit(PATH[, OPTIONS])
tell the process corresponding to the pid file to quit (setting its
action to "quit"), wait a bit to check that it indeed stopped and
kill it using No::Worries::Proc's proc_terminate() is everything
else fails; supported options:
· "callback": code that will be called with information to report
· "linger": maximum time to wait after having told the process to
quit (default: 5)
· "kill": kill specification to use when killing the process
SEE ALSO
http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html
<http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-
generic/iniscrptact.html>, No::Worries, No::Worries::Proc.
AUTHOR
Lionel Cons <http://cern.ch/lionel.cons>
Copyright CERN 2012
perl v5.14.3 2012-12-19 No::Worries::PidFile(3)
