view release on metacpan or  search on metacpan

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

package Benchmark::Confirm;
use strict;
use warnings;

our $VERSION = '1.00';

=head1 NAME

Benchmark::Confirm - take a Benchmark and confirm returned values


=head1 SYNOPSIS

for example, it is ordinary to execute benchmark script...

    perl some_benchmark.pl

and use Benchmark::Confirm

    perl -MBenchmark::Confirm some_benchmark.pl

then you get the result of benchmark and the confirmination.

    Benchmark: timing 1 iterations of Name1, Name2, Name3...
         Name1:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
                (warning: too few iterations for a reliable count)
         Name2:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
                (warning: too few iterations for a reliable count)
         Name3:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
                (warning: too few iterations for a reliable count)
                        Rate Name3 Name1 Name2
    Name3 10000/s    --    0%    0%
    Name1 10000/s    0%    --    0%
    Name2 10000/s    0%    0%    --
    ok 1
    ok 2
    ok 3
    1..3

See the last 4 lines, these are the result of confirmation.


=head1 DESCRIPTION

B<Benchmark::Confirm> displays a confirmation after benchmarks that the each values from benchmark codes are equivalent or not.

All you have to do is to use C<Benchmark::Confirm> instead of C<Benchmark>.

However, if you write some benchmarks in the one script, you should call some methods from C<Benchmark::Confirm>. for more details see below METHODS section.


=head1 METHODS

See L<Benchmark#Standard_Exports> and L<Benchmark#Optional_Exports> sections.

Moreover, B<atonce> and B<reset_confirm> these functions are only for C<Benchmark::Confirm>.

=head2 atonce

C<atonce> function confirms values manually.

You can use this function when you write some benchmarks in one script. Or you shuld use C<reset> function instead on between some benchmarks.

    use strict;
    use warnings;

    use Benchmark::Confirm qw/timethese/;

    {
        my $result = timethese( 1 => +{
            Name1 => sub { "something" },
            Name2 => sub { "something" },
            Name3 => sub { "something" },
        });
    }

    Benchmark::Confirm->atonce;

    {
        my $result = timethese( 1 => +{
            Name1 => sub { 1 },
            Name2 => sub { 1 },
            Name3 => sub { 1 },
        });
    }

=head2 reset_confirm

This function resets stacks of returned value.


=head1 IMPORT OPTIONS

=head2 TAP

If you want to get valid TAP result, you should add import option C<TAP>.

    perl -MBenchmark::Confirm=TAP some_benchmark.pl

Then you get results as valid TAP like below.

    # Benchmark: timing 1 iterations of Name1, Name2, Name3...
    #      Name1:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
    #             (warning: too few iterations for a reliable count)
    #      Name2:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
    #             (warning: too few iterations for a reliable count)
    #      Name3:  0 wallclock secs ( 0.00 usr +  0.00 sys =  0.00 CPU)
    #             (warning: too few iterations for a reliable count)
    #                     Rate Name3 Name1 Name2
    # Name3 10000/s    --    0%    0%
    # Name1 10000/s    0%    --    0%
    # Name2 10000/s    0%    0%    --
    ok 1
    ok 2
    ok 3
    1..3

=head2 no_plan

If you want to add more tests with benchmarks, you should use import option C<no_plan>.

    use Benchmark::Confirm qw/no_plan timethese cmpthese/;

    my $result = timethese( 1 => +{
        Name1 => sub { "something" },
        Name2 => sub { "something" },
        Name3 => sub { "something" },
    });

    cmpthese $result;

    ok 1, 'additionaly';

Don't worry, C<Test::More::done_testing> invokes in C<END> block of Benchmark::Confirm. So you don't need write that.


=head1 CAVEATS

If benchmark code returns CODE reference, then C<Benchmark::Confirm> treats it as string value: 'CODE'. This may change in future releases.


=head1 REPOSITORY

Benchmark::Confirm is hosted on github
<http://github.com/bayashi/Benchmark-Confirm>


=head1 AUTHOR

Dai Okabayashi E<lt>bayashi@cpan.orgE<gt>


=head1 SEE ALSO

L<Benchmark>


=head1 LICENSE

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

=cut

use Benchmark;
use Test::More;

my $capture;