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.