NAME

Proc::Spawner - start children with posix_spawn(3) and run the one event loop (EXPERIMENTAL)

SYNOPSIS

my $pid = Proc::Spawner::start('/bin/ls', ['ls', '-l'], undef, { 1 => fileno $w, 3 => undef },
                               chdir => '/tmp', sigdefault => ['PIPE'], on_exit => sub { ... });
Proc::Spawner::wait_until(sub { $done });

# the raw call, without the loop:
my $pid = Proc::Spawner::spawn('ls', ['ls', '-l'], undef,
                            [[dup2 => fileno($w), 1], [close => 3], [chdir => '/tmp']],
                            {search => 1, sigdefault => [POSIX::SIGPIPE()]})
  // die "spawn: $!";

DESCRIPTION

The comments at the top of the module describe start. The loop is Proc::Spawner::Loop (since post-0.10); on_read, on_write, defer, poll and wait_until here are its old names, and loop() is the loop.

spawn(FILE, \@ARGV, \@ENV_OR_UNDEF, \@ACTIONS, \%ATTR, \%UNSUPPORTED) (here an alias of the XSUB __posix_spawn) calls posix_spawn (or posix_spawnp with search => 1; pidfd_spawn or pidfd_spawnp with pidfd => 1) and returns the pid (and with pidfd, the pidfd too), or the empty list with $! set. \@ENV is a list of "NAME=value" strings; undef passes environ.

Actions, applied in the child in order: [dup2 => FROM, TO], [close => FD], [open => FD, PATH, FLAGS, MODE], [chdir => DIR], [fchdir => FD], [closefrom => FD], [tcsetpgrp => FD] (the last four are glibc extensions).

Attributes: search; pidfd; sigdefault => [SIGNUMS] (reset to the default action in the child); sigmask => [SIGNUMS] (the child's signal mask, [] for an empty one); pgroup => PGID (0: a new group led by the child); setsid; resetids; sched => [POLICY, PRIORITY]; cgroup => FD.

Attributes posix_spawn has no option for (EXPERIMENTAL, post-0.08): sigignore => [SIGNUMS] (ignored in the child); rlimit => [[RESOURCE, SOFT, HARD], ...] (RESOURCE a number, see __rlimits() for the names; SOFT or HARD undef: as ours; 'unlimited'); nice => INCREMENT. The XSUB sets them in this process right around the call, in C, with every signal blocked, and puts them back right after. One that could not be put back is unsupported (\%UNSUPPORTED below): a hard limit lower than ours without CAP_SYS_RESOURCE; a higher nice value unless CAP_SYS_NICE or RLIMIT_NICE allows lowering it back; a CPU limit this process has used up; ignoring SIGCHLD. A signal both ignored and set to the default fails with EINVAL. On Windows sigignore is unsupported but for PIPE (no SIGPIPE there) and INT in a new process group (Ctrl-C is off there), which need nothing.

On Windows (post-0.09, decision W4) two settings of Windows' own, exact: win_priority => 'idle' | 'below_normal' | 'normal' | 'above_normal' | 'high' | 'realtime' (the child's priority class) and win_job => { ProcessMemoryLimit => BYTES, JobMemoryLimit => BYTES, PerProcessUserTimeLimit => TICKS, PerJobUserTimeLimit => TICKS, ActiveProcessLimit => N } (limits of a job of the child's own, by Windows' names and units: committed memory, user time in 100-ns ticks; with kill_with_parent on, nested in its job, which needs Windows 8). nice and rlimit are mapped to them, approximately: nice from this process's class to a class as Cygwin maps nice values (12 and up idle, 4 to 11 below_normal, -4 to 3 normal, -5 to -12 above_normal, -13 and below high, never realtime; a class's own nice value: 16, 8, 0, -8, -16, -20); rlimit AS and DATA to ProcessMemoryLimit, CPU to PerProcessUserTimeLimit, NPROC to ActiveProcessLimit (the soft value if set, else the hard one: Windows has one limit, and ends the child at it); the other resources have no counterpart and are unsupported. Where both are given, win_priority and win_job win. Elsewhere win_job is unsupported, and win_priority (post-0.12) is mapped to nice: the increment from this process's nice value to the class's (above), so win_priority => 'idle' from nice 0 is nice => 16, with nice's limits; nice, if given, wins; an unknown class fails with EINVAL.

Without posix_spawn (Makefile.PL found none, or PROC_SPAWNER_MISSING=posix_spawn), spawn forks and execs, in C, with nothing in between, and does every other setting around the call; then setsid, pgroup => 0, tcsetpgrp, sched and cgroup are unsupported. Where there is no fork either (Windows with posix_spawn masked, OS/2, VMS), the redirections are delegated to Run 0.07, whose start applies them around Perl's own system { FILE } 1, ARGV; the arguments go to Perl as they are (on Windows Perl's command line does not yet quote them as the child parses them back); the child sees fds 0-2 only there; at most 64 children at once ($Proc::Spawner::PRIMITIVE says which primitive is used).

%Proc::Spawner::WINDOWS (Windows only, EXPERIMENTAL) says how every child is started there; it is read at each call, so local changes it for one call:

new_group => 'auto' (the default since post-0.12)

Whether the child is in a process group of its own, where Windows turns Ctrl-C off. 'auto': only a child that would have SIGINT ignored on POSIX (sigignore has INT, or $SIG{INT} is 'IGNORE' here and sigdefault does not have INT; so Proc::ShellSpawn's background jobs, not its foreground commands); 1: every child (the default until 0.12); 0: none. pgroup => 0 gives a child a group of its own as well. A child in this process's group gets a Ctrl-C at the console itself, as a POSIX child in the foreground process group gets SIGINT, and handles it or dies of it; one in a group of its own does not (unless it turns Ctrl-C back on for itself, as perl.exe does by its source). Perl's own spawn does the same: system LIST's child stays in Perl's group, system 1, ...'s gets one of its own.

kill_with_parent => 0 (default off since post-0.12)

On: the child is in a job object whose only handle is this process's, and Windows ends everything in the job (the child, and whatever it starts) when this process ends, however it ends: nothing started here outlives this process, and the children end by TerminateProcess, with no chance to clean up (also right after a Ctrl-C they got themselves). Off (as Perl's own spawn, which makes no job, and as on POSIX): a child still running when this process ends keeps running.

new_console => 1 (default on)

A child with none of fds 0-2 gets a console of its own, as with Perl's own spawn; off: it shares this process's, with no standard handles.

Through Perl's own spawn ($Proc::Spawner::PRIMITIVE system1) none of them applies: Perl's own choices hold there (every child in a group of its own, no job).

What the defaults cost, on Windows (none of it tried with a real Ctrl-C: under Wine it was checked that each child gets the process group it should, as Windows records it, and that a child outlives its parent):

  • A child still running when this process ends keeps running: after this process is killed or crashes, after a Ctrl-C that ends it (Perl runs no END blocks then), and after it exits without waiting for children of spawn or start (Proc::ShellSpawn waits for its background jobs at exit). So it is on POSIX; on Windows, moreover, a file such a child keeps open cannot be deleted (a temporary directory may not be removed), and it may go on writing to the console and reading keys meant for the next program.

  • Ctrl-C reaches only processes on this console: a child with a console of its own (new_console), a GUI program, or a detached one does not get it, and goes on after this process has ended. On POSIX a child in the foreground process group gets SIGINT whatever it is.

  • Perl's kill sends TERM and BREAK as a Ctrl-Break event to the process group whose id is the pid, so they reach only a child in a group of its own; INT is a Ctrl-C event, which a child in a group of its own has off. A child in this process's group (since post-0.12, every child that does not ignore SIGINT; until then none) can be ended only by kill KILL (TerminateProcess), unless it is given a group of its own (pgroup => 0, or new_group => 1). What Windows does with such an event for a pid that leads no group was not checked.

  • Through Perl's own spawn (system1) every child is in a group of its own: Ctrl-C reaches none of them, and none is killed, so after a Ctrl-C they all go on, the command this process was waiting for too.

Not a cost of these settings, as no setting changes it: Ctrl-Break at the console reaches every process on it, also one in a group of its own (Windows turns only Ctrl-C off there), so it ends the background jobs too (by Windows' documentation; not tried).

reaped(PID): after waiting yourself for a child of spawn. On Windows it releases the process handle kept for the exit code; elsewhere it does nothing. The loop calls it for the children of start.

\%UNSUPPORTED (optional) says, per option, what a port that lacks it (a future Windows one) does: 'drop' it or 'fail'. Options not listed take the value in %Proc::Spawner::UNSUPPORTED, where '*' covers the rest (default 'fail', which fails the call with ENOTSUP). It applies with posix_spawn too, to the extensions this build's libc lacks: chdir, fchdir, closefrom, tcsetpgrp, pidfd and cgroup. They are functions, not macros, so Makefile.PL finds them by compiling a call to each (in glibc they came with 2.29, 2.29, 2.34, 2.35, 2.39 and 2.39). A dropped pidfd returns only the pid.

LIMITATIONS

Process-wide state is flipped for a while, so these parts are bullet-proof only in non-threaded execution: the umask, set around start's call (umask => N), and the SIGCHLD action, taken over while wait_until runs. poll() (EXPERIMENTAL) runs what is ready without waiting; it does nothing inside wait_until or a callback. Proc::ShellSpawn calls it from a deferred SIGCHLD handler of its own between run() calls while background jobs remain; while that handler is installed, the program's own sleep and select return early whenever a child ends. The signal actions and resource limits set around the call (sigignore, rlimit) are the process's too; on Linux nice and the signal mask are per thread. A memory limit lower than what this process uses makes glibc's posix_spawn fail with ENOMEM. Without /proc (FreeBSD and the like), Perl's own writes into a pipe it was given by the caller (not one of the graph's) are blocking writes of PIPE_BUF bytes once select says the pipe is writable: another writer filling the pipe in between makes Perl wait, and can hang the loop when the reader waits on Perl (known issue X32 in doc/pspawn-known-issues.md; not observed). Only Linux with glibc 2.39 has been tested (and Windows under Wine).

AUTHOR

Ilya Zakharevich

COPYRIGHT AND LICENCE

Copyright (C) 2026 by Ilya Zakharevich

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.22.2 or, at your option, any later version of Perl 5 you may have available.