NAME

Forks::Super::Job - object representing a background task

VERSION

0.30

SYNOPSIS

use Forks::Super;

$pid = Forks::Super::fork( \%options );  # see Forks::Super
$job = Forks::Super::Job::get($pid);
$job = Forks::Super::Job::getByName($name);
print "Current job state is $job->{state}\n";
print "Job was created at ", scalar localtime($job->{created}), "\n";

DESCRIPTION

Calls to Forks::Super::fork that successfully spawn a child process or create a deferred job will cause a Forks::Super::Job instance to be created to track the job's state. For many uses of fork, it will not be necessary to query the state of a background job. But access to these objects is provided for users who want to exercise even greater control over their use of background processes.

Calls to Forks::Super::fork that fail (return undef or small negative numbers) generally do not cause a new Forks::Super::Job instance to be created.

ATTRIBUTES

Use the Forks::Super::Job::get or Forks::Super::Job::getByName methods to obtain a Forks::Super::Job object for examination. The Forks::Super::Job::get method takes a process ID or job ID as an input (a value that may have been returned from a previous call to Forks::Super::fork and returns a reference to a Forks::Super::Job object, or undef if the process ID or job ID was not associated with any known Job object. The Forks::Super::Job::getByName looks up job objects by the name parameter that may have been passed in the Forks::Super::fork call.

A Forks::Super::Job object has many attributes, some of which may be of interest to an end-user. Most of these should not be overwritten.

pid

Process ID or job ID. For deferred processes, this will be a unique large negative number (a job ID). For processes that were not deferred, this valud is the process ID of the child process that performed this job's task.

real_pid

The process ID of the child process that performed this job's task. For deferred processes, this value is undefined until the job is launched and the child process is spawned.

pgid

The process group ID of the child process. For deferred processes, this value is undefined until the child process is spawned. It is also undefined for systems that do not implement getpgrp.

created

The time (since the epoch) at which the instance was created.

start

The time at which a child process was created for the job. This value will be undefined until the child process is spawned.

end

The time at which the child process completed and the parent process received a SIGCHLD signal for the end of this process. This value will be undefined until the child process is complete.

reaped

The time at which a job was reaped via a call to Forks::Super::wait, Forks::Super::waitpid, or Forks::Super::waitall. Will be undefined until the job is reaped.

state

A string value indicating the current state of the job. Current allowable values are

DEFERRED

For jobs that are on the job queue and have not started yet.

ACTIVE

For jobs that have started in a child process

COMPLETE

For jobs that have completed and caused the parent process to receive a SIGCHLD signal, but have not been reaped.

REAPED

For jobs that have been reaped by a call to Forks::Super::wait, Forks::Super::waitpid, or Forks::Super::waitall.

SUSPENDED

The job has started but it has been suspended (with a SIGSTOP or other appropriate mechanism for your operating system) and is not currently running. A suspended job will not consume CPU resources but my tie up memory, I/O, and network resources.

SUSPENDED-DEFERRED

Job is in the job queue and has not started yet, and also the job has been suspended.

status

The exit status of a job. See CHILD_ERROR in perlvar. Will be undefined until the job is complete.

style

One of the strings natural, cmd, or sub, indicating whether the initial fork call returned from the child process or whether the child process was going to run a shell command or invoke a Perl subroutine and then exit.

cmd

The shell command to run that was supplied in the fork call.

sub

args

The name of or reference to CODE to run and the subroutine arguments that were supplied in the fork call.

_on_busy

The behavior of this job in the event that the system was too "busy" to enable the job to launch. Will have one of the string values block, fail, or queue.

queue_priority

If this job was deferred, the relative priority of this job.

can_launch

By default undefined, but could be a CODE reference supplied in the fork() call. If defined, it is the code that runs when a job is ready to start to determine whether the system is too busy or not.

depend_on

If defined, contains a list of process IDs and job IDs that must complete before this job will be allowed to start.

depend_start

If defined, contains a list of process IDs and job IDs that must start before this job will be allowed to start.

start_after

Indicates the earliest time (since the epoch) at which this job may start.

expiration

Indicates the latest time that this job may be allowed to run. Jobs that run past their expiration parameter will be killed.

os_priority

Value supplied to the fork call about desired operating system priority for the job.

cpu_affinity

Value supplied to the fork call about desired CPU's for this process to prefer.

SEE ALSO

Forks::Super.

AUTHOR

Marty O'Brien, <mob@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2009-2010, Marty O'Brien.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.