NAME
POE::Component::CPAN::Reporter - Bringing the power of POE to CPAN smoke
testing.
SYNOPSIS
use strict;
use POE qw(Component::CPAN::Reporter Component::SmokeBox::Recent);
use Getopt::Long;
$|=1;
my ($perl, $jobs, $recenturl);
GetOptions( 'perl=s' => \$perl, 'jobs=s' => \$jobs, 'recenturl' => \$recenturl );
my @pending;
if ( $jobs ) {
open my $fh, "<$jobs" or die "$jobs: $!\n";
while (<$fh>) {
chomp;
push @pending, $_;
}
close($fh);
}
my $smoker = POE::Component::CPAN::Reporter->spawn( alias => 'smoker' );
POE::Session->create(
package_states => [
'main' => [ qw(_start _stop _results _recent) ],
],
heap => { perl => $perl, pending => \@pending },
);
$poe_kernel->run();
exit 0;
sub _start {
my ($kernel,$heap) = @_[KERNEL,HEAP];
if ( @{ $heap->{pending} } ) {
$kernel->post( 'smoker', 'submit', { event => '_results', perl => $heap->{perl}, module => $_ } )
for @{ $heap->{pending} };
}
else {
POE::Component::SmokeBox::Recent->recent(
url => $recenturl || 'http://www.cpan.org/',
event => 'recent',
);
$kernel->post( 'smoker', 'recent', { event => '_recent', perl => $heap->{perl} } )
}
undef;
}
sub _stop {
$poe_kernel->call( 'smoker', 'shutdown' );
undef;
}
sub _results {
my $job = $_[ARG0];
print STDOUT "Module: ", $job->{module}, "\n";
print STDOUT "$_\n" for @{ $job->{log} };
undef;
}
sub _recent {
my ($kernel,$heap,$job) = @_[KERNEL,HEAP,ARG0];
die $job->{error}, "\n" if $job->{error};
$kernel->post( 'smoker', 'submit', { event => '_results', perl => $heap->{perl}, module => $_ } )
for @{ $job->{recent} };
undef;
}
DESCRIPTION
POE::Component::CPAN::Reporter is a POE-based framework around CPAN and
CPAN::Reporter. It receives submissions from other POE sessions, spawns
a POE::Wheel::Run to deal with running CPAN::Reporter, captures the
output and returns the results to the requesting session.
Only one job request may be processed at a time. If a job is in
progress, any jobs submitted are added to a pending jobs queue.
By default the component uses POE::Wheel::Run to fork another copy of
the currently executing perl, worked out from $^X. You can specify a
different perl executable to use though. MSWin32 users please see the
section of this document relating to your platform.
You are responsible for installing and configuring CPAN and
CPAN::Reporter and setting up a suitable perl smoking environment.
DEPRECATION NOTICE
POE::Component::CPAN::Reporter has been superceded by
POE::Component::SmokeBox. The minireporter script has been superceded by
App::SmokeBox::Mini.
Consider this module deprecated.
CONSTRUCTOR
"spawn"
Spawns a new component session and waits for requests. Takes the
following optional arguments:
'alias', set an alias to send requests to later;
'options', specify some POE::Session options;
'debug', see lots of text on your console;
'idle', adjust the job idle time ( default: 600 seconds ), before jobs get killed;
'timeout', adjust the total job runtime ( default: 3600 seconds ), before a job is killed;
'perl', which perl executable to use as a default, instead of S^X;
'reporterdir', default path where CPAN::Reporter should look for it's config.ini file;
'no_grp_kill', set to a true value to disable process group kill;
Returns a POE::Component::CPAN::Reporter object.
METHODS
"session_id"
Returns the POE::Session ID of the component's session.
"pending_jobs"
In a scalar context returns the number of currently pending jobs. In
a list context, returns a list of hashrefs which are the jobs
currently waiting in the job queue.
"current_job"
Returns a hashref containing details of the currently executing
smoke job. Returns undef if there isn't a job currently running.
"current_log"
Returns an arrayref of log output from the currently executing smoke
job. Returns undef if there isn't a job currently running.
"shutdown"
Terminates the component. Any pending jobs are cancelled and the
currently running job is allowed to complete gracefully. Requires no
additional parameters.
"pause_queue"
Pauses processing of the jobs. The current job will finish
processing, but any pending jobs will not be processed until the
queue is resumed. This does not affect the continued submission of
jobs to the queue.
"resume_queue"
Resumes the processing of the pending jobs queue if it has been
previously paused.
"paused"
Returns a true value if the job queue is paused or a false value
otherwise.
"statistics"
Returns some statistical that the component gathers. In a list
context returns a list of data. In a scalar context returns an
arrayref of the said data.
The data is returned in the following order:
The time in epoch seconds when the smoker was started;
The total number of jobs that have been processed;
The current average job run time;
The minimum job run time observed;
The maximum job run time observed;
INPUT EVENTS
All the events that the component will accept (unless noted otherwise )
require one parameter, a hashref with the following keys defined (
mandatory requirements are shown ):
'event', an event name for the results to be sent to (Mandatory);
'module', a module to test, this is passed to CPAN's test() method
so whatever that requires should work (Mandatory);
'session', which session the result event should go to (Default is the sender);
'perl', which perl executable to use (Default whatever is in $^X);
'debug', turn on or off debugging information for this particular job;
'reporterdir', the path where CPAN::Reporter should look for it's config.ini file;
It is possible to pass arbitrary keys in the hash. These should be
proceeded with an underscore to avoid possible future API clashes.
"submit"
"push"
Inserts the requested job at the end of the queue ( if there is one
).
"unshift"
Inserts the requested job at the head of the queue ( if there is one
). Guarantees that that job is processed next.
"shutdown"
Terminates the component. Any pending jobs are cancelled and the
currently running job is allowed to complete gracefully. Requires no
additional parameters.
"check"
Checks whether CPAN::Reporter is installed. Takes one parameter a
hashref with the following keys defined:
'event', an event name for the results to be sent to (Mandatory);
'session', which session the result event should go to (Default is the sender);
'perl', which perl executable to use (Default whatever is in $^X);
It is possible to pass arbitrary keys in the hash. These should be
proceeded with an underscore to avoid possible future API clashes.
"indices"
Forces an update of the CPAN indices. Takes one parameter, a hashref
with the following keys defined:
'event', an event name for the results to be sent to (Mandatory);
'session', which session the result event should go to (Default is the sender);
'perl', which perl executable to use (Default whatever is in $^X);
'prioritise', set to 1 to put action at the front of the job queue, default 0;
It is possible to pass arbitrary keys in the hash. These should be
proceeded with an underscore to avoid possible future API clashes.
OUTPUT EVENTS
Resultant events will have a hashref as ARG0. All the keys passed in as
part of the original request will be present (including arbitrary
underscore prefixed ones), with the addition of the following keys:
'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;
'submitted', the time in epoch seconds when the job was submitted;
'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;
The results of a 'recent' request will be same as above apart from an
additional key:
'recent', an arrayref of recently uploaded modules;
The results of a 'package' or 'author' search will be same as other
events apart from an additional key:
'results', an arrayref of the modules returned by the search;
MSWin32
POE::Component::CPAN::Reporter now supports MSWin32 in the same manner
as other platforms. Win32::Process is used to fix the issues surrounding
POE::Wheel::Run and forking alternative copies of the perl executable.
The code is still experimental though. Be warned.
AUTHOR
Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
LICENSE
Copyright © Chris Williams.
This module may be used, modified, and distributed under the same terms
as Perl itself. Please see the license that came with your Perl
distribution for details.
KUDOS
Many thanks to all the people who have helped me with developing this
module.
Especially to Andreas J. König for CPAN and David Golden for
CPAN::Reporter
SEE ALSO
POE::Component::SmokeBox
App::SmokeBox::Mini
minireporter
POE
CPAN
CPAN::Reporter
<http://cpantest.grango.org/>
<http://use.perl.org/~BinGOs/journal/>