NAME

File::Flock::Tiny - yet another flock package

SYNOPSIS

my $lock = File::Flock::Tiny->lock($file);
... # do something
$lock->release;

DESCRIPTION

Simple wrapper around flock for ease of use.

CLASS METHODS

File::Flock::Tiny->lock($file)

Acquire exclusive lock on the file. $file may be a file name or an opened file handler. If a filename given and the file doesn't exist it will be created. The method returns a lock object, the file remains locked until this object goes out of the scope, or till you call release method on it.

File::Flock::Tiny->trylock($file)

Same as lock, but doesn't block and returns immediately, if the lock can not be acquired returns undef.

File::Flock::Tiny->write_pid($file)

Try to lock the file and save the process ID into it. Returns the lock object, or undef if the file was already locked. The lock returned by write_pid will be automatically released when the object goes out of the scope in the process that locked the pid file, in child processes you can release the lock explicitely.

LOCK OBJECT METHODS

Here is the list of methods that you can invoke on a lock object.

$lock->write_pid

Truncates locked file and saves PID into it. Also marks the lock object as tied to the current process, so it only will be automatically released when goes out of scope in the current process but not in any of the child processes created after this call. This method may be used to create pid files for daemons, you can lock file in parent process to ensure that there is no another copy of the daemon running already, and then fork and write pid of the child into the file. Here is the simplified example of daemonizing code:

my $pid = File::Flock::Tiny->trylock('daemon.pid')
  or die "Daemon already running";
if ( fork == 0 ) {
    setsid;
    if (fork) {
        # intermediate process
        $pid->close;
        exit 0;
    }
}
else {
    # parent process
    $pid->close;
    exit 0;
}
# daemon process
# perhaps you want to close all opened files here, do not close $pid!
$pid->write_pid;

It is importand to remember to close the lock file in the parent and intermediate processes, otherwise the lock will be released during destruction of the variable.

$lock->release

Release lock and close the file

$lock->close

Close the locked filehandle, but do not release the lock. Normally if you closed the file it will be unlocked, but if you forked after locking the file and when closed the lock in the parent process, the file will still be locked even after the lock went out of the scope in the parent process. The following example demonstrates the use for this method:

{
    my $lock = File::Flock::Tiny->lock("lockfile");
    my $pid = fork;
    if( $pid == 0 ) {
        # We are in child process
        do_something();
    }
    $lock->close;
}
# file still locked by child. Without $lock->close,
# it would be unlocked by parent when $lock went out
# of the scope

Note, that this behaviour is not portable! It works on Linux and BSD, but on Solaris locks are not inherited by child processes, so the file will be unlocked as soon as the parent process will close it. See also description of flock.

AUTHOR

Pavel Shaydo, <zwon at cpan.org>

CAVEATS

Different implementations of flock behave differently, code that uses this module may be non-portable, like any other code that uses flock. See "flock" in perlfunc for details.

On windows you can not read the file while it is locked by another process, hence "write_pid" doesn't make much sense.

BUGS

Please report any bugs or feature requests via GitHub bug tracker at http://github.com/trinitum/perl-File-Flock-Tiny/issues.

SEE ALSO

A lot of modules with similar functionality on CPAN, it just happened that I don't like any of them.

LICENSE AND COPYRIGHT

Copyright 2011, 2012 Pavel Shaydo.

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.