File Coverage

blib/lib/Dumbbench/Instance.pm

Criterion	Covered	Total	%
statement	17	49	34.6
branch	1	16	6.2
condition	0	4	0.0
subroutine	6	12	50.0
pod	5	5	100.0
total	29	86	33.7

package Dumbbench::Instance;
use strict;
use warnings;
use Carp ();
use List::Util qw/min max/;

require Dumbbench::Instance::Cmd;
require Dumbbench::Instance::PerlEval;
require Dumbbench::Instance::PerlSub;

use Class::XSAccessor {
  constructor => 'new',
  accessors => [qw(
    name
    dry_result
    result
  )],
  getters => [qw(timings dry_timings)],
};

=encoding utf8

=head1 NAME

Dumbbench::Instance - A benchmark instance within a Dumbbench

=head1 SYNOPSIS

  use Dumbbench;

  my $bench = Dumbbench->new(
    target_rel_precision => 0.005, # seek ~0.5%
    initial_runs         => 20,    # the higher the more reliable
  );
  $bench->add_instances(
    Dumbbench::Instance::Cmd->new(name => 'mauve', command => [qw(perl -e 'something')]),
    # ... more things to benchmark ...
  );
  $bench->run();
  # ...

=head1 DESCRIPTION

This module is the base class for all benchmark instances. For example,
for benchmarking external commands, you should use L.

The synopsis shows how instances of subclasses of
C are added to a benchmark run.

=head1 METHODS

=head2 new

Constructor that takes named arguments. In this base class,
the only recognized argument is an instance C.

=head2 timings

Returns the internal array reference of timings or undef if
there aren't any.

=head2 dry_timings

Same as C but for dry-run timings.

=head2 name

Returns the name of the instance.

=head2 clone

Returns a full (deep) copy of the object. May have to be
augmented in subclasses.

=cut

sub clone {
  my $self = shift;
  my $clone = bless({%$self} => ref($self));

  if (defined $clone->dry_result) {
    $clone->dry_result($clone->dry_result->new);
  }
  if (defined $clone->result) {
    $clone->result($clone->result->new);
  }
  return $clone;
}

=head2 single_run

Needs to be implemented in subclasses:
A method that performs a single benchmark run and returns the
duration of the run in seconds.

=cut

sub single_run {
  my $self = shift;
  Carp::croak("Can't single_run Dumbbench::Instance: Choose a subclass that implements running.");
}

=head2 single_dry_run

Needs to be implemented in subclasses:
A method that performs a single dry-run and returns the
duration of the run in seconds.

=cut

sub single_dry_run {
  my $self = shift;
  Carp::croak("Can't single_dry_run Dumbbench::Instance: Choose a subclass that implements dry-running.");
}

=head2 timings_as_histogram

If the optional L module is installed,
C can generate histograms of the timing distributions.

This method creates such a histogram object (of type C)
and returns it. If C is not available, this method
returns the empty list.

=cut

sub timings_as_histogram {
  my $self = shift;
  my $timings = $self->timings||[];
  return $self->_timings_as_histogram($timings);
}

=head2 dry_timings_as_histogram

Same as C, but for the timings
from dry-runs.

=cut

sub dry_timings_as_histogram {
  my $self = shift;
  my $timings = $self->dry_timings||[];
  return $self->_timings_as_histogram($timings, 'dry');
}

sub _timings_as_histogram {
  my $self = shift;
  eval "require SOOT;";
  return() if $@;

  my $timings = shift;
  my $is_dry  = shift;
  my $min = (@$timings ? min(@$timings)*0.95 : 0);
  my $max = (@$timings ? max(@$timings)*1.05 : 1);
  my $n = max(@$timings/8, 100);
  my $prefix = $is_dry ? 'dry_' : '';
  my $name = defined($self->name) ? "${prefix}timings_" . $self->name : "${prefix}timings";
  my $hist = TH1D->new($name, "distribution of benchmark ${prefix}timings", int($n), $min, $max);
  $hist->GetXaxis()->SetTitle("run time [s]");
  $hist->GetYaxis()->SetTitle("#");
  $hist->Fill($_) for @$timings;
  return $hist;
}

sub _name_prefix {
  my $name = $_[0]->name;
  return defined($name) ? "$name: " : '';
}

1;

__END__