package Win32::Job;

use strict;
use base qw(DynaLoader);
use vars qw($VERSION);

$VERSION = '0.05';

use constant WIN32s => 0;
use constant WIN9X  => 1;
use constant WINNT  => 2;

require Win32 unless defined &Win32::GetOSVersion;
my @ver = Win32::GetOSVersion;
die "Win32::Job is not supported on $ver[0]" unless (
    $ver[4] == WINNT and (
	$ver[1] > 5 or
	($ver[1] == 5 and $ver[2] > 0) or
	($ver[1] == 5 and $ver[2] == 0 and $ver[3] >= 0)
    )
);

Win32::Job->bootstrap($VERSION);

1;

__END__

=head1 NAME

Win32::Job - Run sub-processes in a "job" environment

=head1 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);

=head1 PLATFORMS

Win32::Job requires Windows 2000 or later. Windows 95, 98, NT, and Me are not
supported.

=head1 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 I<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.

=head1 Using Win32::Job

The following methods are available:

=over 4

=item 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 C<undef> if CreateJobObject() fails. Look at C<$^E>
for more detailed error information.

=item 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 C<undef> if CreateProcess() fails. See C<$^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:

=over 4

=item 1

$exe

The executable program to run. This may be C<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 F<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%"

=item 2

$args

The commandline to pass to the executable program. The first word will be
C<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.

=item 3

%opts

A hash reference for advanced options. This parameter is optional.
the following keys are recognized:

=over 4

=item cwd

A string specifying the current directory of the new process.

By default, the process shares the parent's current directory, C<.>.

=item 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.

=item window_attr

Either C<minimized>, which displays the new window minimized; C<maximimzed>,
which shows the new window maximized; or C<hidden>, which does not display the
new window.

By default, the window is displayed using its application's defaults.

=item 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).

=item 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 C<window_attr> tag instead.

By default, the process shares its parent's console.

=item 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.

=item 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.

=item 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.

=back

Unrecognized keys are ignored.

=back

=item 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 I<all> processes to
complete within the $timeout, or whether to wait for I<any> process to
complete. You should set this to a boolean, where a true value means to
wait for I<all> the processes to complete, and a false value to wait
for I<any>. If you do not specify $which, it defaults to true (C<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;

=item 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;

=item 5

status()

   status()

Returns a hash containing information about the processes in the job.
Only returns valid information I<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 C<exitcode> field should be ignored.

The keys of the hash are the process IDs; the values are a subhash
containing the following keys:

=over 4

=item exitcode

The exit code returned by the process. If the process was killed because
of a timeout, the value is 293.

=item time

The time accumulated by the process. This is yet another subhash containing
the subkeys (i) C<user>, the amount of time the process spent in user
space; (ii) C<kernel>, the amount of time the process spent in kernel space;
and (iii) C<elapsed>, the total time the process was running.

=back

=item 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.

=back

=head1 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:

=over 4

=item 1

Win32::Process

Low-level access to creating processes in Win32. See L<Win32::Process>.

=item 2

Win32::Console

Low-level access to consoles in Win32. See L<Win32::Console>.

=item 3

Win32::ProcFarm

Manage pools of threads to perform CPU-intensive tasks on Windows. See
L<Win32::ProcFarm>.

=back

=head1 AUTHOR

ActiveState (support@ActiveState.com)

=head1 COPYRIGHT

Copyright (c) 2002, ActiveState Corporation. All Rights Reserved.

=cut