NAME
App::FileSync::Process - start and reap a transport's child process
SYNOPSIS
use App::FileSync::Process;
my $child = App::FileSync::Process::spawn(command => [ 'ssh', 'host', 'filesync-server' ], stderr => fileno(STDERR));
print { $child->{writer} } "...\n";
close $child->{writer};
close $child->{reader};
my $end = App::FileSync::Process::reap(pid => $child->{pid});
DESCRIPTION
A transport writes to its child's standard input and reads its standard output, and relies on the child seeing end of file when the transport closes its end. That only happens once every copy of the pipe's write end is closed. IPC::Open3 marks the parent's ends close-on-exec on Unix, but on Windows it starts the child with every inheritable handle, so the child held a copy of its own stdin's write end and waited for input forever.
spawn therefore makes the parent's ends non-inheritable on Windows before starting the child, and reap never waits without limit: a child that has not exited after $GRACE_SECONDS is stopped.
FUNCTIONS
spawn
Purpose: start a child process with pipes to its standard input and output.
Args: command (the argv, never passed through a shell), stderr (a file descriptor the child's standard error goes to).
Returns: a hashref: pid, writer (to the child's standard input), reader (from its standard output). The writer is unbuffered.
Side Effects: starts the process. On Windows, briefly points this process's standard handles at the child's pipes while it starts.
Usage:
my $child = App::FileSync::Process::spawn(command => \@argv, stderr => fileno(STDERR));
EXAMPLE
my $child = App::FileSync::Process::spawn(command => [ $^X, '-pe1' ], stderr => fileno(STDERR));
print { $child->{writer} } "echo\n";
close $child->{writer};
print readline $child->{reader}; # echo
API SPECIFICATION
INPUT
{
command => { type => 'arrayref', min => 1 },
stderr => { type => 'integer', min => 0 },
}
OUTPUT
{
type => 'hashref',
schema => {
pid => { type => 'integer', min => 1 },
writer => { type => 'object' },
reader => { type => 'object' },
},
}
MESSAGES
Key Meaning Resolution
args.invalid command or stderr is missing pass them
process.spawn the program could not start check that it exists and runs
process.inherit Windows refused a handle flag see the error text
FORMAL SPECIFICATION
spawn(a) ⇒ ∃ c • argv(c) = a.command ∧ stdin(c) = pipe(writer) ∧ stdout(c) = pipe(reader)
∧ writer ¬in; handles(c) ∧ reader ¬in; handles(c)
PSEUDOCODE
if not Windows:
open3 the command (it marks the parent's ends close-on-exec)
else:
make two pipes, and mark the parent's ends non-inheritable
save STDIN, STDOUT, STDERR; point them at the child's ends and stderr
start the command without waiting; restore the standard handles
close the child's ends in this process
return pid, writer, reader
reap
Purpose: wait for a child to exit, stopping it if it does not.
Args: pid, optional grace (seconds to wait before stopping it; default $GRACE_SECONDS).
Returns: a hashref: status (exit status, or -1 when the child had already been reaped), signal (the signal that ended it, or 0) and killed (1 if reap had to stop it).
Side Effects: waits up to grace seconds, then sends SIGTERM, waits up to $TERM_SECONDS more, then sends SIGKILL. On Windows it sends SIGKILL (TerminateProcess) straight away, since Perl delivers SIGTERM there as a console Ctrl-Break. Sets $?.
Usage:
close $child->{writer};
close $child->{reader};
my $end = App::FileSync::Process::reap(pid => $child->{pid});
EXAMPLE
my $end = App::FileSync::Process::reap(pid => $pid, grace => 1);
warn "the child would not exit\n" if $end->{killed};
API SPECIFICATION
INPUT
{
pid => { type => 'integer', min => 1 },
grace => { type => 'number', min => 0, optional => 1 },
}
OUTPUT
{
type => 'hashref',
schema => {
status => { type => 'integer', min => -1 },
signal => { type => 'integer', min => 0 },
killed => { type => 'integer', memberof => [ 0, 1 ] },
},
}
MESSAGES
Key Meaning Resolution
args.invalid no pid given pass it
FORMAL SPECIFICATION
exits(c) within grace ⇒ killed! = 0 ∧ status! = exit(c)
¬ exits(c) within grace ⇒ killed! = 1 ∧ c ¬in; processes'
PSEUDOCODE
wait up to grace seconds for the child to exit
if it has not:
send TERM and wait up to TERM_SECONDS (not on Windows)
if it still has not: send KILL and wait for it
return its exit status and signal, and whether it was stopped
LIMITATIONS
On Windows, spawn is not safe to call from two threads at once: it points this process's standard handles at the child's pipes while the child starts. App::FileSync does not use threads.
A child stopped by reap does not get to clean up. The server discards temporaries it finds stale on a later session, and the lock is the operating system's, so neither outlives it for long.
AUTHOR
Nigel Horne, <njh at nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms. If you use it, please let me know.