NAME

POE::Component::SmokeBox::Smoker - encapsulates a smoker object.

VERSION

version 0.58

SYNOPSIS

  use POE::Component::SmokeBox::Smoker;

  my $smoker = POE::Component::SmokeBox::Smoker->new(
	perl => '/home/foo/perl-5.10.0/bin/perl',
	env  => { APPDATA => '/home/foo/perl-5.10.0/', },
  );

  print $smoker->perl();
  my $hashref = $smoker->env();

DESCRIPTION

POE::Component::SmokeBox::Smoker provides an object based API for SmokeBox smokers. A smoker is defined as the path to a perl executable that is configured for CPAN Testing and its associated environment settings.

CONSTRUCTOR

new

Creates a new POE::Component::SmokeBox::Smoker object. Takes some parameters:

'perl', the path to a suitable perl executable, (required);
'env', a hashref containing %ENV type environment variables;
'do_callback', a callback to be triggered before+after smoking a job;
'name', anything you want to attach to the smoker for informative purposes;

METHODS

perl

Returns the perl executable path that was set.

env

Returns the hashref of %ENV settings, if applicable.

do_callback

Using this enables the callback mode. USE WITH CAUTION!

You need to pass a subref to enable it, and a undef value to disable it. A typical subref would be one you get from POE:

POE::Component::SmokeBox::Smoker->new(
	'do_callback'	=> $_[SESSION]->callback( 'my_callback', @args ),
	'perl'		=> $^X,
);

Again, it is worth reminding you that you need to read POE::Session for the exact semantics of callbacks in POE. You do not need to supply POE callbacks, any plain subref will do.

POE::Component::SmokeBox::Smoker->new(
	'do_callback'	=> \&my_callback,
	'perl'		=> $^X,
);

The callback will be executed before+after this smoker object processes a job. In the "BEFORE" phase, you can return a true/false value to control SmokeBox's actions. If a false value is returned, the smoker will NOT execute the job. It will simply submit the result as usual, but with some "twists" to the result. The result will have a status of "-1" to signify it didn't run and the "cb_kill" key will be set to 1. In the "AFTER" phase, the return value doesn't matter because the job is done.

Before a job, the callback will get the data shown. ( $self is a POE::Component::SmokeBox::Backend object! )

$callback->( 'BEFORE', $self );

After a job, the callback will get the data shown. ( $result is the result hashref you would get from SmokeBox normally )

$callback->( 'AFTER', $self, $result );

The normal flow for a job would be something like this:

* submit job to SmokeBox from your session
* SmokeBox gets ready to process job
* callback executed with BEFORE
* SmokeBox processes job
* callback executed with AFTER
* SmokeBox submits results to your session

Now, if you have N smokers, it would look like this:

* submit job to SmokeBox from your session
* SmokeBox gets ready to process job
* callback executed with BEFORE ( for smoker 1 )
* SmokeBox processes job ( for smoker 1 )
* callback executed with AFTER ( for smoker 1 )
* callback executed with BEFORE ( for smoker N+1 )
* SmokeBox processes job ( for smoker N+1 )
* callback executed with AFTER ( for smoker N+1 )
* SmokeBox submits results to your session

dump_data

Returns all the data contained in the object as a list.

SEE ALSO

POE::Component::SmokeBox

POE::Component::SmokeBox::JobQueue

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.