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.