NAME

Lock::File - file locker with an automatic out-of-scope unlocking mechanism

VERSION

version 1.03

SYNOPSIS

    use Lock::File qw(lockfile);
    # blocking mode is default
    my $lock = lockfile('/var/lock/my_script.lock');
    # unlock
    undef $lock;
    # or:
    $lock->unlock();
    # print filename
    say $lock->name;
    $lock = lockfile('./my.lock', { blocking => 0 }) or die "Already locked";
    # lock an open file:
    $lock = lockfile($fh);
    $lock = lockfile_multi('./my.lock', 5); # will try to lock on files "my.lock.0", "my.lock.1" .. "my.lock.4"
    $lock = lockfile_any('foo', 'bar');

DESCRIPTION

"lockfile" is a perlfunc "flock" wrapper. The lock is autotamically released as soon as the assotiated object is no longer referenced.

"lockfile_multi" makes non-blocking "lockfile" calls for multiple files and throws and exception if all are locked.

FUNCTIONS

lockfile($file, $options): Create a Lock instance. Always save the result in some variable(s), otherwise the lock will be released immediately.
The lock is automatically released when all the references to the Lockf object are lost. The $file mandatory parameter can be either a string representing a filename or a reference to an already opened filehandle. The second optional parameter is a hash of boolean options. Supported options are:

shared

OFF by default. Tells to achieve a shared lock. If not set, an exclusive lock is requested.

blocking

ON by default. If unset, a non-blocking mode of flock is used. If this flock fails because the lock is already held by some other process, "undef" is returned. If the failure reason is somewhat different, e.g. permissions problems or the absence of a target file directory, an exception is thrown.

timeout

Unset by default. If set, specifies the wait timeout for acquiring the blocking lock.

Throws an exception on timeout.

The value of 0 is equivalent to "blocking => 0" option, except that it throws an exception instead of returning undef if the file is already locked.

blocking is assumed to be true, and specifying "blocking => 0" explicitly is considered an error.

mode

Undef by default. If set, a chmod with the specified mode is performed on a newly created file. Ignored when filehandle is passed instead of a filename.

remove

OFF by default. If set, the lock file will be deleted before unlocking.

Alternatively, you can use OO interface:

    my $lock = Lock::File->new($file, $options);

lockfile_multi($file, $max, $options): Calls non-blocking "lockfile"'s for files from "$fname.0" to "$fname.$max-1", and returns a "Lock::File" object for the first successful lock.
Only remove and mode options are supported.
lockfile_any($filenames, $options): Same as "lockfile_multi", but accepts arrayref of filenames.

METHODS

name(): Gives the name of the file, as it was when the lock was taken.
share(): Transform exclusive lock to shared.
unshare(): Transform shared lock to exclusive. Can block if other shared/exclusive locks are held by some other processes.
unlock(): Force the lock to be released independent of how many references to the object are still alive.

FAQ

Yet another locking module? Why?

There're tons of file locking modules <https://metacpan.org/search?q=lock> on CPAN. Last time I counted, there were at least 17.

And yet, every time I tried to find a replacement for our in-house code on which this module is based, every one of them had quirks which I found too uncomfortable. I had to copy our code as Ubic::Lockf when I opensourced Ubic.

I wanted to do the review of all those modules, neilb style <http://neilb.org/reviews/>. I never got around to that, and then I realized how much this task holds me back from releasing other useful stuff.

So... sorry for bringing yet-another-file-locking module into the world.

Why Lock::File instead of File::Lock?

First, there's File::Lock::Multi, which is completely unrelated to this module.

Second, there are so many locking modules that choosing a good name is *hard*.

Third, maybe I'm going to release Lock::Zookeeper with the similar interface in the future.

DEPRECATED FUNCTIONS AND METHODS

lockf(), lockf_multi() and lockf_any() functions, and unlockf() method were renamed to "lockfile.*" in 1.01 release.

It's unlikely that many people used 1.00 version in important code because it's been only a week since its release, but I'm keeping them around for a few releases anyway.

In other words, they are all exported on ":all", and they print a warning message.

SIMILAR MODULES

File::Flock::Tiny

File::Lockfile

Lazy::Lockfile

Lockfile::Simple

File::Lock::Multi

File::Lock

File::FcntlLock

File::TinyLock

ExclusiveLock::Guard

File::lockf

And many others.

AUTHOR

Vyacheslav Matyukhin <mmcleric@yandex-team.ru>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.