NAME¶
Proc::PID::File - a module to manage process id files
SYNOPSIS¶
use Proc::PID::File;
die "Already running!" if Proc::PID::File->running();
Process that spawn child processes may want to protect each separately by using
multiple
pidfiles.
my $child1 = Proc::PID::File->new(name => "lock.1");
my $child2 = Proc::PID::File->new(name => "lock.2");
which may be checked like this:
<do-something> if $child1->alive();
and should be released manually:
$child1->release();
DESCRIPTION¶
This Perl module is useful for writers of daemons and other processes that need
to tell whether they are already running, in order to prevent multiple process
instances. The module accomplishes this via *nix-style
pidfiles, which
are files that store a process identifier.
The module provides two interfaces: 1) a simple call, and 2) an object-oriented
interface
Simple Interface¶
The simple interface consists of a call as indicated in the first example of the
Synopsis section above. This approach avoids causing race conditions
whereby one instance of a daemon could read the
pidfile after a
previous instance has read it but before it has had a chance to write to it.
running [hash[-ref]]¶
The parameter signature for this function is identical to that of the
-> new() method described below in the
OO
Interface section of this document. The method's return value is the same
as that of
->alive().
OO Interface¶
The following methods are provided:
new [hash[-ref]]¶
This method is used to create an instance object. It automatically calls the
-> file() method described below and receives the same
paramters. For a listing of valid keys in this hash please refer to the
aforementioned method documentation below.
In addition to the above, the following constitute valid keys:
- verify = 1 | string
- This parameter implements the second solution outlined in
the WARNING section of this document and is used to verify that an
existing pidfile correctly represents a live process other than the
current. If set to a string, it will be interpreted as a regular
expression and used to search within the name of the running process.
Alternatively, a 1 may be passed: For Linux/FreeBSD, this indicates that
the value of $0 will be used (stripped of its full
path); for Cygwin, $^X (stripped of path and extension) will be
used.
If the parameter is not passed, no verification will take place. Please note
that verification will only work for the operating systems listed below
and that the OS will be auto-sensed. See also DEPENDENCIES section below.
Supported platforms: Linux, FreeBSD, Cygwin
- debug
- Any non-zero value turns debugging output on. Additionally,
if a string is passed containing the character M, the module name
will be prefixed to the debugging output.
file [hash[-ref]]¶
Use this method to set the path of the
pidfile. The method receives an
optional hash (or hash reference) with the keys listed below, from which it
makes a path of the format:
$dir/$name.pid.
- dir
- Specifies the directory to place the pid file. If left
unspecified, defaults to /var/run.
- name
- Indicates the name of the current process. When not
specified, defaults to basename($0).
alive¶
Returns true when the process is already running. Please note that this call
must be made *after* daemonisation i.e. subsequent to the call to
fork(). If the
verify flag was set during the instance creation,
the process id is verified, alternatively the flag may be passed directly to
this method.
touch¶
Causes for the current process id to be written to the
pidfile.
release¶
This method is used to delete the
pidfile and is automatically called by
DESTROY method. It should thus be unnecessary to call it directly.
locktime [hash[-ref]]¶
This method returns the
mtime of the
pidfile.
AUTHOR¶
Erick Calder <ecalder@cpan.org>
ACKNOWLEDGEMENTS¶
1k thx to Steven Haryanto <steven@haryan.to> whose package
(Proc::RID_File) inspired this implementation.
Our gratitude also to Alan Ferrency <alan@pair.com> for fingering the
boot-up problem and suggesting possible solutions.
DEPENDENCIES¶
For Linux, FreeBSD and Cygwin, support of the
verify option requires
availability of the
ps utility. For Linux/FreeBSD This is typically
found in the
procps package. Cygwin users need to run version 1.5.20 or
later for this to work.
WARNING¶
This module may prevent daemons from starting at system boot time. The problem
occurs because the process id written to the
pidfile by an instance of
the daemon may coincidentally be reused by another process after a system
restart, thus making the daemon think it's already running.
Some ideas on how to fix this problem are catalogued below, but unfortunately,
no platform-independent solutions have yet been gleaned.
- - leaving the pidfile open for the duration of the
daemon's life
- - checking a "ps" to make sure the pid is what
one expects (current implementation)
- - looking at /proc/$PID/stat for a process name
- - check mtime of the pidfile versus uptime; don't trust old
pidfiles
- - try to get the script to nuke its pidfile when it exits
(this is vulnerable to hardware resets and hard reboots)
- - try to nuke the pidfile at boot time before the script
runs; this solution suffers from a race condition wherein two instances read
the pidfile before one manages to lock it, thus allowing two
instances to run simultaneously.
SUPPORT¶
For help and thank you notes, e-mail the author directly. To report a bug,
submit a patch or add to our wishlist please visit the CPAN bug manager at:
http://rt.cpan.org
AVAILABILITY¶
The latest version of the tarball, RPM and SRPM may always be found at:
http://perl.arix.com/ Additionally the module is available from CPAN.
LICENCE¶
This utility is free and distributed under GPL, the Gnu Public License. A copy
of this license was included in a file called LICENSE. If for some reason,
this file was not included, please see
http://www.gnu.org/licenses/ to
obtain a copy of this license.
$Id: File.pm,v 1.16 2004-04-08 02:27:25 ekkis Exp $