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.