NAME

RapidApp::BgTask::TaskPool

SYNOPSIS

  my $pool= RapidApp::BgTask::TaskPool->new( path => '/tmp/foo', mkdirIfMissing => [ 0755, undef, undef ] );
  my $task= $pool->spawn(cmd => 'while sleep 1; do date; done', lockfile => '/tmp/countdate.lock', meta => { name => 'foo' });
  print Dumper($task->info);
  
  my @tasks= $pool->search( { meta => { name => 'foo' } } );
  $_->kill('INT') for @tasks;
  sleep 1;
  $_->terminate_supervisor() for @tasks;

DESCRIPTION

Organizes a group of tasks via a directory, providing methods to search existing tasks and create new ones.

TaskPool is really nothing more than a view of a directory, and methods to search and create tasks.

ATTRIBUTES

path

Base directory for a pool of jobs. The directory must be writeable by users wishing to create jobs, and readable by users withing to interact with existing jobs. -or- the directory must be readable or writeable by the set-gid feature of the specified supervisorScript.

sockdir

The directory where job supervisor sockets are created. Currently the same as "path" of the task pool.

METHODS

outputPath( $pid ||= $$ )

The path and filename of the file the given supervisor process will use for its STDOUT.

socketPath( $pid ||= $$ )

The path and filename of the unix socket the given supervisor will listen on.

$args = $pool->supervisorCmd( \@execParams )

Get or set the array of arguments that will be passed to exec to start the supervisor

$envHash= $pool->supervisorEnv( \%envHash )

Get or set the environment variables for the supervisor.

Beware that setting this will voerwrite the defaults of PERLLIB and BGTASK_TASKPOOL_PATH, which are important to the implementation of the default supervisor.

Consider using ->applySupervisorEnv to merge in additional values.

$envHash= $pool->applySupervisorEnv( key => $value, ... )

Apply new environment variables to the environment hash for the supervisor process

$cls= $pool->taskClass( $newClassName )

Get or set the class name used to represent tasks.

This class should have a constructor of the form $class->new($pool, $pid);

$pool= $class->new( %params );

Create a new task pool.

Required parameters: * path => $scalar || Path::Class::Dir Optional parameters: * mkdirIfMissing => [ $mode, $uid, $gid ] * supervisorCmd => \@execArgs * supervisorEnv => \%envOverrides

$task= $pool->spawn( %params );

This method creates a new background task, using the supplied parameters. It returns a controller for the new process, which can be used to construct RapidApp::BgTask::Control objects.

Supported parameters: * cmd => $scalar - the string which should be passed to the shell * exec => [ $prog, @args ] - an array of parameters which will be passed to the exec() syscall * env => %environment - a hash of environment variables to set for the child * behavior => foreground: run as a plain console program. background: redirect stdout and stderr to a file, and double-fork to kill parent and be owned by init, but still exit with current process group. daemon: same as background, but also start a new session to disassociate with the caller's process group. * meta => %freeForm - a hash of free-form metadata to be associated with the process * maxReadBufSize => $int - the maximum bytes of the job's output which will be held for client requests * lockfile => $filename - path of a file which must be able to be locked, or the job exits

@tasks= $pool->search( %infoPattern | sub {$bool} );

This method searches for an existing background task. Every task has a hash called "info". The pattern specifies keys and values that should exist in the desired task's info hash.

Note that the anonymous sub that you pass will be "evaled", so you are free to use code that will die on missing info keys. The anonymous sub will be given the info hash as the first and only parameter.

Example: Proc1: info => { a => 1, meta => { name => 'CoolProgram' }, c => [ 1, 2, 3 ] } Proc2: info => { a => 5, b => 5, c => 5 }

  BgTask->search( { meta => { name => 'CoolProgram' } } );       # returns Proc1
  BgTask->search( sub { (shift)->{meta}{name} eq 'CoolProgram' ) # returns Proc1
  BgTask->search( sub { (shift)->{c}[0] == 1 } ); # returns Proc1

$pool->taskByPid($pid)

Returns a task object for the specified pid, if that pid is a supervisor process and listening on its socket. Returns undef if the process doesn't exist or isn't listening.

cpanm RapidApp

perl -MCPAN -e shell
install RapidApp