view release on metacpan or  search on metacpan

lib/Benchmark/Dumb.pm  view on Meta::CPAN

}



1;

__END__

=encoding utf8

=head1 NAME

Benchmark::Dumb - Benchmark.pm compatibility layer for Dumbbench

=head1 SYNOPSIS

  use Benchmark::Dumb qw(:all);
  cmpthese(
    0.05, # 5% precision
    {
      fast => 'fast code',
      slow => 'slow code',
    }
  );
  # etc

=head1 DESCRIPTION

This module implements an interface that is B<similar> to the functional
interface of the L<Benchmark> module. This module, however, uses the
L<Dumbbench> benchmarking tool under the hood. For various reasons,
the interface and the output of the benchmark runs are B<not exactly>
the same. Among other reasons, you would lose out on some of
C<Dumbbench>'s advantages.

Understanding this documentation requires some familiarity of how
C<Benchmark.pm> works since it mostly explains how this module
is different.

Please read the following section carefully to understand the most
important differences:

=head2 Differences to Benchmark.pm

This is a list of differences to the interface and behaviour
of the C<Benchmark> module. It may not be complete.
If so, please let me know.

=over 2

=item *

B<The C<$count> parameter is interpreted very differently!>

With C<Benchmark.pm>, specifying a positive integer meant that the
benchmark should be run exactly C<$count> times. A negative value
indicated that the code should be run until C<$count> seconds of
cumulated run-time have elapsed.

With C<Benchmark::Dumb>, we can do better. A positive integer
specifies the I<minimum> number of iterations. C<Dumbbench> may choose
to run more iterations to arrive at the necessary precision.

Specifying a certain target run-time (via a negative number for C<$count>)
may seem like a tempting idea, but if you care at all about the precision
of your result, it's quite useless.
B<This usage is not supported by C<Benchmark::Dumb>!>

Instead, if you pass a positive floating point number as C<$count>,
the fractional part of the number willbe interpreted as the target
I<relative precision> that you expect from the result.

Finally, supplying a C<0> as C<$count> means that C<Dumbbench> will
be invoked with the default settings. This is good enough for most cases.

=item *

There are no exported functions I<by default>!

=item *

The C<:hireswallclock> option is ignored. We always use the hi-res wallclock!
While on the topic: We also I<only> use wallclock times.

=item *

The cache-related functions aren't implemented because we don't use a cache.

=item *

The original C<Benchmark.pm> implementation provides a rudimentary
object-oriented interface. We do not faithfully copy that. See
L</METHODS> below.

=item *

The benchmark code will be run in a special package. It will B<not> be
run in the caller package (at this time). If you need access to
previously-set-up package variables, you will need to include a
C<package> statement in your code.

=item *

The C<debug> method is not implemented and neither is the C<countit>
function.

=item *

Some things that were previously considered functions are now considered
primarily methods (see C<METHODS> below). But they are all importable
and callable as functions.

=back

=head1 FUNCTIONS

These functions work mostly (see the C<$count> gotcha above)
like the equivalent functions in the C<Benchmark> module, but
the textual output is different in that it contains estimates
of the uncertainties. Some of the I<style> and I<format>
options of the original functions are ignored for the time being.

I'm quoting the C<Benchmark> documentation liberally.

=head2 timethis(COUNT, CODE, [TITLE, [STYLE]])

Time I<COUNT> iterations of I<CODE>. I<CODE> may be a string to eval
or a code reference. Unlike with the original C<Benchmark>,
the code will B<not> run in the caller's package. Results will be printed
to C<STDOUT> as I<TITLE> followed by the C<timestr()>.
I<TITLE> defaults to C<"timethis COUNT"> if none is provided.

I<STYLE> determines the format of the output, as described for C<timestr()> below.

Please read the section on C<Differences to Benchmark.pm>
for a discussion of how the I<COUNT> parameter is interpreted.

Returns a C<Benchmark::Dumb> object.

=head2 timeit(COUNT, CODE)

Arguments: I<COUNT> is the number of times to run the loop (see discussion above),
and I<CODE> is the code to run. I<CODE> may be either a code reference or a
string to be eval'd. Unlike with the original C<Benchmark>,
the code will B<not> run in the caller's package.

Returns a C<Benchmark::Dumb> object.

=head2 timethese(COUNT, CODEHASHREF, [STYLE])

The I<CODEHASHREF> is a reference to a hash containing names as keys
and either a string to eval or a code reference for each value.
For each (I<KEY>, I<VALUE>) pair in the I<CODEHASHREF>, this routine will call

  timethis(COUNT, VALUE, KEY, STYLE)

The routines are called in string comparison order of I<KEY>.

The I<COUNT> must be positive or zero. See discussion above.

Returns a hash reference of C<Benchmark::Dumb> objects, keyed by name.

=head2 cmpthese(COUNT, CODEHASHREF, [STYLE])
cmpthese(RESULTSHASHREF, [STYLE])

Optionally calls C<timethese()>, then outputs a comparison chart.  This:

  cmpthese( 500.01, { a => "++\$i", b => "\$i *= 2" } ) ;

outputs a chart like:

		 Rate/s Precision/s       a       b
	a -3.59e+07       6e+06      -- -535.3%
	b  8.24e+06      220000 -123.0%      --

This chart is sorted from slowest to fastest, and shows the percent speed difference between each pair of tests
as well as the uncertainties on the rates and the relative speed difference. The uncertainty on a speed difference
may be omitted if it is below one tenth of a percent.

C<cmpthese> can also be passed the data structure that C<timethese()> returns:

  my $results = timethese( 100.01, { a => "++\$i", b => "\$i *= 2" } ) ;
  cmpthese( $results );

in case you want to see both sets of results.  If the first argument is an
unblessed hash reference, that is C<RESULTSHASHREF>; otherwise that is C<COUNT>.