view release on metacpan or  search on metacpan

lib/Acrux/FileLock.pm  view on Meta::CPAN

package Acrux::FileLock;
use strict;
use warnings;
use utf8;

=encoding utf-8

=head1 NAME

Acrux::FileLock - The Lock File simple interface

=head1 SYNOPSIS

    use Acrux::FileLock;

    my $fl = Acrux::FileLock->new(
        file => '/tmp/file.lock',
        pid  => $$,
        auto => 0,
    );

    if ( my $pid = $fl->check ) {
        warn $fl->error if $fl->error;
        die "Already running: $pid";
    }

    $fl->lock;
    die $fl->error if $fl->error;

    # . . . do stuff . . .

    $fl->unlock;
    die $fl->error if $fl->error;

... or with auto-lock and auto-unlock:

    my $fl = Acrux::FileLock->new(
        file => '/tmp/file.lock',
        pid  => $$,
        auto => 1,
    );

    die $fl->error if $fl->error;
    die "Already running" if $fl->check;

    # . . . do stuff . . .

=head1 DESCRIPTION

The Lock File simple interface

This package manages a lock files. It will create a lock file,
query the process within to discover if it's still running, and remove
the lock file. This module based on L<Lock::File>, L<File::TinyLock>,
L<JIP::LockFile>, L<LockFile::Simple> and L<Acrux::FilePid>.

=head1 METHODS

This module implements the following methods

=head2 new

    my $fl = Acrux::FileLock->new(
        file    => '/tmp/file.lock',
        delay   => 60,
        retries => 5,
        pid     => $$,
        auto    => 1,
    );

This constructor takes several optional attributes:

=over 4

=item auto

    auto => 0

If this flag specified as true, then
will be saved the lock file automatically while instance create and
removed the lock file automatically on DESTROY phase. Default: false

=item debug

    debug => 0

Print debugging messages to STDERR (0=Off (default), 1=On)

=item delay

    delay => 60

Number of seconds to wait between retries to getting a lockfile

Default: 60

=item file

    file => '/tmp/test.lock'

The name of the lock file to work on. If not specified, a lock
file located in current directory will be created that matches F<./basename($0).lock>.

=item pid

    pid => $$

The pid to write to a new lockfile. If not specified, C<$$> is
used when the lock file doesn't exist. When the lock file does exist, the
pid inside it is used.


=item retries

    retries => 5

Number of times to retry getting a lockfile

Default: 5

=back

=head2 check

    if ( my $pid = $fl->check ) {
        warn $fl->error if $fl->error;
        die "Already running: $pid";
    }

This method checks the lock file and returns the PID of the process that first acquired the lock.
Otherwise returns 0 if no lock file found

=head2 error

    my $error = $fl->error;

Returns current error message

=head2 file

    my $file = $fl->file;

Accessor for the filename used as the lock file.

=head2 lock

    $self = $self->lock;

This method creates a lock file and stores the current PID in it.

=head2 own

    $fl->own(123);
    my $owner_did = $fl->own;

Accessor/mutator for the pid being saved to the lock file.

=head2 owner

    my $owner_uid = $fl->owner || 0;

This method returns the numeric user ID of lock file's owner or undef otherwise

=head2 pid

    my $pid = $fl->pid;

Accessor for the pid being saved to the lock file.

=head2 unlock

    $self = $self->unlock;

This method performs unlocking the lock file and removes it

=head1 HISTORY

See C<Changes> file

=head1 TO DO

See C<TODO> file

=head1 SEE ALSO

L<Lock::File>, L<File::TinyLock>, L<JIP::LockFile>, L<LockFile::Simple>,
L<Acrux::FilePid>

=head1 AUTHOR