NAME
BgTask, the Background Task System
DESCRIPTION
This library allows you to conveniently start background jobs, and then check on them and interact with them later using convenient perl data structures for communication, all without needing to be a parent or sibling process.
Communication takes place through sockets in /var/run/bgtask/ and permissions are controlled by file ownership. Output from the script is held in memory until something comes and reads it, even after the task terminates or is killed. (however, if the task supervisor is killed, the output is lost).
SYNOPSYS
my $task= RapidApp::BgTask->spawn(
exec => [ qw( /opt/scripts/foo.pl -n -t /tmp/bar.txt ) ],
env => { DEBUG_STUFF => 1 },
meta => { name => 'Hello World', myDataStruct => MyObject->new({x =>'y'}) },
retainOutput => 1000000 # retain up to one MB of output even after it has been read
);
my @runningTasks= RapidApp::BgTask->search( status => { running => 1 } );
for my $task (@runningTasks) {
$task->pause();
$task->applyMeta('Paused by '.$$);
}
my $task= RapidApp::BgTask->new($pid);
print "Bytes ".$task->stream(1)->start." - ".$task->stream(1)->limit." available on STDOUT\n";
print "Bytes ".$task->stream(2)->start." - ".$task->stream(2)->limit." available on STDERR\n";
my @datagrams= $task->stream('data')->read; # read all available messages
my $stdout= $task->stream('stdout')->read; # read all available bytes
my $stdoutSegment= $task->stream('stdout')->read(12, 35); # read bytes [12 .. 34] if they are still available
#! /usr/bin/perl
use strict;
use RapidApp::BgTask;
my $task= RapidApp::BgTask->new($$);
$task->applyMeta({ name => 'Hello World', target => $ARGV[0], purpose => 'World Domination' });
print "Hello World";
print STDERR, "Hello World";
my @lines= <>;METHODS
$class->defaultTaskPool
Returns a task pool based on the directory /var/run/bgtask. This task pool is used for the methods ->spawn and ->search. If you want to use a custom task pool, create one, and then use $pool->spawn and $pool->search
$class->spawn
Alias for $class->defaultTaskPool->spawn
See RapidApp::BgTask::TaskPool
$class->search
Alias for $class->defaulttaskPool->search
See RapidApp::BgTask::TaskPool
$class->new( $pid )
Create a new interface to an existing task. This doesn't actually do any work, like connecting to the task supervisor or anything, so creating a Task object is cheap. In fact, this does little other than blessing a hash with a pid in it as a BgTask.
If you want to see if you can successfully talk to the supervisor, call 'connect'. However, keep in mind that the supervisor can be terminated at any moment, and then whatever method you call next will likely die with an error. So, you should generally wrap all your code with try / catch.
$task->pid
The process ID of the supervisor of the task
$task->taskPool
The associated TaskPool object which this job should use various parameters from.
$bool = $task->connect( \%failReason = undef )
Try connecting to the supervisor of this task. connect returns true if the supervisor exists and if it was able to open a socket connection to the supervisor, else dies with an error.
If you don't want it to throw an exception, you can pass the optional hash ref as a parameter, and the function will return false, with diagnostic information stored into the hash. ( this can help reduce overhead if you want to iterate accross all jobs, trying to connect to each )
$task->disconnect
$task->applyMeta( %metaAttributes )
This method merges a hash of key/values into the hash of metadata associated with the process.
$task->info( $getFreshCopy=0 )
This method returns the "info hash" of the task. The info hash has lots of useful information, including a key "meta" which contains the metadata hash.
This method fetches the info the first time, and returns the cached info afterward. If you pass a true value for the optional $getFreshCopy, it will discard any cache and pull the info from the supervisor again.
$task->stream( $indexOrName )
This method returns a RapidApp::BgTask::Stream which you can use to query or read or write to one of the task's file descriptors. The parameter can either be a numeric file descriptor, or one of 'stdin', 'stdout', 'stderr'.
$task->kill( $signal='KILL' )
This method tells the supervisor to send a signal to the task. Note that this is much preferrable to trying to find the pid of the supervisor's child and trying to send the signal yourself.
The signal name strings are the same as those for perl's kill() function.
$task->pause( $bool=true )
Alias for ->kill(SIGSTOP), or ->kill(SIGCONT) if the parameter is specified false.
$task->resume
Alias for ->kill(SIGCONT)
$task->restart
Re-execute a terminated task. Has no effect if the job is still running. This does not restart a supervisor; it tells a live supervisor to restart the child process.
$task->delete
Tell the supervisor to terminate, killing its job, collecting any remaining output, and removing its files and disappearing from existance.
$task->_conn
The connection to the supervisor, if one has been made. undef if not connected.
$task->callRemoteMethod
Run a remote method, checking the connection, getting a response, and checking the response for errors.