NAME

AnyEvent::FileLock - Lock files asynchronously

SYNOPSIS

use AnyEvent::FileLock;

my $w = AnyEvent::FileLock->flock(file => $fn,
                                  cb => sub { ... },
                                  mode => '<',
                                  delay => $seconds,
                                  timeout => $timeout);

DESCRIPTION

This module tries to lock some file repeatedly until it success or a timeout happens.

API

The function provides a unique method flock accepting the following arguments:

fh => $file_handle

When this argument is given the passed file handle is used as the file locking target.

file => $file_name

When this argument is given a file with the given name will be opened or created and then the module will try to lock it.

type => $lock_type

$lock_type may be fcntl or flock and determines the way used to obtain the lock under the hood.

The default is flock.

In order to use locks of type fcntl, the module Fctnl::Packer has to be also installed.

cb => $sub_ref

The given function is called once the lock is acquired on the file with the file handle passed as an argument.

In case of error (i.e. timeout) undef will be passed instead of the file handle. The error can be retrieved from $!.

The user is responsible for closing the file handle or calling flock($fh, LOCK_UN) (or the corresponding fcntl(2) F_UNLCK) on it when required.

open_mode => $mode

The mode used to open the file when the argument file is passed. Accepted values are <, >, >>, +< and +>.

lock_mode => $mode

The mode used when locking the file, it accepts the same set of values as open_mode. < means shared access and everything else exclusive access.

mode => $mode

Configures both open_mode and lock_mode.

timeout => $seconds

The operation is aborted if the lock operation can not be completed for the given lapse.

Note that this timeout is approximate, it is checked just after every failed locking attempt.

delay => $seconds

Time to be delayed between consecutive locking attempts. Defaults to 1 second.

Some randomness will be added to the delay to avoid the degenerate case where all the contenders look for the lock at the same time every time.

whence => $whence

start => $start

len => $len

When fcntl is selected as the lock type, this three additional arguments can be used to define the section of the file that has to be locked. See fcntl(2) for the details.

SEE ALSO

AnyEvent.

"flock" in perlfunc, "fcntl" in perlfunc, fcntl(2), Fcntl, Fcntl::Packer.

AUTHORS

Salvador Fandiño, <sfandino@yahoo.com>

Manfred Stock, <mstock@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013, 2017 by Qindel Formación y Servicios S.L.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.