| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
$args->{"grace"} // $App::FileSync::Process::GRACE_SECONDS
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 250 | 2 | ▶ | unless (!$IS_WINDOWS && _wait_for($pid, $TERM_SECONDS)) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
not $IS_WINDOWS and _wait_for($pid, $App::FileSync::Process::TERM_SECONDS)
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)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
$reaped == $pid or $reaped == $NO_CHILD
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
| |||||||||||||||||||||||||||||||||||||||||||
| 277 | 4892 | ▶ | return 0 if Time::HiRes::time() >= $deadline; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
$@ || "$!"
MC/DC0%0/2
$@ || "$!"
$@
"$!"
Truth table0%0/3
A || B
A= $@B= "$!"
| |||||||||||||||||||||||||||||||||||||||||||
| 311 | 0 | $_->() for reverse @restore; | |||||||||||||||||||||||||||||||||||||||||
| 312 | 0 | ▶ | throw('process.spawn', { program => $command->[0], error => _reason($error) }) | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
$started and $started > 0
MC/DC0%0/2
$started and $started > 0
$started
$started > 0
Truth table0%0/3
A and B
A= $startedB= $started > 0
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition0%0/6
not ref $target and defined $current and $target == $current
not ref $target and defined $current
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
| |||||||||||||||||||||||||||||||||||||||||||
| 337 | |||||||||||||||||||||||||||||||||||||||||||
| 338 | 0 | my $saved; | |||||||||||||||||||||||||||||||||||||||||
| 339 | 0 | ▶ | if (defined fileno $handle) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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)
$handle and $handle != Win32API::File::INVALID_HANDLE_VALUE()
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)
| |||||||||||||||||||||||||||||||||||||||||||
| 367 | && Win32API::File::SetHandleInformation($handle, Win32API::File::HANDLE_FLAG_INHERIT(), 0); | ||||||||||||||||||||||||||||||||||||||||||
| 368 | 0 | ▶ | throw('process.inherit', { error => "$^E" }) unless $ok; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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__ | ||||||||||||||||||||||||||||||||||||||||||