The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PID-File-0.26
River stage one • 2 direct dependents • 2 total dependents
++
/ PID::File

NAME

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

VERSION

Version 0.26

SYNOPSIS

Create PID files.

 use PID::File;
 
 my $pid_file = PID::File->new;
 
 exit if $pid_file->running;

 if ( $pid_file->create )
 {
     # do something
      
     $pid_file->remove;
 }

Or perhaps a bit more robust...

 while ( $pid_file->running || ! $pid_file->create )
 {
     print "Already running, sleeping for 2\n";
     sleep 2;
 }

 $pid_file->guard;
 
 # if we get an exception at this point, $pid_file->remove() will be called automatically
 
 $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).

The code for this module was largely borrowed from there.

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 for whether the pid file was created.

If the file already exists, and the pid in that file is still running, 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).

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

pid

 $pid_file->pid

Returns the pid in the pid file, if it exists.

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 current instance of this object.

This is enforced by an internal object mechanism, and not the actual pid in the file.

To force the removal of the pid file, supply force => 1 in the parameters...

 $pid_file->remove( force => 1 );

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 token. When that token goes out of scope, remove is called automatically.

This can give you 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 current instance of this object. This is enforced by an internal object mechanism, and not the actual pid in the file.

To force the guarding of the pid file, supply force => 1 in the parameters

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

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.