| 1 | =head1 NAME | ||||||||||||||||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||||||||||||||||
| 3 | AnyEvent::MCP::File - private state file locking and replacement | ||||||||||||||||||||||||||||||||||||||||||
| 4 | |||||||||||||||||||||||||||||||||||||||||||
| 5 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||||||||||||||||
| 7 | Internal utility for small state files shared by MCP processes, | ||||||||||||||||||||||||||||||||||||||||||
| 8 | such as the workdir ID registry. C<lock> obtains a lock on the current | ||||||||||||||||||||||||||||||||||||||||||
| 9 | pathname; C<replace> writes a complete new version atomically. The caller | ||||||||||||||||||||||||||||||||||||||||||
| 10 | owns serialization, validation and the lock's lifetime. | ||||||||||||||||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||||||||||||||||
| 12 | For example, after building a new complete file body: | ||||||||||||||||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||||||||||||||||
| 14 | use AnyEvent::MCP::File (); | ||||||||||||||||||||||||||||||||||||||||||
| 15 | |||||||||||||||||||||||||||||||||||||||||||
| 16 | my $lock = AnyEvent::MCP::File::lock $path; | ||||||||||||||||||||||||||||||||||||||||||
| 17 | # read and validate the current state under this lock | ||||||||||||||||||||||||||||||||||||||||||
| 18 | AnyEvent::MCP::File::replace $path, $new_bytes; | ||||||||||||||||||||||||||||||||||||||||||
| 19 | close $lock; | ||||||||||||||||||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||||||||||||||||
| 21 | The lock protects cooperating writers, not other programs that write the | ||||||||||||||||||||||||||||||||||||||||||
| 22 | file without this protocol. Use L<AnyEvent::MCP::Workdirs> for the workdir | ||||||||||||||||||||||||||||||||||||||||||
| 23 | registry rather than implementing its update rules here. | ||||||||||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||||||||||
| 25 | =head1 FUNCTIONS | ||||||||||||||||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||||||||||||||||
| 27 | =over | ||||||||||||||||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||||||||||||||||
| 29 | =item $lock = AnyEvent::MCP::File::lock $file | ||||||||||||||||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||||||||||||||||
| 31 | Create the parent directory and file if necessary, and lock the current file | ||||||||||||||||||||||||||||||||||||||||||
| 32 | exclusively. Retries if an atomic replacement changed the pathname while waiting for the lock. | ||||||||||||||||||||||||||||||||||||||||||
| 33 | Keep the returned handle alive through reading, modifying and replacing | ||||||||||||||||||||||||||||||||||||||||||
| 34 | the file. All writers must use this locking protocol. | ||||||||||||||||||||||||||||||||||||||||||
| 35 | |||||||||||||||||||||||||||||||||||||||||||
| 36 | =item AnyEvent::MCP::File::replace $file, $bytes | ||||||||||||||||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||||||||||||||||
| 38 | Write bytes to a temporary file beside C<$file>, preserve the mode of an | ||||||||||||||||||||||||||||||||||||||||||
| 39 | existing file, then atomically rename over C<$file>. The caller holds the lock. | ||||||||||||||||||||||||||||||||||||||||||
| 40 | Removes the temporary file on failure. This provides atomic visibility, | ||||||||||||||||||||||||||||||||||||||||||
| 41 | not crash durability. | ||||||||||||||||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||||||||||||||||
| 43 | =back | ||||||||||||||||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||||||||||||||||
| 45 | =cut | ||||||||||||||||||||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||||||||||||||||||||
| 47 | package AnyEvent::MCP::File; | ||||||||||||||||||||||||||||||||||||||||||
| 48 | |||||||||||||||||||||||||||||||||||||||||||
| 49 | 355 | ▶ | use common::sense; | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 50 | 355 | ▶ | use File::Path (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 51 | 355 | ▶ | use File::Basename (); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 52 | 355 | ▶ | use Fcntl qw(O_RDWR O_WRONLY O_CREAT O_EXCL LOCK_EX); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 53 | 355 | ▶ | use Errno qw(ENOENT EEXIST); | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||||||||
| 54 | |||||||||||||||||||||||||||||||||||||||||||
| 55 | 1790 | ▶ | sub lock { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
lock: called CC=10 SCAR=29.2
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 56 | 1790 | my ($file) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||||||||||||||||||||
| 58 | 1790 | File::Path::mkpath (File::Basename::dirname ($file), 0, 0700); | |||||||||||||||||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||||||||||||||||
| 60 | 1790 | while (1) { | |||||||||||||||||||||||||||||||||||||||||
| 61 | 1790 | my $fh; | |||||||||||||||||||||||||||||||||||||||||
| 62 | 1790 | ▶ | sysopen $fh, $file, O_RDWR | O_CREAT | O_EXCL, 0600 or do { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 63 | 1702 | ▶ | die "$file: $!\n" unless $! == EEXIST; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 64 | 1702 | ▶ | sysopen $fh, $file, O_RDWR or die "$file: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 65 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 66 | |||||||||||||||||||||||||||||||||||||||||||
| 67 | 1790 | my @stat = stat $fh; | |||||||||||||||||||||||||||||||||||||||||
| 68 | 1790 | ▶ | flock $fh, LOCK_EX or die "$file: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 69 | 1790 | my @current = stat $file; | |||||||||||||||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||||||||||||||||
| 71 | 1790 | ▶ | return $fh if @current && $stat[0] == $current[0] && $stat[1] == $current[1]; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%2/6
@current and $stat[0] == $current[0] and $stat[1] == $current[1]
@current and $stat[0] == $current[0]
MC/DC0%0/3
@current and $stat[0] == $current[0] and $stat[1] == $current[1]
@current
$stat[0] == $current[0]
$stat[1] == $current[1]
Truth table25%1/4
A and B and C
A= @currentB= $stat[0] == $current[0]C= $stat[1] == $current[1]
| |||||||||||||||||||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||||||||||||||||||
| 73 | 0 | ▶ | die "$file: $!\n" unless @current || $! == ENOENT; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
@current or $! == 2
MC/DC0%0/2
@current or $! == 2
@current
$! == 2
Truth table0%0/3
A or B
A= @currentB= $! == 2
| |||||||||||||||||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||||||||||||||||
| 75 | 0 | close $fh; | |||||||||||||||||||||||||||||||||||||||||
| 76 | } | ||||||||||||||||||||||||||||||||||||||||||
| 77 | } | ||||||||||||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||||||||||||
| 79 | 396 | ▶ | sub replace { | ||||||||||||||||||||||||||||||||||||||||
|
Subroutine
replace: called CC=11 SCAR=26.3
Pod
documented
| |||||||||||||||||||||||||||||||||||||||||||
| 80 | 396 | my ($file, $bytes) = @_; | |||||||||||||||||||||||||||||||||||||||||
| 81 | |||||||||||||||||||||||||||||||||||||||||||
| 82 | 396 | my @stat = stat $file; | |||||||||||||||||||||||||||||||||||||||||
| 83 | 396 | ▶ | die "$file: $!\n" unless @stat || $! == ENOENT; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
@stat or $! == 2
MC/DC0%0/2
@stat or $! == 2
@stat
$! == 2
Truth table33%1/3
A or B
A= @statB= $! == 2
| |||||||||||||||||||||||||||||||||||||||||||
| 84 | |||||||||||||||||||||||||||||||||||||||||||
| 85 | 396 | my $temporary = "$file.$$~"; | |||||||||||||||||||||||||||||||||||||||||
| 86 | 396 | ▶ | sysopen my $fh, $temporary, O_WRONLY | O_CREAT | O_EXCL, 0600 or die "$temporary: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 87 | |||||||||||||||||||||||||||||||||||||||||||
| 88 | 396 | my $ok = eval { | |||||||||||||||||||||||||||||||||||||||||
| 89 | 396 | ▶ | print {$fh} $bytes or die "$temporary: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 90 | 396 | ▶ | if (@stat) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 91 | 396 | my $mode = $stat[2] & 07777; | |||||||||||||||||||||||||||||||||||||||||
| 92 | 396 | ▶ | chmod $mode, $fh or die "$temporary: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 93 | } | ||||||||||||||||||||||||||||||||||||||||||
| 94 | 396 | ▶ | close $fh or die "$temporary: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 95 | 396 | ▶ | rename $temporary, $file or die "$file: $!\n"; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 96 | 396 | 1 | |||||||||||||||||||||||||||||||||||||||||
| 97 | }; | ||||||||||||||||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||||||||||||||||
| 99 | 396 | my $error = $@; | |||||||||||||||||||||||||||||||||||||||||
| 100 | 396 | ▶ | unlink $temporary unless $ok; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 101 | 396 | ▶ | die $error unless $ok; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 102 | } | ||||||||||||||||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||||||||||||||||
| 104 | 355 | 1; | |||||||||||||||||||||||||||||||||||||||||