.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Lintian::Command::Simple 3"
.TH Lintian::Command::Simple 3 "2020-08-20" "Lintian v2.90.0~bpo10+1" "Debian Package Checker"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lintian::Command::Simple \- Run commands without pipes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Lintian::Command::Simple qw(wait_any);
\&
\&    my %pid_info;
\&    my $pid = fork() // die("fork: $!");
\&    exec(\*(Aqdo\*(Aq, \*(Aqsomething\*(Aq) if $pid == 0;
\&    $pid_info{$pid} = "A useful value associated with $pid";
\&
\&    my ($termiated_pid, $value) = wait_any(\e%pid_info);
\&    ...;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lintian::Command::Simple allows running commands with the capability of
running them \*(L"in the background\*(R" (asynchronously.)
.PP
Pipes are not handled at all, except for those handled internally by
the shell. See 'perldoc \-f exec's note about shell metacharacters.
If you want to pipe to/from Perl, look at Lintian::Command instead.
.IP "wait_any (hashref[, nohang])" 4
.IX Item "wait_any (hashref[, nohang])"
When starting multiple processes asynchronously, it is common to wait
until the first is done. While the \fBCORE::wait()\fR function is usually
used for that very purpose, it does not provide the desired results
when the processes were started via the \s-1OO\s0 interface.
.Sp
To help with this task, \fBwait_any()\fR can take a hash ref where the key
of each entry is the pid of that command.  There are no requirements
for the value (which can be used for any application specific
purpose).
.Sp
Under this mode, \fBwait_any()\fR waits until any child process is done.
The key (and value) associated the pid of the reaped child will then
be removed from the hashref.  The exitcode of the child is available
via \f(CW$?\fR as usual.
.Sp
The results and return value are undefined when under this mode
\&\fBwait_any()\fR \*(L"accidentally\*(R" reaps a process not listed in the hashref.
.Sp
The return value in scalar context is value associated with the pid of
the reaped processed.  In list context, the pid and value are returned
as a pair.
.Sp
Whenever \fBwaitpid()\fR would return \-1, \fBwait_any()\fR returns undef or a null
value so that it is safe to:
.Sp
.Vb 1
\&    while($cmd = wait_any(\e%hash)) { something; }
.Ve
.Sp
The same is true whenever the hash reference points to an empty hash.
.Sp
If \f(CW\*(C`nohang\*(C'\fR is also given, wait_any will attempt to reap any child
process non-blockingly.  If no child can be reaped, it will
immediately return (like there were no more processes left) instead of
waiting.
.IP "kill_all(hashref[, signal])" 4
.IX Item "kill_all(hashref[, signal])"
In a similar way to \fBwait_any()\fR, it is possible to pass a hash
reference to \fBkill_all()\fR.  It will then kill all of the processes
(default signal being \*(L"\s-1TERM\*(R"\s0) followed by a reaping of the processes.
All reaped processes (and their values) will be removed from the set.
.Sp
Any entries remaining in the hashref are processes that did not
terminate (or did not terminate yet).
.SH "NOTES"
.IX Header "NOTES"
Unless specified by prefixing the package name, every reference to a
function/method in this documentation refers to the functions/methods
provided by this package itself.
.SH "CAVEATS"
.IX Header "CAVEATS"
Combining asynchronous jobs (e.g. via Lintian::Command) and calls to
\&\fBwait_any()\fR can lead to unexpected results.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Raphael Geissert <atomo64@gmail.com> for Lintian.