NAME

Developer::Dashboard::Pax::Benchmark - internal benchmark helpers for PAX validation

SYNOPSIS

my $bench = Developer::Dashboard::Pax::Benchmark->new(iterations => 5);
my $result = $bench->run_runtime_benchmark(entrypoint => 'bin/app.pl');

DESCRIPTION

This module measures capture, reference runtime, and native-runtime behavior for validation gates. Under SOW-03 it calls compiler/runtime modules directly instead of shelling out to removed public diagnostic CLI commands.

METHODS

new

Creates a benchmark runner. iterations controls the number of samples.

run_capture_benchmark

Runs Developer::Dashboard::Pax::Capture directly and records timing plus process memory fields.

run_runtime_benchmark

Compares stock Perl timing, capture timing, and native execution timing where a native region can be emitted.

PURPOSE

This module exists to keep performance comparisons scripted and reproducible so PAX can measure where a build is faster, slower, or functionally different from stock Perl.

WHY IT EXISTS

PAX's whole value proposition is "capture/native-compile this entrypoint and it still behaves the same, only faster (or at least no slower)" - a claim that is only checkable by actually timing runs, not by inspecting code. This module runs the SAME entrypoint under three conditions (stock perl, PAX's capture/interpret path, and a natively-compiled artifact when one exists) with matched sample counts and RSS-before/after memory accounting, so a benchmark result is directly comparable across the three rather than each caller timing its own ad-hoc subset.

WHEN TO USE

Edit this file when adding a new dimension to compare (a new timing metric, a different memory measurement), when the native-artifact selection logic in _time_native needs to recognize a new entry_kind, or when the benchmark result shape callers depend on changes.

HOW TO USE

Construct a Benchmark with an iterations count, then call run_capture_benchmark to measure just the capture/interpret overhead for one entrypoint, or run_runtime_benchmark for the full three-way comparison (stock Perl, capture, native). Read native_available before trusting native_mean_seconds - a region with no natively-compilable shape legitimately reports native_available => false and fallback_share => 1 rather than a fabricated timing.

WHAT USES IT

PAX's own differential/validation test paths (see Developer::Dashboard::Pax::Differential) and its benchmark-matrix tooling (see Developer::Dashboard::Pax::BenchmarkMatrix) call this to produce the timing evidence behind a "this build is not slower" claim.

EXAMPLES

Example 1:

my $bench = Developer::Dashboard::Pax::Benchmark->new(iterations => 5);
my $result = $bench->run_capture_benchmark('bin/app.pl');
# $result->{mean_seconds} is the mean capture/interpret time over 5 runs

Example 2:

my $bench = Developer::Dashboard::Pax::Benchmark->new(iterations => 3);
my $result = $bench->run_runtime_benchmark('bin/app.pl');
# compares $result->{reference_mean_seconds} (stock perl) against
# $result->{native_mean_seconds} when $result->{native_available} is true