/ 
Acrux-0.13
/ Acrux::FileLock

NAME

Acrux::FileLock - The Lock File simple interface

SYNOPSIS

use Acrux::FileLock;

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

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

$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 . . .

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 Lock::File, File::TinyLock, JIP::LockFile, LockFile::Simple and Acrux::FilePid.

METHODS

This module implements the following methods

new

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

This constructor takes several optional attributes:

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

debug
debug => 0

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

delay
delay => 60

Number of seconds to wait between retries to getting a lockfile

Default: 60

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 ./basename($0).lock.

flock
flock => 1

If this flag is set to true then lockfile will be lock by system with flock

Default: 0

pid
pid => $$

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

retries
retries => 5

Number of times to retry getting a lockfile

Default: 5

check

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

This method checks whether the lock is currently considered active.

Returns 1 if the lock is active or 0 if the lock is free. The return value is always boolean and does not contain the PID of the lock owner.

Before checking the lock state, this method reads the owner information from the lock file and updates the own and uid attributes when the file contains valid owner data. These values represent the metadata stored in the lock file at the time of the call and must not be considered proof that the corresponding process currently owns the lock.

When flock mode is enabled, the lock state is determined exclusively by the system file lock. The own and uid attributes are still updated from the lock file, but they do not participate in determining the lock state.

In the regular mode, the owner PID and UID are additionally used to determine whether the lock is still valid. A stale lock file is removed automatically when possible.

If a stale lock file cannot be removed by the operating system, the lock is considered active and check returns 1. This condition is reported through the debug facility and does not set error.

error

my $error = $fl->error;

Returns current error message

file

my $file = $fl->file;

Accessor for the filename used as the lock file.

lock

$self = $self->lock;

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

own

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

Accessor and mutator for the PID associated with the lock owner.

When check reads a lock file containing valid owner information, this attribute is updated with the PID stored in the file.

The value represents the owner PID recorded in the lock file at the time of the last check call. It is metadata and is not, by itself, a guarantee that the corresponding process currently owns the lock.

After a successful lock, the attribute contains the PID associated with the newly acquired lock.

In flock mode, the operating system does not provide the PID of the process holding the system lock. Therefore, when inspecting a foreign lock, own represents only the PID recorded in the lock file.

pid

my $pid = $fl->pid;

Returns the PID associated with this lock object.

By default, this is the PID of the current process ($$). The value is used when creating the lock file and is stored as the owner PID in the lock file

The PID may be specified explicitly when creating the object:

my $fl = Acrux::FileLock->new(pid => 123);

This can be useful when the object is used to represent a lock owned by another process

uid

$fl = $fl->uid(1000);
my $owner_uid = $fl->uid;

Accessor and mutator for the numeric user ID associated with the lock owner.

When check reads a lock file containing valid owner information, this attribute is updated with the UID stored in the file.

The value represents the owner UID recorded in the lock file at the time of the last check call. It is metadata and is not, by itself, a guarantee that the corresponding process currently owns the lock.

After a successful lock, the attribute contains the UID associated with the newly acquired lock.

In flock mode, the operating system does not provide the UID of the process holding the system lock. Therefore, when inspecting a foreign lock, uid represents only the UID recorded in the lock file.

unlock

$self = $self->unlock;

This method performs unlocking the lock file and removes it

HISTORY

See Changes file

TO DO

See TODO file

SEE ALSO

Lock::File, File::TinyLock, JIP::LockFile, LockFile::Simple, Acrux::FilePid

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

Copyright (C) 1998-2026 D&D Corporation

LICENSE

This program is distributed under the terms of the Artistic License Version 2.0

See the LICENSE file or https://opensource.org/license/artistic-2-0 for details