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; nested in the job of kill_with_parent, which needs Windows 8). nice and rlimit are mapped to them, approximately: nice from this process's class to the class whose nice value is nearest (10 and up idle, 1 to 9 below_normal, -1 to -9 above_normal, -10 and below high, never realtime); 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_priority and win_job are unsupported.

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).

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.