view release on metacpan or  search on metacpan

script/bencher  view on Meta::CPAN

=item B<--env-hash>=I<s>

Add an environment hash.

See C<--env-hashes>.

=item B<--env-hashes-json>=I<s>

Add environment hashes (JSON-encoded).

See C<--env-hashes>.

=item B<--env-hashes>=I<s>

Add environment hashes.

=item B<--on-failure>=I<s>

What to do when there is a failure.

Valid values:

 ["die","skip"]

For a command participant, failure means non-zero exit code. For a Perl-code
participant, failure means Perl code dies or (if expected result is specified)
the result is not equal to the expected result.

The default is "die". When set to "skip", will first run the code of each item
before benchmarking and trap command failure/Perl exception and if that happens,
will "skip" the item.


=item B<--on-result-failure>=I<s>

What to do when there is a result failure.

Valid values:

 ["die","skip","warn"]

This is like C<on_failure> except that it specifically refer to the failure of
item's result not being equal to expected result.

There is an extra choice of C<warn> for this type of failure, which is to print a
warning to STDERR and continue.


=item B<--precision-limit>=I<s>

Set precision limit.

Instead of setting C<precision> which forces a single value, you can also set
this C<precision_limit> setting. If the precision in the scenario is higher
(=number is smaller) than this limit, then this limit is used. For example, if
the scenario specifies C<default_precision> 0.001 and C<precision_limit> is set to
0.005 then 0.005 is used.

This setting is useful on slower computers which might not be able to reach the
required precision before hitting maximum number of iterations.


=item B<--precision>=I<s>

Precision.

When benchmarking with the default L<Benchmark::Dumb> runner, will pass the
precision to it. The value is a fraction, e.g. 0.5 (for 5% precision), 0.01 (for
1% precision), and so on. Or, it can also be a positive integer to speciify
minimum number of iterations, usually need to be at least 6 to avoid the "Number
of initial runs is very small (<6)" warning. The default precision is 0, which
is to let Benchmark::Dumb determine the precision, which is good enough for most
cases.

When benchmarking with L<Benchmark> runner, will pass this value as the
C<$count> argument. Which can be a positive integer to mean the number of
iterations to do (e.g. 10, or 100). Or, can also be set to a negative number
(e.g. -0.5 or -2) to mean minimum number of CPU seconds. The default is -0.5.

When benchmarking with L<Benchmark::Dumb::SimpleTime>, this value is a
positive integer which means the number of iterations to perform.

When profiling, a number greater than 1 will set a repetition loop (e.g. C<<
for(1..100){ ... } >>).

This setting overrides C<default_precision> property in the scenario.


=item B<--runner>=I<s>

Runner module to use.

Valid values:

 ["Benchmark::Dumb","Benchmark","Benchmark::Dumb::SimpleTime"]

The default is C<Benchmark::Dumb> which should be good enough for most cases.

You can use C<Benchmark> runner (C<Benchmark.pm>) if you are accustomed to it and
want to see its output format.

You can use C<Benchmark::Dumb::SimpleTime> if your participant code runs for at
least a few to many seconds and you want to use very few iterations (like 1 or
2) because you don't want to wait for too long.


=item B<--save-result>

Whether to save benchmark result to file.

Will also be turned on automatically if C<BENCHER_RESULT_DIR> environment
variabl is defined.

When this is turned on, will save a JSON file after benchmark, containing the
result along with metadata. The directory of the JSON file will be determined
from the C<results_dir> option, while the filename from the C<results_filename>
option.


=item B<--test>

Whether to test participant code once first before benchmarking.

By default, participant code is run once first for testing (e.g. whether it dies
or return the correct result) before benchmarking. If your code runs for many
seconds, you might want to skip this test and set this to 0.


=item B<--with-args-size>

Also return memory usage of item's arguments.

Memory size is measured using L<Devel::Size>.


=item B<--with-process-size>

Also return process size information for each item.

This is done by dumping each item's code into a temporary file and running the
file with a new perl interpreter process and measuring the process size at the
end (so it does not need to load Bencher itself or the other items). Currently
only works on Linux because process size information is retrieved from
C</proc/PID/smaps>. Not all code can work, e.g. if the code tries to access a
closure or outside data or extra modules (modules not specified in the
participant or loaded by the code itself). Usually does not make sense to use
this on external command participants.


=item B<--with-result-size>

Also return memory usage of each item code's result (return value).

Memory size is measured using L<Devel::Size>.


=back

=head2 Action options

=over

=item B<--action>=I<s>, B<-a>