NAME

Proc::PID::File - a module to manage process id files

SYNOPSIS

  use Proc::PID::File;
  die "Already running!" if Proc::PID::File->running();

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 three interfaces: 1) a simple call, 2) an object-oriented interface, and 3) a regular procedural function set.

Simple Interface

The simple interface consists of a call as indicated in 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 ->file() method described below with the exception of the additional parameter listed below. The mothod's return value is the same as that of ->alive().

verify = 1 | string

This parameter helps prevent the problem described in the WARNING section below. If set to a string, it will be interpreted as a regular expression and used to search within the name of the running process. A 1 may also be passed, indicating that the value of $0 should be used (stripped of its full path). 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

OO Interface

The following methods are provided:

new [hash[-ref]]

This method is used to create an instance of the module. It automatically calls the ->file() method described below and receives the same paramters. For a listing of valid keys in this has please refer to the aforementioned method documentation below.

In addition to the above, the following constitute valid keys:

debug

Turns debugging output on.

file [hash[-ref]]

Use this method to set the path of the pidfile. The method receives an optional hash (or alternatively a hash reference) of options, which includes those 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 calling process is already running. Please note that this call must be made *after* daemonisation i.e. subsequent to the call to fork().

read

Returns the process id currently stored in the file set. If unable to open the file for read, the method die()s with an error message.

write

Causes for the current process id to be written to the set file. The process die()s upon failure to write to the file.

remove

This method is used to delete the pidfile and is automatically called by DESTROY method. It should thus be unnecessary to call it directly.

Procedural interface

The module can also export its functionality into the caller's namespace. The functions exported generally correspond to those in the OO interface but follow the naming format: pid_file_<name>.

As an exception, instead of calling ->new() the user will need to call pid_file_set before making any other calls.

- exempli gratia -

  use Proc::PID::File qw(:all);
  pid_file_set( dir => "/var/run", name => "mydaemon" );
  die "Already running!" if pid_file_alive();

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 and FreeBSD, support of the verify option (simple interface) requires the ps utility to be available. This is typically found in the procps RPM.

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.

RFC

The following is a request-for-comments on the following issues:

1) Would welcome feedback on whether I should just drop the OO and procedural interfaces and leave only the simple interface.

2) A better solution to boot-up problem described above would be most welcome.

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.15 2003/11/02 01:36:07 ekkis Exp $

cpanm Proc::PID::File

perl -MCPAN -e shell
install Proc::PID::File