NAME
Run - Perl extension for to start programs in background
SYNOPSIS
use Run;
$pid = spawn 'long_running_task', 'arg1', 'arg2' or die "spawn: $!";
do_something_else();
waitpid($pid,0);
DESCRIPTION
The subroutine spawn is equivalent to the builtin system (see "system LIST" in perlfunc) with the exceptions that the program is started in background, and the return the pid of the kid.
Returns 0 on failure, $! should contain the reason for the failure.
EXPORT
Exports spawn by default.
AUTHOR
Ilya Zakharevich <ilya@math.ohio-state.edu
TODO
What to do with errs in or? Should they be cleared?
COMMANDS AND STATUS
new_system(PROG, ARGS...) and new_spawn(...) always run PROG with ARGS, as system { PROG } PROG, ARGS does: a single element is a program name, never a shell command (unlike the exported spawn, which keeps the builtin system's meaning of a single string).
run returns true iff the command succeeded. Every new_system leaves its $? in $data->{result}, 0 included, or -1 when nothing was started (the program or a redirection target could not be opened; the reason is in errs). So after new_and, new_or, new_chain and new_pipeline it holds the status sh would give. new_chain succeeds iff its last command does, as in sh. new_readpipe and new_readpipe_split wait for their kid and leave its status there too; the output keeps its trailing newlines.
PIPELINES
new_pipeline(CMD1, CMD2, ...) is CMD1 | CMD2 | .... An element that is a simple command (new_system or new_spawn, possibly under new_env and new_redir) is spawned with the pipe ends as fds 0 and 1: after the outer redirections and before its own, as in sh.
Any other element (new_and, new_or, new_chain, a nested new_pipeline) runs in this process, after every other element has started, with the pipe ends applied to each command it starts. This process keeps its write end open until the element's last command has ended, so in { A || B } | C the reader sees one stream: B starts (or not) when A has ended, and C sees end of file only after that. Before running it, this process closes every other pipe end, so readers see end of file and writers get SIGPIPE as in sh.
Only one element can run in this process (the last such one). Where fork exists, the others run in forked copies of this process, which exit with the status of their last command (255 if it died); their messages, and the message of a die, come back into errs. With $Run::Forkless a second such element is refused. If the element run in this process dies, the pipeline closes its pipes, reaps its kids and then rethrows.
The pipeline succeeds iff its last element does; $data->{result} is the last element's status, or -1 if it did not start or nothing could be started (a pipe could not be created, a refused element). An element that did not start is reported in errs and the others run on. The pipeline cannot itself run under spawn (as a new_pipe element).
REDIRECTIONS
new_redir and run({redir => ...}) take either a hash {FD => SPEC}, applied in increasing FD, or an array [FD => SPEC, ...], applied in the order given. SPEC is {filehandle => FH}, {filename => STRING} or {filename => NAME, mode => OP}. As in sh, redirections are applied left to right, outer new_redir first, so [1 => {filename => '>f'}, 2 => {filename => '>&1'}] is >f 2>&1, and the reverse order is 2>&1 >f.
{filehandle => FH},{filename => '>&N'}(or'>&=N','<&N')-
FD becomes a copy of fd
fileno FH(or N) as it is at that point, so an earlier redirection of that fd counts. {filename => '>&-'}(or'<&-')-
FD is closed in the kid.
{filehandle => FH, pin => 1}-
FD becomes a copy of FH's file, even when
fileno FHis itself one of the target fds: FH is first copied above every target. This is the safe way to pass a file the caller opened, or a pipe end. {filename => NAME, mode => OP}-
NAME is the file's name as it is (
-,&1and leading blanks are literal), opened as sh's OP does:<reads,>and>|create or truncate,>>appends,<>reads and writes, creating the file but not truncating it. FD becomes a copy of that file. Use this form for names that come from elsewhere. - any other
{filename => STRING} -
STRING is opened with 2-argument
open; FD becomes a copy of that file.
Where fork exists, the redirections are applied in the kid between fork and exec, and the parent's fd table is never changed. Where it does not (forkless, see below), they are applied in the parent around a spawn that inherits the fd table, and afterwards every target fd is put back as it was: open on the same file with the same close-on-exec flag, or closed.
FORKLESS
On OS/2, Win32 and VMS $Run::Forkless is true, and Run starts every process with one primitive, Run::spawn_nowait(LIST_FLAG, \@ARGS, \@ERRS): like spawnvp(P_NOWAIT), the kid gets this process's fd table as it is (except close-on-exec fds), and the pid is returned (undef, with a message, if nothing started). There it is system 1, .... Nothing else in Run forks; new_system is spawn_nowait followed by waitpid.
On Unix, which has no spawn, the primitive is emulated by fork and exec with nothing in between. Setting $Run::Forkless (local is fine; $Run::Wraparound is the old name, and either one set means forkless) runs the forkless code paths there, which is how they are tested. What the emulation does not reproduce: on Win32 a kid sees only fds 0..2, and the close-on-exec flag is a Unix notion.
Limits of the parent-side way: other threads see the redirected fds while the kid starts; and outside Linux the close-on-exec flag of a target fd is inferred, not read (Perl cannot look at it without changing it), so a fd opened by C code with the flag set comes back without it. Only the Unix ways have been tested; on Win32 a kid sees only fds 0..2.
NOTES
open FH, ">&=FH1" creates a "naughty" copy of FH1. Closing FH will invalidate FH1 -- unless another Perl handle also uses that fd: PerlIO counts the handles of each fd. Such an open also sets or clears close-on-exec on that fd according to $^F.
SEE ALSO
perl(1).