NAME¶
Lintian::Command::Simple - Run commands without pipes
SYNOPSIS¶
use Lintian::Command::Simple qw(background rundir);
Lintian::Command::Simple::rundir ('./some-dir/', 'echo', 'hello world');
# Start a command in the background:
Lintian::Command::Simple::background('sleep', 10);
print wait() > 0 ? 'success' : 'failure';
DESCRIPTION¶
Lintian::Command::Simple allows running commands with the capability of running
them "in the background" (asynchronously.)
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.
- rundir(dir, command, argument [, ...])
- Executes the given "command" with the given arguments and in
"dir" returns the status code as one would see it from a shell
script.
Being fair, the only advantage of this function over the
CORE::system() function is the way the return status is reported
and the chdir support.
- background(command, argument [, ...])
- Executes the given "command" with the given arguments
asynchronously and returns the process id of the child process.
A return value of -1 indicates an error. This can either be a problem when
calling CORE::fork() or when trying to run another command before
calling wait() to reap the previous command.
- wait_any (hashref[, nohang])
- When starting multiple processes asynchronously, it is common to wait
until the first is done. While the CORE::wait() function is usually
used for that very purpose, it does not provide the desired results when
the processes were started via the OO interface.
To help with this task, wait_any() 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).
Under this mode, wait_any() 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 $? as
usual.
The results and return value are undefined when under this mode
wait_any() "accidentally" reaps a process not listed in
the hashref.
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.
Whenever waitpid() would return -1, wait_any() returns undef
or a null value so that it is safe to:
while($cmd = wait_any(\%hash)) { something; }
The same is true whenever the hash reference points to an empty hash.
If "nohang" 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.
- kill_all(hashref[, signal])
- In a similar way to wait_any(), it is possible to pass a hash
reference to kill_all(). It will then kill all of the processes
(default signal being "TERM") followed by a reaping of the
processes. All reaped processes (and their values) will be removed from
the set.
Any entries remaining in the hashref are processes that did not terminate
(or did not terminate yet).
TODO¶
Provide the necessary methods to modify the environment variables of the
to-be-executed commands. This would let us drop "system_env" (from
Lintian::Util) and make "run" more useful.
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.
CAVEATS¶
Combining asynchronous jobs (e.g. via Lintian::Command) and calls to
wait_any() can lead to unexpected results.
AUTHOR¶
Originally written by Raphael Geissert <atomo64@gmail.com> for
Lintian.