NAME

Proc::Background - Generic interface to Unix and Win32 background process management

SYNOPSIS

use Proc::Background;
timeout_system('seconds', 'path_to_program', 'arg1');
my $proc = Proc::Background->new('path_to_program', 'arg1', 'arg2');
$proc->alive;
$proc->die;
$proc->wait;
$time = $proc->start_time;
$time = $proc->end_time;

DESCRIPTION

This is a generic interface to place programs in background processing on both Unix and Win32 platforms. This class lets you start, kill, wait on, retrieve exit values, and see if background processes are alive.

METHODS

new path [arg, [arg, ...]]

This creates a new background process. If the path to the program is not an asolute path, then new will attempt to find the program in the current PATH environmental variable. If anything fails, then new returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context.

pid

Returns the process ID of the created process. This value is saved even if the process has already finished.

alive

Return 1 if the process is still active, 0 otherwise.

die

Reliably try to kill the process. Returns 1 if the process no longer exists once die has completed, 0 otherwise. This will also return 1 if the process has already died. On Unix, the following signals are sent to the process in one second intervals until the process dies: HUP, QUIT, INT, KILL.

wait

Wait for the process to exit. Return the exit status of the program as returned by wait() on the system. To get the actual exit value, divide by 256, regardless of the operating system being used. If the process never existed, then return an empty list in a list context, an undefined value in a scalar context, or nothing in a void context. This function may be called multiple times even after the process has exited and it will return the same exit status.

start_time

Return the value that the Perl function time() returned when the process was started.

end_time

Return the value that the Perl function time() returned when the exit status was obtained from the process.

FUNCTIONS

timeout_system timeout path [arg, [arg...]]

Run a command for timeout seconds and if the process did not exit, then kill it. The location of the program must be used passed in path. While the timeout is implemented using sleep(), this function makes sure that the full timeout is reached before killing the process. The return is the exit status returned from the wait() call. To get the actual exit value, divide by 256. If something failed in the creation of the process, it returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context.

IMPLEMENTATION

Proc::Background comes with two packages, Proc::Background::Unix and Proc::Background::Win32. Currently, on the Unix platform Proc::Background it uses the Proc::Background::Unix class and on the Win32 platform Proc::Win32, which makes use of Win32::Process, is used.

The Proc::Background is package that just assigns to @ISA either Proc::Unix or Proc::Win32, which does the OS dependent work. The OS independent work is done in Proc::Background.

Use two variables to keep track of the process. $self->{_os_obj} contains the operating system object to reference the process. On a Unix systems this is the process id (pid). On Win32, it is an object returned from the Win32::Process class. When $self->{_os_obj} exists, then the program is running. When the program dies, this is recorded by deleting $self->{_os_obj} and saving the exit value $self->{_exit_value}.

Anytime alive() is called, a waitpid() is called on the process and the return status, if any, is gathered and saved for a call to wait(). This module does not install a signal handler for SIGCHLD. If for some reason, the user has installed a signal handler for SIGCHLD, then, then when this module calls waitpid(), the failure will be noticed and taken as the exited child, but it won't be able to gather the exit status. In this case, the exit status will be set to 0.

SEE ALSO

See also the Proc::Background::Unix and Proc::Background::Win32 manual pages.

AUTHOR

Blair Zajac <blair@gps.caltech.edu>

COPYRIGHT

Copyright (c) 1998-2000 Blair Zajac. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.