blib/lib/App/FileSync/Process.pm

filter: Statementstmt 69.2% 97 / 140 Branchbran 46.4% 13 / 28 Conditioncond 18.5% 5 / 27 MC/DCmcdc 6.2% 1 / 16 Subroutinesub 81.4% 22 / 27 Podpod 100% 2 / 2 totaltotal 58.3% 140 / 240 CC 26 SCAR 24.8
CC
26
Cov
59%
_spawn_windows
42.0
_point
30.0
_no_inherit
20.0
CRAP 12.0
« blib/lib/App/FileSync/Transport/SSH.pm ↑ Summary blib/lib/App/FileSync/Merge.pm »
1 package App::FileSync::Process;
2  
3 # Starts the child a transport talks to (filesync-server, or ssh) and reaps
4 # it. Both transports used to call IPC::Open3 and then waitpid directly,
5 # which hung forever on Windows: the child inherited the parent's end of its
6 # own stdin pipe, so closing that end never gave it end of file.
7  
8 327 ▶use App::FileSync::Platform;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 327 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 327 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 327 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 327 ▶use IO::Handle ();
Subroutine BEGIN: called CC=1 SCAR=0.0
15 327 ▶use IPC::Open3 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
16 327 ▶use POSIX qw(WNOHANG);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 327 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 327 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
19 327 ▶use Time::HiRes ();
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 327 ▶use App::FileSync::Args qw(named);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 327 ▶use App::FileSync::I18N qw(throw);
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 327 ▶use version; our $VERSION = version->declare('0.002.1');
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 # How long reap() waits for a child to exit by itself before stopping it.
27 # The server needs a moment after end of file to discard a half-received
28 # upload and journal the failed session; over ssh the remote end has to
29 # hear of it first. A package variable, not Readonly, so tests can shrink it.
30 327 our $GRACE_SECONDS = 30;
31  
32 # After SIGTERM, how long to wait before SIGKILL.
33 327 our $TERM_SECONDS = 5;
34  
35 # How often reap() looks to see whether the child has gone.
36 327 Readonly::Scalar my $POLL_SECONDS => 0.05;
37  
38 # Windows: handle inheritance is switched off per handle, not per process.
39 327 Readonly::Scalar my $IS_WINDOWS => $^O eq 'MSWin32';
40  
41 # The value waitpid() returns once there is no such child left to reap.
42 327 Readonly::Scalar my $NO_CHILD => -1;
43  
44 # Bits of $? that hold the exit status and the signal.
45 327 Readonly::Scalar my $EXIT_SHIFT => 8;
46 327 Readonly::Scalar my $SIGNAL_MASK => 127;
47  
48 =encoding utf8
49  
50 =head1 NAME
51  
52 App::FileSync::Process - start and reap a transport's child process
53  
54 =head1 SYNOPSIS
55  
56 use App::FileSync::Process;
57  
58 my $child = App::FileSync::Process::spawn(command => [ 'ssh', 'host', 'filesync-server' ], stderr => fileno(STDERR));
59 print { $child->{writer} } "...\n";
60 close $child->{writer};
61 close $child->{reader};
62 my $end = App::FileSync::Process::reap(pid => $child->{pid});
63  
64 =head1 DESCRIPTION
65  
66 A transport writes to its child's standard input and reads its standard
67 output, and relies on the child seeing end of file when the transport closes
68 its end. That only happens once every copy of the pipe's write end is
69 closed. IPC::Open3 marks the parent's ends close-on-exec on Unix, but on
70 Windows it starts the child with every inheritable handle, so the child held
71 a copy of its own stdin's write end and waited for input forever.
72  
73 C<spawn> therefore makes the parent's ends non-inheritable on Windows before
74 starting the child, and C<reap> never waits without limit: a child that has
75 not exited after C<$GRACE_SECONDS> is stopped.
76  
77 =head1 FUNCTIONS
78  
79 =head2 spawn
80  
81 Purpose: start a child process with pipes to its standard input and output.
82  
83 Args: C<command> (the argv, never passed through a shell), C<stderr> (a file
84 descriptor the child's standard error goes to).
85  
86 Returns: a hashref: C<pid>, C<writer> (to the child's standard input),
87 C<reader> (from its standard output). The writer is unbuffered.
88  
89 Side Effects: starts the process. On Windows, briefly points this process's
90 standard handles at the child's pipes while it starts.
91  
92 Usage:
93  
94 my $child = App::FileSync::Process::spawn(command => \@argv, stderr => fileno(STDERR));
95  
96 =head3 EXAMPLE
97  
98 my $child = App::FileSync::Process::spawn(command => [ $^X, '-pe1' ], stderr => fileno(STDERR));
99 print { $child->{writer} } "echo\n";
100 close $child->{writer};
101 print readline $child->{reader}; # echo
102  
103 =head3 API SPECIFICATION
104  
105 =head4 INPUT
106  
107 {
108 command => { type => 'arrayref', min => 1 },
109 stderr => { type => 'integer', min => 0 },
110 }
111  
112 =head4 OUTPUT
113  
114 {
115 type => 'hashref',
116 schema => {
117 pid => { type => 'integer', min => 1 },
118 writer => { type => 'object' },
119 reader => { type => 'object' },
120 },
121 }
122  
123 =head3 MESSAGES
124  
125 Key Meaning Resolution
126 args.invalid command or stderr is missing pass them
127 process.spawn the program could not start check that it exists and runs
128 process.inherit Windows refused a handle flag see the error text
129  
130 =head3 FORMAL SPECIFICATION
131  
132 spawn(a) ⇒ ∃ c • argv(c) = a.command ∧ stdin(c) = pipe(writer) ∧ stdout(c) = pipe(reader)
133 ∧ writer ∉ handles(c) ∧ reader ∉ handles(c)
134  
135 =head3 PSEUDOCODE
136  
137 if not Windows:
138 open3 the command (it marks the parent's ends close-on-exec)
139 else:
140 make two pipes, and mark the parent's ends non-inheritable
141 save STDIN, STDOUT, STDERR; point them at the child's ends and stderr
142 start the command without waiting; restore the standard handles
143 close the child's ends in this process
144 return pid, writer, reader
145  
146 =cut
147  
148 184 ▶sub spawn {
Subroutine spawn: called CC=3 SCAR=11.1
Pod documented
149 184 my $args = named(\@_, {
150 command => { type => 'arrayref', min => 1 },
151 stderr => { type => 'integer', min => 0 },
152 }, 'Process::spawn');
153  
154 184 my @command = @{ $args->{command} };
155 184 my ($pid, $writer, $reader);
156  
157 184 ▶ if ($IS_WINDOWS) {
Branch: 1 branch
BranchTrueFalseTotal
if ($IS_WINDOWS) { } 0 184 184
158 0 ($pid, $writer, $reader) = _spawn_windows(\@command, $args->{stderr});
159 } else {
160 184 $pid = eval { IPC::Open3::open3($writer, $reader, '>&' . $args->{stderr}, @command) };
161 184 ▶ throw('process.spawn', { program => $command[0], error => _reason($@) }) unless $pid;
Branch: 1 branch
BranchTrueFalseTotal
unless $pid 1 183 184
162 }
163 183 $writer->autoflush(1);
164  
165 183 return { pid => $pid, writer => $writer, reader => $reader };
166 }
167  
168 =head2 reap
169  
170 Purpose: wait for a child to exit, stopping it if it does not.
171  
172 Args: C<pid>, optional C<grace> (seconds to wait before stopping it; default
173 C<$GRACE_SECONDS>).
174  
175 Returns: a hashref: C<status> (exit status, or -1 when the child had already
176 been reaped), C<signal> (the signal that ended it, or 0) and C<killed> (1 if
177 C<reap> had to stop it).
178  
179 Side Effects: waits up to C<grace> seconds, then sends SIGTERM, waits up to
180 C<$TERM_SECONDS> more, then sends SIGKILL. On Windows it sends SIGKILL
181 (TerminateProcess) straight away, since Perl delivers SIGTERM there as a
182 console Ctrl-Break. Sets C<$?>.
183  
184 Usage:
185  
186 close $child->{writer};
187 close $child->{reader};
188 my $end = App::FileSync::Process::reap(pid => $child->{pid});
189  
190 =head3 EXAMPLE
191  
192 my $end = App::FileSync::Process::reap(pid => $pid, grace => 1);
193 warn "the child would not exit\n" if $end->{killed};
194  
195 =head3 API SPECIFICATION
196  
197 =head4 INPUT
198  
199 {
200 pid => { type => 'integer', min => 1 },
201 grace => { type => 'number', min => 0, optional => 1 },
202 }
203  
204 =head4 OUTPUT
205  
206 {
207 type => 'hashref',
208 schema => {
209 status => { type => 'integer', min => -1 },
210 signal => { type => 'integer', min => 0 },
211 killed => { type => 'integer', memberof => [ 0, 1 ] },
212 },
213 }
214  
215 =head3 MESSAGES
216  
217 Key Meaning Resolution
218 args.invalid no pid given pass it
219  
220 =head3 FORMAL SPECIFICATION
221  
222 exits(c) within grace ⇒ killed! = 0 ∧ status! = exit(c)
223 ¬ exits(c) within grace ⇒ killed! = 1 ∧ c ∉ processes'
224  
225 =head3 PSEUDOCODE
226  
227 wait up to grace seconds for the child to exit
228 if it has not:
229 send TERM and wait up to TERM_SECONDS (not on Windows)
230 if it still has not: send KILL and wait for it
231 return its exit status and signal, and whether it was stopped
232  
233 =cut
234  
235 183 ▶sub reap {
Subroutine reap: called CC=8 SCAR=23.4
Pod documented
236 183 my $args = named(\@_, {
237 pid => { type => 'integer', min => 1 },
238 grace => { type => 'number', min => 0, optional => 1 },
239 }, 'Process::reap');
240  
241 183 my $pid = $args->{pid};
242 183 my $killed = 0;
243  
244 183 ▶ unless (_wait_for($pid, $args->{grace} // $GRACE_SECONDS)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_wait_for($pid, $args->{"grace"} // $App::FileSync::Process::GRACE_SECONDS)) 2 181 183
Condition66%2/3
$args->{"grace"} // $App::FileSync::Process::GRACE_SECONDS
l!l&&r!l&&!r
21810
MC/DC0%0/2
$args->{"grace"} // $App::FileSync::Process::GRACE_SECONDS
$args->{"grace"} $App::FileSync::Process::GRACE_SECONDS
Truth table66%2/3
A // B
A= $args->{"grace"}B= $App::FileSync::Process::GRACE_SECONDS
ABresult
1X1
011
000
245 2 $killed = 1;
246 # Windows has no polite stop: Perl turns TERM into a console Ctrl-Break
247 # event, which can reach other processes on the console. KILL there is
248 # TerminateProcess, for that child alone.
249 2 ▶ CORE::kill('TERM', $pid) unless $IS_WINDOWS;
Branch: 1 branch
BranchTrueFalseTotal
unless $IS_WINDOWS 2 0 2
250 2 ▶ unless (!$IS_WINDOWS && _wait_for($pid, $TERM_SECONDS)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (not $IS_WINDOWS and _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)) 0 2 2
Condition33%1/3
not $IS_WINDOWS and _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)
!ll&&!rl&&r
002
MC/DC0%0/2
not $IS_WINDOWS and _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)
not $IS_WINDOWS _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)
Truth table33%1/3
not(A) and B
A= not $IS_WINDOWSB= _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)
ABresult
0X0
100
111
251 0 CORE::kill('KILL', $pid);
252 0 waitpid($pid, 0);
253 }
254 }
255  
256 183 my $status = $?;
257 return {
258 183 ▶ status => $status == $NO_CHILD ? $NO_CHILD : $status >> $EXIT_SHIFT,
Branch: 2 branches
BranchTrueFalseTotal
$status == $NO_CHILD ? : 0 183 183
$status == $NO_CHILD ? : 0 183 183
259 signal => $status == $NO_CHILD ? 0 : $status & $SIGNAL_MASK,
260 killed => $killed,
261 };
262 }
263  
264 # _wait_for
265 # Purpose: poll for a child's exit for a limited time.
266 # Entry: $pid is a child of this process; $seconds >= 0.
267 # Exit: returns 1 once the child is reaped (or was already gone),
268 # 0 if it is still running when the time is up.
269 # Side effects: reaps the child, setting $?.
270 185 ▶sub _wait_for :Private {
Subroutine _wait_for: called CC=4 SCAR=14.0
271 185 my ($pid, $seconds) = @_;
272  
273 185 my $deadline = Time::HiRes::time() + $seconds;
274 185 while (1) {
275 5075 my $reaped = waitpid($pid, WNOHANG);
276 5075 ▶ return 1 if $reaped == $pid || $reaped == $NO_CHILD;
Branch: 1 branch
BranchTrueFalseTotal
if $reaped == $pid or $reaped == $NO_CHILD 183 4892 5075
Condition66%2/3
$reaped == $pid or $reaped == $NO_CHILD
l!l&&r!l&&!r
18304892
MC/DC50%1/2
$reaped == $pid or $reaped == $NO_CHILD
$reaped == $pid $reaped == $NO_CHILD
Truth table66%2/3
A or B
A= $reaped == $pidB= $reaped == $NO_CHILD
ABresult
1X1
011
000
277 4892 ▶ return 0 if Time::HiRes::time() >= $deadline;
Branch: 1 branch
BranchTrueFalseTotal
if &Time::HiRes::time() >= $deadline 2 4890 4892
278 4890 Time::HiRes::sleep($POLL_SECONDS);
279 }
280 0 return 0;
281 327 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
282  
283 # _spawn_windows
284 # Purpose: start a child on Windows without it inheriting our pipe ends.
285 # Entry: $command is the argv; $stderr a file descriptor.
286 # Exit: returns ($pid, $writer, $reader).
287 # Side effects: starts the process. STDIN, STDOUT and STDERR point at the
288 # child's handles while it starts (that is how a Windows child
289 # is given them) and are restored before returning, even when
290 # the start fails. This is what IPC::Open3 does on Windows,
291 # plus the inheritance flags it leaves set.
292 0 ▶sub _spawn_windows :Private {
Subroutine _spawn_windows: not called CC=6 SCAR=37.4
293 0 my ($command, $stderr) = @_;
294  
295 0 pipe(my $child_in, my $writer);
296 0 pipe(my $reader, my $child_out);
297 0 _no_inherit($_) for $writer, $reader;
298  
299 0 STDOUT->flush();
300 0 STDERR->flush();
301 0 my @restore = (
302 _point(\*STDIN, '<', $child_in),
303 _point(\*STDOUT, '>', $child_out),
304 _point(\*STDERR, '>', $stderr),
305 );
306  
307 0 my $pid = do {
308 0 local $!;
309 0 my $started = eval { CORE::system(1, @{$command}) }; # 1 == P_NOWAIT
310 0 ▶ my $error = $@ || "$!";
Condition0%0/3
$@ || "$!"
l!l&&r!l&&!r
000
MC/DC0%0/2
$@ || "$!"
$@ "$!"
Truth table0%0/3
A || B
A= $@B= "$!"
ABresult
1X1
011
000
311 0 $_->() for reverse @restore;
312 0 ▶ throw('process.spawn', { program => $command->[0], error => _reason($error) })
Branch: 1 branch
BranchTrueFalseTotal
unless $started and $started > 0 0 0 0
Condition0%0/3
$started and $started > 0
!ll&&!rl&&r
000
MC/DC0%0/2
$started and $started > 0
$started $started > 0
Truth table0%0/3
A and B
A= $startedB= $started > 0
ABresult
0X0
100
111
313 unless $started && $started > 0;
314 0 $started;
315 };
316  
317 0 CORE::close($child_in);
318 0 CORE::close($child_out);
319  
320 0 return ($pid, $writer, $reader);
321 327 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
322  
323 # _point
324 # Purpose: point a standard handle somewhere else for a while.
325 # Entry: $handle is STDIN, STDOUT or STDERR; $mode '<' or '>';
326 # $target a handle or a file descriptor.
327 # Exit: returns a coderef that puts $handle back as it was.
328 # Side effects: dups $handle aside (not inheritable, so the child does not
329 # keep this process's own output open), then dups $target onto it.
330 0 ▶sub _point :Private {
Subroutine _point: not called CC=5 SCAR=34.0
331 0 my ($handle, $mode, $target) = @_;
332  
333 # Already there (the server's stderr is usually ours): reopening a handle
334 # as a dup of its own descriptor would close it first.
335 0 my $current = fileno $handle;
336 0 ▶ return sub { 1 } if !ref $target && defined $current && $target == $current;
Subroutine __ANON__: not called CC=1 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
if not ref $target and defined $current and $target == $current 0 0 0
Condition0%0/6
not ref $target and defined $current and $target == $current
!ll&&!rl&&r
000
not ref $target and defined $current
!ll&&!rl&&r
000
MC/DC0%0/3
not ref $target and defined $current and $target == $current
not ref $target defined $current $target == $current
Truth table0%0/4
not(A) and B and C
A= not ref $targetB= defined $currentC= $target == $current
ABCresult
0XX0
10X0
1100
1111
337  
338 0 my $saved;
339 0 ▶ if (defined fileno $handle) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined &App::FileSync::Process::fileno($handle)) 0 0 0
340 0 open $saved, "$mode&", $handle;
341 0 _no_inherit($saved);
342 }
343 0 open $handle, "$mode&", $target;
344  
345 0 ▶ return sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
346 0 ▶ if ($saved) {
Branch: 1 branch
BranchTrueFalseTotal
if ($saved) { } 0 0 0
347 0 open $handle, "$mode&", $saved;
348 0 CORE::close($saved);
349 } else {
350 0 CORE::close($handle);
351 }
352 0 };
353 327 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
354  
355 # _no_inherit
356 # Purpose: keep a child from inheriting a handle (Windows only).
357 # Entry: $fh is an open Perl filehandle.
358 # Exit: returns 1.
359 # Side effects: clears HANDLE_FLAG_INHERIT on the OS handle; raises
360 # process.inherit if Windows refuses.
361 0 ▶sub _no_inherit :Private {
Subroutine _no_inherit: not called CC=4 SCAR=30.0
362 0 my ($fh) = @_;
363  
364 0 require Win32API::File;
365 0 my $handle = Win32API::File::GetOsFHandle($fh);
366 0 ▶ my $ok = $handle && $handle != Win32API::File::INVALID_HANDLE_VALUE()
Condition0%0/6
$handle && $handle != Win32API::File::INVALID_HANDLE_VALUE() && Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0)
!ll&&!rl&&r
000
$handle and $handle != Win32API::File::INVALID_HANDLE_VALUE()
!ll&&!rl&&r
000
MC/DC0%0/3
$handle && $handle != Win32API::File::INVALID_HANDLE_VALUE() && Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0)
$handle $handle != Win32API::File::INVALID_HANDLE_VALUE() Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0)
Truth table0%0/4
A and B && C
A= $handleB= $handle != Win32API::File::INVALID_HANDLE_VALUE()C= Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0)
ABCresult
0XX0
10X0
1100
1111
367 && Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0);
368 0 ▶ throw('process.inherit', { error => "$^E" }) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 0 0 0
369  
370 0 return 1;
371 327 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
372  
373 # _reason
374 # Purpose: the text of a failed start, without IPC::Open3's prefixes.
375 # Entry: $error is $@ or $! text.
376 # Exit: returns the reason, e.g. "No such file or directory".
377 # Side effects: none.
378 1 ▶sub _reason :Private {
Subroutine _reason: called CC=1 SCAR=0.0
379 1 my ($error) = @_;
380  
381 1 $error = "$error";
382 1 $error =~ s/\Aopen3: //;
383 1 $error =~ s/\AIO::Pipe: Can't spawn-NOWAIT: //;
384 1 $error =~ s/\Aexec of .*? failed: //s;
385 1 $error =~ s/ at \S+ line \d+\.?\s*\z//s;
386 1 chomp $error;
387 1 return $error;
388 327 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
389  
390 327 1;
391  
392 __END__
« blib/lib/App/FileSync/Transport/SSH.pm ↑ Summary blib/lib/App/FileSync/Merge.pm »