NAME
Parallel::Jobs - run jobs in parallel with access to their stdout and stderr
SYNOPSIS
use Parallel::Jobs;
use Parallel::Jobs qw(start_job watch_jobs);
$pid = Parallel::Jobs::start_job('cmd', ... args ...);
$pid = Parallel::Jobs::start_job('cmd ... args ...');
$pid = Parallel::Jobs::start_job({ stdin_file => filename |
stdin_handle => *HANDLE,
stdout_handle => *HANDLE |
stdout_capture => 1,
stderr_handle => *HANDLE |
stderr_capture => 1 },
... cmd as above ...);
($pid, $event, $data) = Parallel::Jobs::watch_jobs();
($pid, $event, $data) = Parallel::Jobs::watch_jobs({nohang => 1});DESCRIPTION
The Parallel::Jobs module allows you to run multiple jobs in parallel with fine-grained control over their stdin, stdout and stderr. That control is the biggest difference between this module and others such as Parallel::ForkManager.
You can specify the command to run as a single string or as a list specifying the command and its arguments, as in IPC::Open3. If your version of IPC::Open3 supports '-' as the command, Parallel::Jobs::start_job() will fork to a Perl child in a manner analogous to open(FOO, "-|").
If your first argument is a reference to a hash, it can specify the parameters shown above. By default, stdin for each job is set to /dev/null and stdout and stderr are set to the stdout and stderr of the calling process.
If you specify stdin_handle, stdout_handle or stderr_handle, the handle will be copied the original handle will thus not be modified.
Each time you call Parallel::Jobs::watch_jobs(), it will return the process ID of the job with which an event has occured, the event type, and the data associated with that event. If there are no more jobs to watch, watch_jobs() will return undef. If you want to poll for pending events without hanging if there are none currently available, specify a hash with the key "nohang" set to a true value.
The relevant events are as follows:
- EXIT
-
The indicated process has exited. The returned data is the value of $? from the exited process. The process has already been waited for (i.e., you don't need to do any cleanup on it).
- STDOUT
-
Output has been received on stdout. The returned data is the output that was received, or an empty string if EOF was received.
- STDERR
-
Output has been received on stderr. The returned data is the output that was received, or an empty string if EOF was received.
Note that it is possible to receive STDOUT or STDERR events from a process after its EXIT event, i.e., you may receive an EXIT event before you've read all of a process's output.
AUTHOR
Jonathan Kamens <jik@kamens.us>
CREDITS
This module was written and is maintained by Jonathan Kamens (originally <jik@worldwinner.com>, currently <jik@kamens.us>). In addition, the following people contributed bug fixes, enhancements, and/or useful suggestions:
COPYRIGHT AND LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.