Job(3) User Contributed Perl Documentation Job(3)NAME
Win32::Job - Run sub-processes in a "job" environment
SYNOPSIS
use Win32::Job;
my $job = Win32::Job->new;
# Run 'perl Makefile.PL' for 10 seconds
$job->spawn($Config{perlpath}, "perl Makefile.PL");
$job->run(10);
PLATFORMS
Win32::Job requires Windows 2000 or later. Windows 95, 98, NT, and Me
are not supported.
DESCRIPTION
Windows 2000 introduced the concept of a "job": a collection of
processes which can be controlled as a single unit. For example, you
can reliably kill a process and all of its children by launching the
process in a job, then telling Windows to kill all processes in the
job. Win32::Job makes this feature available to Perl.
For example, imagine you want to allow 2 minutes for a process to
complete. If you have control over the child process, you can probably
just run it in the background, then poll every second to see if it has
finished.
That's fine as long as the child process doesn't spawn any child
processes. What if it does? If you wrote the child process yourself
and made an effort to clean up your child processes before terminating,
you don't have to worry. If not, you will leave hanging processes
(called "zombie" processes in Unix).
With Win32::Job, just create a new Job, then use the job to spawn the
child process. All its children will also be created in the new Job.
When you time out, just call the job's kill() method and the entire
process tree will be terminated.
Using Win32::Job
The following methods are available:
1. new()new();
Creates a new Job object using the Win32 API call
CreateJobObject(). The job is created with a default security
context, and is unnamed.
Note: this method returns "undef" if CreateJobObject() fails. Look
at $^E for more detailed error information.
2. spawn()
spawn($exe, $args, \%opts);
Creates a new process and associates it with the Job. The process
is initially suspended, and can be resumed with one of the other
methods. Uses the Win32 API call CreateProcess(). Returns the PID
of the newly created process.
Note: this method returns "undef" if CreateProcess() fails. See $^E
for more detailed error information. One reason this will fail is
if the calling process is itself part of a job, and the job's
security context does not allow child processes to be created in a
different job context than the parent.
The arguments are described here:
1. $exe
The executable program to run. This may be "undef", in which
case the first argument in $args is the program to run.
If this has path information in it, it is used "as is" and
passed to CreateProcess(), which interprets it as either an
absolute path, or a path relative to the current drive and
directory. If you did not specify an extension, ".exe" is
assumed.
If there are no path separators (either backslashes or forward
slashes), then Win32::Job will search the current directory and
your PATH, looking for the file. In addition, if you did not
specify an extension, then Win32::Job checks ".exe", ".com",
and ".bat" in order. If it finds a ".bat" file, Win32::Job will
actually call cmd.exe and prepend "cmd.exe" to the $args.
For example, assuming a fairly normal PATH:
spawn(q{c:\winnt\system\cmd.exe}, q{cmd /C "echo %PATH%"})
exefile: c:\winnt\system\cmd.exe
cmdline: cmd /C "echo %PATH%"
spawn("cmd.exe", q{cmd /C "echo %PATH%"})
exefile: c:\winnt\system\cmd.exe
cmdline: cmd /C "echo %PATH%"
2. $args
The commandline to pass to the executable program. The first
word will be "argv[0]" to an EXE file, so you should repeat the
command name in $args.
For example:
$job->spawn($Config{perlpath}, "perl foo.pl");
In this case, the "perl" is ignored, since perl.exe doesn't use
it.
3. %opts
A hash reference for advanced options. This parameter is
optional. the following keys are recognized:
cwd A string specifying the current directory of the new
process.
By default, the process shares the parent's current
directory, ".".
new_console
A boolean; if true, the process is started in a new console
window.
By default, the process shares the parent's console. This
has no effect on GUI programs which do not interact with
the console.
window_attr
Either "minimized", which displays the new window
minimized; "maximimzed", which shows the new window
maximized; or "hidden", which does not display the new
window.
By default, the window is displayed using its application's
defaults.
new_group
A boolean; if true, the process is the root of a new
process group. This process group includes all descendents
of the child.
By default, the process is in the parent's process group
(but in a new job).
no_window
A boolean; if true, the process is run without a console
window. This flag is only valid when starting a console
application, otherwise it is ignored. If you are launching
a GUI application, use the "window_attr" tag instead.
By default, the process shares its parent's console.
stdin
An open input filehandle, or the name of an existing file.
The resulting filehandle will be used for the child's
standard input handle.
By default, the child process shares the parent's standard
input.
stdout
An open output filehandle or filename (will be opened for
append). The resulting filehandle will be used for the
child's standard output handle.
By default, the child process shares the parent's standard
output.
stderr
An open output filehandle or filename (will be opened for
append). The resulting filehandle will be used for the
child's standard error handle.
By default, the child process shares the parent's standard
error.
Unrecognized keys are ignored.
3. run()
run($timeout, $which);
Provides a simple way to run the programs with a time limit. The
$timeout is in seconds with millisecond accuracy. This call blocks
for up to $timeout seconds, or until the processes finish.
The $which parameter specifies whether to wait for all processes to
complete within the $timeout, or whether to wait for any process to
complete. You should set this to a boolean, where a true value
means to wait for all the processes to complete, and a false value
to wait for any. If you do not specify $which, it defaults to true
("all").
Returns a boolean indicating whether the processes exited by
themselves, or whether the time expired. A true return value means
the processes exited normally; a false value means one or more
processes was killed will $timeout.
You can get extended information on process exit codes using the
status() method.
For example, this is how to build two perl modules at the same
time, with a 5 minute timeout:
use Win32::Job;
$job = Win32::Job->new;
$job->spawn("cmd", q{cmd /C "cd Mod1 && nmake"});
$job->spawn("cmd", q{cmd /C "cd Mod2 && nmake"});
$ok = $job->run(5 * 60);
print "Mod1 and Mod2 built ok!\n" if $ok;
4. watch()
watch(\&handler, $interval, $which);
handler($job);
Provides more fine-grained control over how to stop the programs.
You specify a callback and an interval in seconds, and Win32::Job
will call the "watchdog" function at this interval, either until
the processes finish or your watchdog tells Win32::Job to stop. You
must return a value indicating whether to stop: a true value means
to terminate the processes immediately.
The $which parameter has the same meaning as run()'s.
Returns a boolean with the same meaning as run()'s.
The handler may do anything it wants. One useful application of the
watch() method is to check the filesize of the output file, and
terminate the Job if the file becomes larger than a certain limit:
use Win32::Job;
$job = Win32::Job->new;
$job->spawn("cmd", q{cmd /C "cd Mod1 && nmake"}, {
stdin => 'NUL', # the NUL device
stdout => 'stdout.log',
stderr => 'stdout.log',
});
$ok = $job->watch(sub {
return 1 if -s "stdout.log" > 1_000_000;
}, 1);
print "Mod1 built ok!\n" if $ok;
5. status()status()
Returns a hash containing information about the processes in the
job. Only returns valid information after calling either run() or
watch(); returns an empty hash if you have not yet called them. May
be called from a watch() callback, in which case the "exitcode"
field should be ignored.
The keys of the hash are the process IDs; the values are a subhash
containing the following keys:
exitcode
The exit code returned by the process. If the process was
killed because of a timeout, the value is 293.
time
The time accumulated by the process. This is yet another
subhash containing the subkeys (i) "user", the amount of time
the process spent in user space; (ii) "kernel", the amount of
time the process spent in kernel space; and (iii) "elapsed",
the total time the process was running.
6. kill()kill();
Kills all processes and subprocesses in the Job. Has no return
value. Sets the exit code to all processes killed to 293, which
you can check for in the status() return value.
SEE ALSO
For more information about jobs, see Microsoft's online help at
http://msdn.microsoft.com/
For other modules which do similar things (but not as well), see:
1. Win32::Process
Low-level access to creating processes in Win32. See
Win32::Process.
2. Win32::Console
Low-level access to consoles in Win32. See Win32::Console.
3. Win32::ProcFarm
Manage pools of threads to perform CPU-intensive tasks on Windows.
See Win32::ProcFarm.
AUTHOR
ActiveState (support@ActiveState.com)
COPYRIGHT
Copyright (c) 2002, ActiveState Corporation. All Rights Reserved.
perl v5.14.2 2005-09-17 Job(3)
