README
1NAME
2 File::Flock::Retry - Yet another flock module
3
4VERSION
5 This document describes version 0.632 of File::Flock::Retry (from Perl
6 distribution File-Flock-Retry), released on 2021-08-10.
7
8SYNOPSIS
9 use File::Flock::Retry;
10
11 # try to acquire exclusive lock. if fail to acquire lock within 60s, die.
12 my $lock = File::Flock::Retry->lock($file);
13
14 # explicitly unlock
15 $lock->release;
16
17 # automatically unlock if object is DESTROY-ed.
18 undef $lock;
19
20DESCRIPTION
21 This is yet another flock module. It is a more lightweight alternative
22 to File::Flock with some other differences:
23
24 * OO interface only
25
26 * Autoretry (by default for 60s) when trying to acquire lock
27
28 I prefer this approach to blocking/waiting indefinitely or failing
29 immediately.
30
31METHODS
32 lock
33 Usage:
34
35 $lock = File::Flock::Retry->lock($path, \%opts)
36
37 Attempt to acquire an exclusive lock on $path. By default, $path will be
38 created if not already exists (see "mode"). If $path is already locked
39 by another process, will retry every second for a number of seconds (by
40 default 60). Will die if failed to acquire lock after all retries.
41
42 Will automatically unlock if $lock goes out of scope. Upon unlock, will
43 remove $path if it is still empty (zero-sized).
44
45 Available options:
46
47 * mode
48
49 Integer. Default: O_CREAT | O_RDWR.
50
51 File open mode, to be passed to Perl's "sysopen()". For example, if
52 you want to avoid race condition between creating and locking the
53 file, you might want to use "O_CREAT | O_EXCL | O_RDWR" to fail when
54 the file already exists. Note that the constants are available after
55 you do a "use Fcntl ':DEFAULT';".
56
57 * retries
58
59 Integer. Default: 60.
60
61 Number of retries (equals number of seconds, since retry is done
62 every second).
63
64 * shared
65
66 Boolean. Default: 0.
67
68 By default, an exclusive lock (LOCK_EX) is attempted. However, if
69 this option is set to true, a shared lock (LOCK_SH) is attempted.
70
71 unlock
72 Usage:
73
74 $lock->unlock
75
76 Unlock. will remove lock file if it is still empty.
77
78 release
79 Usage:
80
81 $lock->release
82
83 Synonym for "unlock".
84
85 handle
86 Usage:
87
88 my $fh = $lock->handle;
89
90 Return the file handle.
91
92HOMEPAGE
93 Please visit the project's homepage at
94 <https://metacpan.org/release/File-Flock-Retry>.
95
96SOURCE
97 Source repository is at
98 <https://github.com/perlancar/perl-File-Flock-Retry>.
99
100BUGS
101 Please report any bugs or feature requests on the bugtracker website
102 <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Flock-Retry>
103
104 When submitting a bug or request, please include a test-file or a patch
105 to an existing test-file that illustrates the bug or desired feature.
106
107CAVEATS
108 Not yet tested on Windows. Some filesystems do not support inode?
109
110SEE ALSO
111 File::Flock, a bit too heavy in terms of dependencies and startup
112 overhead, for my taste. It depends on things like File::Slurp and
113 Data::Structure::Util (which loads Digest::MD5, Storable, among others).
114
115 File::Flock::Tiny which is also tiny, but does not have the autoremove
116 and autoretry capability which I want. See also:
117 <https://github.com/trinitum/perl-File-Flock-Tiny/issues/1>
118
119 flock() Perl function.
120
121 An alternative to flock() is just using sysopen() with O_CREAT|O_EXCL
122 mode to create lock files. This is supported on more filesystems
123 (particularly network filesystems which lack flock()).
124
125AUTHOR
126 perlancar <perlancar@cpan.org>
127
128COPYRIGHT AND LICENSE
129 This software is copyright (c) 2021, 2019, 2017, 2015, 2014 by perlancar
130 <perlancar@cpan.org>.
131
132 This is free software; you can redistribute it and/or modify it under
133 the same terms as the Perl 5 programming language system itself.
134
135