blib/lib/App/FileSync/Lock.pm

filter: Statementstmt 100% 37 / 37 Branchbran 83.3% 5 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 10 / 10 Podpod 100% 1 / 1 totaltotal 98.1% 53 / 54 CC 4 SCAR 6.5
CC
4
Cov
98%
acquire
4.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.9
« blib/lib/App/FileSync/Store.pm ↑ Summary blib/lib/App/FileSync/Args.pm »
1 package App::FileSync::Lock;
2  
3 # An advisory lock file, so two runs (cron firing while the previous run is
4 # still going, or reindex racing a session) never work on the same tree.
5  
6 329 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 329 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 329 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 329 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 329 ▶use Fcntl qw(:flock);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 329 ▶use File::Basename qw(dirname);
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 329 ▶use App::FileSync::Args qw(named);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 329 ▶use App::FileSync::IO qw(ensure_dir open_file);
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 329 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 =encoding utf8
21  
22 =head1 NAME
23  
24 App::FileSync::Lock - advisory lock files
25  
26 =head1 SYNOPSIS
27  
28 my $lock = App::FileSync::Lock::acquire(path => $path, nonblock => 1)
29 or exit 2; # another run holds it
30 # ... the lock is released when $lock goes out of scope
31  
32 =head1 FUNCTIONS
33  
34 =head2 acquire
35  
36 Purpose: take an exclusive C<flock> on a file.
37  
38 Args: C<path> (required), C<nonblock> (return at once instead of waiting).
39  
40 Returns: the filehandle holding the lock, or C<undef> when C<nonblock> is set
41 and another process holds it. The lock lasts until the handle is closed or
42 goes out of scope.
43  
44 Side Effects: creates the file and its directory if needed.
45  
46 Usage:
47  
48 my $lock = App::FileSync::Lock::acquire(path => $lock_path, nonblock => 1);
49  
50 =head3 EXAMPLE
51  
52 if (my $lock = App::FileSync::Lock::acquire(path => '/tmp/demo.lock', nonblock => 1)) {
53 print "got it\n";
54 }
55  
56 =head3 API SPECIFICATION
57  
58 =head4 INPUT
59  
60 {
61 path => { type => 'string', min => 1 },
62 nonblock => { type => 'boolean', optional => 1 },
63 }
64  
65 =head4 OUTPUT
66  
67 { type => 'handle', optional => 1 }
68  
69 =head3 MESSAGES
70  
71 Key Meaning Resolution
72 args.invalid no path was given pass path
73 io.append the lock file cannot be made check permissions
74  
75 =head3 FORMAL SPECIFICATION
76  
77 ΔLocks
78 path? : PATH ; nb? : 𝔹 ; h! : HANDLE ∪ {⊥}
79 path? ∉ dom Locks ⇒ h! ≠ ⊥ ∧ Locks' = Locks ∪ {path? ↦ self}
80 path? ∈ dom Locks ∧ nb? ⇒ h! = ⊥ ∧ Locks' = Locks
81  
82 =cut
83  
84 373 ▶sub acquire {
Subroutine acquire: called CC=4 SCAR=13.9
Pod documented
85 373 my $args = named(\@_, {
86 path => { type => 'string', min => 1 },
87 nonblock => { type => 'boolean', optional => 1 },
88 }, 'Lock::acquire');
89  
90 373 my $path = $args->{path};
91 373 ensure_dir(dirname($path));
92  
93 # Append mode creates the file without truncating one another process
94 # has open.
95 373 my $fh = open_file($path, '>>');
96  
97 # autodie's flock returns false (rather than dying) when a non-blocking
98 # lock would block, which is exactly the "someone else has it" answer.
99 373 ▶ my $flags = LOCK_EX | ($args->{nonblock} ? LOCK_NB : 0);
Branch: 1 branch
BranchTrueFalseTotal
$args->{'nonblock'} ? : 373 0 373
100 373 my $held = flock($fh, $flags);
101 373 ▶ close $fh unless $held;
Branch: 1 branch
BranchTrueFalseTotal
unless $held 10 363 373
102  
103 373 ▶ return $held ? $fh : undef;
Branch: 1 branch
BranchTrueFalseTotal
$held ? : 363 10 373
104 }
105  
106 329 1;
107  
108 __END__
« blib/lib/App/FileSync/Store.pm ↑ Summary blib/lib/App/FileSync/Args.pm »