| 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
| |||||||||||
| 100 | 373 | my $held = flock($fh, $flags); | |||||||||
| 101 | 373 | ▶ | close $fh unless $held; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 102 | |||||||||||
| 103 | 373 | ▶ | return $held ? $fh : undef; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 104 | } | ||||||||||
| 105 | |||||||||||
| 106 | 329 | 1; | |||||||||
| 107 | |||||||||||
| 108 | __END__ | ||||||||||