NAME

App::SmokeBox::Mini::Plugin - minismokebox plugins

VERSION

version 0.68

DESCRIPTION

This document describes the App::SmokeBox::Mini::Plugin system for App::SmokeBox::Mini and minismokebox.

Plugins are a mechanism for providing additional functionality to App::SmokeBox::Mini and minismokebox.

It is assumed that plugins will be POE based and consist of at least one POE::Session.

INITIALISATION

The plugin constructor is init. App::SmokeBox::Mini uses Module::Pluggable to find plugins beneath the App::SmokeBox::Mini::Plugin namespace and will attempt to call init on each plugin class that it finds.

init will be called with one parameter, a hashref that contains keys for each section of the minismokebox configuration file, (which utilises Config::Tiny).

The role of the plugin is to determine if an appropriate section exists for its own configuration.

If no appropriate configuration exists, then init must return undef.

If appropriate configuration does exist, then the plugin may start a POE::Session.

App::SmokeBox::Mini will watch for a _child event indicating that it has gained a plugin child session. It will detach this child after making a note of the child's session ID which it will use to send the following events.

EVENTS

sbox_perl_info

Sent when App::SmokeBox::Mini has determined the perl version, archname and OS version of the given perl executable.

  ARG0, will be the perl version
  ARG1, will be the archname
  ARG2, will be the OS version

sbox_smoke

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;

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;

sbox_stop

Sent when the smokebox is terminating. Your plugin session should terminate after receiving this event. The following data will be passed:

  ARG0, the start time of the smoke process in epoch time;
  ARG1, the finish time of the smoke process in epoch time;
  ARG2, the total number of jobs processed;
  ARG3, the number of jobs killed for being idle;
  ARG4, the number of jobs killed for running over the excess time;
  ARG5, the average job runtime in seconds;
  ARG6, the minimum job runtime in seconds;
  ARG7, the maximum job runtime in seconds;

AUTHOR

Chris Williams <chris@bingosnet.co.uk>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.