NAME

File::Pid::Quick - Quick PID file implementation

SYNOPSIS

use File::Pid::Quick;

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 );

File::Pid::Quick->recheck;

File::Pid::Quick->check('/var/run/myjob.pid');

DESCRIPTION

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 script finishes.

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:

    use File::Pid::Quick;

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() for its verbose output.

    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 positive integer.

    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.

check

    File::Pid::Quick->check('/var/run/myjob.pid', 60);

    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 false, die()/croak() is used. If it is true, warn()/carp() is used to issue the appropriate message and exit(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.

recheck

    File::Pid::Quick->recheck;

    File::Pid::Quick->recheck(300);

    File::Pid::Quick->recheck(undef, 1);

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() above.

The second argument, $warn_and_exit, works identically to the $warn_and_exit argument described for check() above.

SEE ALSO

perl, File::Pid

AUTHOR

Matthew Sheahan, <chaos@lostsouls.org>

COPYRIGHT

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.

cpanm File::Pid::Quick

perl -MCPAN -e shell
install File::Pid::Quick