diff options
Diffstat (limited to 'Master/tlpkg/installer/perllib/Win32/Job.pm')
-rw-r--r-- | Master/tlpkg/installer/perllib/Win32/Job.pm | 370 |
1 files changed, 0 insertions, 370 deletions
diff --git a/Master/tlpkg/installer/perllib/Win32/Job.pm b/Master/tlpkg/installer/perllib/Win32/Job.pm deleted file mode 100644 index 3350f76400d..00000000000 --- a/Master/tlpkg/installer/perllib/Win32/Job.pm +++ /dev/null @@ -1,370 +0,0 @@ -package Win32::Job; - -use strict; -use base qw(DynaLoader); -use vars qw($VERSION); - -$VERSION = '0.01'; - -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 |