NAME

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

VERSION

version 0.58

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;
            
          

SEE ALSO

POE::Component::SmokeBox::Backend

AUTHOR

Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Chris Williams.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.