/ 
PID-File-0.32
River stage one • 2 direct dependents • 2 total dependents
/ PID::File

NAME

PID::File - PID files that guard against exceptions.

VERSION

Version 0.32

SYNOPSIS

Create PID files.

use PID::File;

my $pid_file = PID::File->new;

exit if $pid_file->running;

if ( $pid_file->create )
{
    $pid_file->guard;

    # do something

    $pid_file->remove;
}

Using the built-in retry mechanism...

if ( ! $pid_file->create( retries => 10, sleep => 5 ) )
{
    die "Could not create pid file after 10 attempts";
}

# do something

$pid_file->remove;

DESCRIPTION

Creating a pid file, or lock file, should be such a simple process.

See Daemon::Control for a more complete solution for creating daemons (and pid files).

After creating a pid file, if an exception is thrown (and the $pid_file goes out of scope) the pid file would normally remain in place.

If you call guard() on the pid object after creation, it will remove the pid file automatically when it goes out of scope. More on this later.

Methods

Class Methods

new

my $pid_file = PID::File->new;

Instance Methods

file

The filename for the pid file.

$pid_file->file( '/tmp/myapp.pid' );

If you specify a relative path, it will be relative to where your scripts runs.

By default it will use the script name and append .pid to it.

create

Attempt to create a new pid file.

if ( $pid_file->create )

Returns true or false.

If the file already exists, no action will be taken and it will return false.

If you supply the retries parameter, it will retry that many times, sleeping for sleep seconds (1 by default) between retries.

if ( ! $pid_file->create( retries => 5, sleep => 2 ) )
{
    die "Could not create pid file";
}

As a shortcut, you can also guard the pid file by passing the guard boolean as a parameter.

$pid_file->create( guard => 1 );

See below for more details on the guard mechanism.

pid

$pid_file->pid

Stores the pid from the pid file, if one exists. Could be undefined.

running

if ( $pid_file->running )

Returns true or false to indicate whether the pid in the current pid file is running.

remove

Removes the pid file.

$pid_file->remove;

You can only remove a pid file that was created by the same process.

guard

This deals with scenarios where your script may throw an exception before you can remove the lock file yourself.

When called in void context, this configures the $pid_file object to call remove automatically when it goes out of scope.

if ( $pid_file->create )
{
    $pid_file->guard;

    die;
}

When called in either scalar or list context, it will return a single token.

When that token goes out of scope, remove is called automatically.

This gives more control on when to automatically remove the pid file.

if ( $pid_file->create )
{
    my $guard = $pid_file->guard;
}

# remove() called automatically, even though $pid_file is still in scope

Note, that if you call remove yourself, the guard configuration will be reset, to save trying to remove the file again when the $pid_file object finally goes out of scope naturally.

You can only guard a pid file that was created by the same process.

AUTHOR

Rob Brown, <rob at intelcompute.com>

BUGS

Please report any bugs or feature requests to bug-pid-file at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PID-File. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PID::File

You can also look for information at:

SEE ALSO

Daemon::Control

Scope::Guard

LICENSE AND COPYRIGHT

Copyright 2012 Rob Brown.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.