NAME

POE::Component::SmokeBox::JobQueue - An array based queue for SmokeBox

SYNOPSIS

  use strict;
  use warnings;
  use data::Dumper;
  use POE qw(Component::SmokeBox::JobQueue Component::SmokeBox::Job Component::SmokeBox::Smoker);

  my $perl = 'home/cpan/rel/perl-5.8.8/bin/perl';

  my $q = POE::Component::SmokeBox::JobQueue->spawn();

  POE::Session->create(
     package_states => [
        'main' => [qw(_start _result)],
     ],
  );

  $poe_kernel->run();
  exit 0;

  sub _start {
    my $smoker = POE::Component::SmokeBox::Smoker->new( perl => $perl );
    my $job = POE::Component::SmokeBox::Job->new( 
	type => 'CPANPLUS::YACSmoke',
	command => 'smoke',
	module => 'B/BI/BINGOS/POE-Component-IRC-5.88.tar.gz',
    );

    my $id = $q->submit( event => '_result', job => $job, smokers => [ $smoker ] );
    print "Job ID $id submitted\n";

    return;
  }

  sub _result {
    my ($kernel,$results) = @_[KERNEL,ARG0];

    print "Submitted = ", $results->{submitted}, "\n";
    print Dumper( $_ ) for $results->{result}->results();

    $q->shutdown();
    return;
  }

DESCRIPTION

POE::Component::SmokeBox::JobQueue is an array based job queue for POE::Component::SmokeBox.

Smoke jobs are submitted to the queue and processed with POE::Component::SmokeBox::Backend.

A smoke job is encapsulated in a POE::Component::SmokeBox::Job object.

The results of the smoke are returned encapsulated in a POE::Component::SmokeBox::Result object.

CONSTRUCTOR

spawn

Creates a new POE::Component::SmokeBox::JobQueue object. Takes a number of optional parameters:

'alias', specify a POE::Kernel alias for the component;
'options', a hashref of POE::Session options to pass to the poco's POE::Session;
'delay', the time in seconds to wait between job runs, default is 0;

METHODS

session_id

Returns the POE::Session ID of the component's session.

shutdown

Terminates the jobqueue and kills any currently processing job.

submit

Submits a job to the jobqueue for processing. Takes a number of parameters:

'job', a POE::Component::SmokeBox::Job object, mandatory;
'event', the event to send results to, mandatory;
'smokers', an arrayref of POE::Component::SmokeBox::Smoker objects, mandatory;
'session', the session to send results to, default is the sender;
'type', specify the job priority, 'push' or 'unshift', defaults to 'push';

Jobs are by default pushed onto the end of the queue. You may specify unshift to put submitted items to the front of the queue.

Returns a unique job ID number.

cancel

Given a previously returned job ID number, removes that job from the queue.

'job', a job ID number, mandatory;

Returns a hashref defining the cancelled job on success, undef otherwise.

pending_jobs

Returns a list of pending jobs in the queue. Each job is represented as a hashref, defined as following:

'id', the unique job ID number of the job;
'job', the POE::Component::SmokeBox::Job object of the job;
'submitted', the epoch time in seconds when the job was submitted;
'event', the event that will be sent with the results;
'session', the session ID the above event will be sent to;

current_job

Returns a hashref to the currently processing job, if there is one, undef otherwise. The hashref will have the following keys:

'job', the POE::Component::SmokeBox::Job object of the job;
'submitted', the epoch time in seconds when the job was submitted;
'event', the event that will be sent with the results;
'session', the session ID the above event will be sent to;
'smokers', an arrayref of POE::Component::SmokeBox::Smoker objects that are waiting to be processed;
'backend', the POE::Component::SmokeBox::Backend object of the current job;
'result', a POE::Component::SmokeBox::Result object containing the results so far;

pause_queue

Pauses the jobqueue. Any currently processing jobs will be completed, but nothing else will be processed until the queue is resumed.

pause_queue_now

Same as pause_queue but also halts any currently processing job.

resume_queue

Resumes the processing of a previously paused jobqueue.

queue_paused

Returns true if the jobqueue is paused, false otherwise.

OUTPUT EVENT

An event will be sent on process completion with a hashref as ARG0:

'job', the POE::Component::SmokeBox::Job object of the job;
'result', a POE::Component::SmokeBox::Result object containing the results;
'submitted', the epoch time in seconds when the job was submitted;
'event', the event that will be sent with the results;
'session', the session ID the above event will be sent to;

The results will be same as returned by POE::Component::SmokeBox::Backend. They may be obtained by querying the POE::Component::SmokeBox::Result object:

$_[ARG0]->{result}->results() # produces a list

Each result is a hashref:

'log', an arrayref of STDOUT and STDERR produced by the job;
'PID', the process ID of the POE::Wheel::Run;
'status', the $? of the process;
'start_time', the time in epoch seconds when the job started running;
'end_time', the time in epoch seconds when the job finished;
'idle_kill', only present if the job was killed because of excessive idle;
'excess_kill', only present if the job was killed due to excessive runtime;
'term_kill', only present if the job was killed due to a poco shutdown event;
'cb_kill', only present if the job was killed due to the callback returning false;

AUTHOR

Chris BinGOs Williams

LICENSE

Copyright (C) Chris Williams

This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.

SEE ALSO

POE::Component::SmokeBox::Backend