Description
Number of logical benchmark operations. Zero is useful for caller-owned counters; a measured batch always contains at least one iteration.
All_Builtin_Metrics
All_Builtin_Metrics : constant Metric_Set :=
Process_Resource_Metrics or Linux_Hardware_Metrics;
Every built-in axis; Flyology scheduler counters remain opt-in because the standalone crate has no dependency on the Flyology runtime.
Case_Measurement
function Case_Measurement
(Result : Multi_Comparison;
Index : Comparison_Case_Index) return Measurement
Return one case's measurement. Index one is the reference.
Parameters
- Result
Completed multi-way comparison.
- Index
Case index in enumeration order.
Return value
Selected case measurement.
Raised exceptions
- Constraint_Error
If Index exceeds the measured case count.
Cases
function Cases (Result : Multi_Comparison) return Comparison_Case_Count
Return the number of implementations in a multi-way comparison.
Parameters
- Result
Completed multi-way comparison.
Return value
Number of measured cases, including the reference.
Clobber_Memory
procedure Clobber_Memory
Prevent memory operations from moving across this compiler barrier.
Clock_Backend
function Clock_Backend (Result : Measurement) return String
Return the platform clock implementation used for the measurement.
Parameters
- Result
Completed measurement.
Return value
Stable human-readable backend identifier.
Clock_Resolution_Nanoseconds
function Clock_Resolution_Nanoseconds
(Result : Measurement) return Long_Float
Return the platform-reported clock resolution.
Parameters
- Result
Completed measurement.
Return value
Nominal clock resolution in nanoseconds.
Coefficient_Of_Variation_Percent
function Coefficient_Of_Variation_Percent
(Result : Measurement) return Long_Float
Return sample dispersion relative to the arithmetic mean.
Parameters
- Result
Completed measurement.
Return value
Sample standard deviation as a percentage of the mean.
Compare
generic
with procedure Reference_Operation;
with procedure Contender_Operation;
procedure Compare
(Config : Configuration := Default_Configuration;
Result : out Comparison)
Measure two operations in adjacent, order-balanced sample pairs. Equal timed slices are the default; Shared_Iterations can require one count.
Generic formal parameters
- Reference_Operation
- Contender_Operation
Parameters
- Config
Shared measurement policy.
- Result
Paired measurements and relative statistics.
Compare_Batched
generic
with procedure Reference_Batch (Iterations : Iteration_Count);
with procedure Contender_Batch (Iterations : Iteration_Count);
procedure Compare_Batched
(Config : Configuration := Default_Configuration;
Result : out Comparison)
Measure two caller-controlled batches in adjacent, order-balanced sample pairs. Each batch must perform exactly Iterations logical operations.
Generic formal parameters
- Reference_Batch
- Contender_Batch
Parameters
- Config
Shared measurement policy.
- Result
Paired measurements and relative statistics.
Compare_Many
generic
type Case_Id is (<>);
with procedure Batch
(Which : Case_Id;
Iterations : Iteration_Count);
procedure Compare_Many
(Config : Configuration := Default_Configuration;
Result : out Multi_Comparison)
Compare two to sixteen implementations in shared rounds. Each case gets a comparable timed slice by default and occupies every execution position equally, or within one round when counts are indivisible. Sampling progress identifies each implementation separately.
Generic formal parameters
- Case_Id
- Batch
Parameters
- Config
Shared measurement policy.
- Result
Multi-way measurements and comparisons against case one.
Compare_Metric
function Compare_Metric
(Result : Comparison;
Axis : Metric_Axis) return Metric_Comparison_Result
Compare one retained axis using the same paired sample schedule as wall time. Positive-only axes use relative ratios; signed or zero-containing axes use paired absolute differences.
Parameters
- Result
Completed comparison.
- Axis
Requested measurement axis.
Return value
Available or unavailable paired metric comparison.
Comparison
type Comparison is private;
Paired measurements and relative statistics for two implementations.
Comparison_Batch_Policy
type Comparison_Batch_Policy is (Equal_Time, Shared_Iterations);
Controls how comparison batches divide their wall-time budget. Equal_Time independently calibrates each implementation toward the same per-sample duration. Shared_Iterations uses one logical operation count for every implementation, so elapsed time varies with their speed.
Enumeration literals
- Equal_Time
Independently calibrate equal timed slices.
- Shared_Iterations
Use one logical operation count for every case.
Comparison_Case_Count
subtype Comparison_Case_Count is Positive range 2 .. Max_Comparison_Cases;
Number of implementations participating in a multi-way comparison.
Comparison_Case_Index
subtype Comparison_Case_Index is Positive range 1 .. Max_Comparison_Cases;
One-based implementation index in enumeration order.
Comparison_Verdict
type Comparison_Verdict is
(Inconclusive, Practically_Equivalent, Contender_Faster,
Reference_Faster);
Statistical and practical interpretation of a paired comparison.
Enumeration literals
- Inconclusive
The confidence interval supports no practical verdict.
- Practically_Equivalent
The full interval lies inside the configured practical threshold.
- Contender_Faster
The contender is faster beyond the threshold.
- Reference_Faster
The reference is faster beyond the threshold.
Configuration
type Configuration is record
Warmup_Time : Duration := 0.100;
Measurement_Time : Duration := 0.500;
Maximum_Sampling_Time : Duration := 0.0;
Samples : Sample_Count := 50;
Minimum_Sample_Time : Duration := 0.000_100;
Maximum_Iterations : Iteration_Count := Iteration_Count'Last;
Comparison_Batching : Comparison_Batch_Policy := Equal_Time;
Shootout_Scheduling : Shootout_Schedule_Policy := Balanced_Rounds;
Subtract_Timer_Cost : Boolean := False;
Practical_Threshold_Percent : Long_Float := 1.0;
Random_Seed : Long_Long_Integer := 1;
Metrics : Metric_Set := Time_Metrics;
Scheduler_Probe : Flyology_Scheduler_Probe := null;
CPU_Quiescence : CPU_Quiescence_Policy := (others => <>);
Collect_Process_Telemetry : Boolean := False;
Progress : Progress_Handler := null;
Progress_Name : Ada.Strings.Unbounded.Unbounded_String :=
Ada.Strings.Unbounded.Null_Unbounded_String;
end record;
Controls warmup, calibration, and timed sampling.
Record fields
- Warmup_Time
Untimed wall time used to warm code and data.
- Measurement_Time
Target wall time across all timed samples.
- Maximum_Sampling_Time
Hard wall-time budget for sample collection; zero disables the limit. The harness completes at least ten samples and checks the budget only between complete samples or comparison rounds.
- Samples
Number of independently timed samples.
- Minimum_Sample_Time
Lower bound for a calibrated sample.
- Maximum_Iterations
Safety bound for one sample's batch size.
- Comparison_Batching
Whether comparisons default to equal timed slices or one shared logical iteration count.
- Shootout_Scheduling
Whether Compare_Many interleaves balanced rounds or collects one complete implementation block at a time.
- Subtract_Timer_Cost
Whether to subtract the observed timestamp cost once from every timed sample.
- Practical_Threshold_Percent
Smallest relative time change treated as practically meaningful by paired-comparison verdicts.
- Random_Seed
Seed used for order shuffling and bootstrap sampling.
- Metrics
Axes retained and compared around each timed batch.
- Scheduler_Probe
Optional source of cumulative Flyology scheduler counters. The callback runs only outside timed regions.
- CPU_Quiescence
Optional sustained low-host-CPU gate performed before clock characterization and workload warmup.
- Collect_Process_Telemetry
Capture process CPU and RSS around each timed sample using untimed native probes. Terminal_Mode enables this.
- Progress
Optional callback invoked outside timed regions.
- Progress_Name
Human-readable identity passed to Progress. During Compare_Many sampling, the current case name follows this identity.
Contender_First_Samples
function Contender_First_Samples (Result : Comparison) return Natural
Return how many timed pairs ran the contender first.
Parameters
- Result
Completed comparison.
Return value
Timed pairs that ran the contender side first.
Contender_Measurement
function Contender_Measurement (Result : Comparison) return Measurement
Return the contender side of a paired comparison.
Parameters
- Result
Completed comparison.
Return value
Contender-side measurement using the shared sample schedule.
Contender_Wins
function Contender_Wins (Result : Comparison) return Natural
Return the number of sample pairs won by the contender.
Parameters
- Result
Completed comparison.
Return value
Pairs in which the contender took less time.
CPU_Quiescence_Policy
type CPU_Quiescence_Policy is record
Enabled : Boolean := False;
Maximum_Average_CPU_Percent : Long_Float := 20.0;
Maximum_Core_CPU_Percent : Long_Float := 50.0;
Stable_Time : Duration := 1.0;
Poll_Interval : Duration := 0.100;
Timeout : Duration := 15.0;
end record;
Controls the optional host CPU preflight gate. When enabled, the harness samples utilization outside timed regions and proceeds only after both the host-wide average and busiest logical CPU remain at or below their limits for Stable_Time. This detects competing CPU work; it does not establish I/O, thermal, frequency, or interrupt quiescence.
Record fields
- Enabled
Whether to wait before clock characterization and warmup.
- Maximum_Average_CPU_Percent
Largest accepted host-wide busy share.
- Maximum_Core_CPU_Percent
Largest accepted busy share on any one logical CPU.
- Stable_Time
Continuous accepted interval required before starting.
- Poll_Interval
Delay between host CPU counter snapshots.
- Timeout
Maximum wall time spent waiting before raising CPU_Quiescence_Timeout.
CPU_Quiescence_Timeout
CPU_Quiescence_Timeout : exception;
Raised when enabled CPU quiescence is not observed before its timeout.
Default_Configuration
Default_Configuration : constant Configuration := (others => <>);
Default configuration for interactive microbenchmark runs.
Direction
function Direction (Axis : Metric_Axis) return Metric_Direction
Return the resource direction used by comparison verdicts.
Parameters
- Axis
Selected measurement axis.
Return value
Lower, higher, or diagnostic direction.
Do_Not_Optimize
generic
type Element is private;
procedure Do_Not_Optimize (Value : in out Element)
Make a value visible to an opaque compiler barrier. Place this outside a timed nanosecond operation because the barrier is an out-of-line call.
Generic formal parameters
- Element
Parameters
- Value
Input or output value that the optimizer must retain.
Flyology_Scheduler_Metrics
Flyology_Scheduler_Metrics : constant Metric_Set :=
(Flyology_Dispatches .. Flyology_Migrations => True, others => False);
Counters supplied through Scheduler_Probe.
Flyology_Scheduler_Probe
type Flyology_Scheduler_Probe is access procedure
(Snapshot : out Flyology_Scheduler_Snapshot);
Capture cumulative Flyology scheduler counters outside a timed region.
Parameters
- Snapshot
Caller-populated cumulative counter snapshot.
Flyology_Scheduler_Snapshot
type Flyology_Scheduler_Snapshot is record
Available : Boolean := False;
Dispatches : Interfaces.Unsigned_64 := 0;
Poll_Batches : Interfaces.Unsigned_64 := 0;
Poll_Events : Interfaces.Unsigned_64 := 0;
Wakeups : Interfaces.Unsigned_64 := 0;
Migrations_In : Interfaces.Unsigned_64 := 0;
Migrations_Out : Interfaces.Unsigned_64 := 0;
end record;
Cumulative Flyology scheduler counters supplied outside timed regions. A caller can sum one or more Flyology.Observability.Group_Snapshot values. Counters must be process-lifetime monotonic values.
Record fields
- Available
Whether the snapshot contains usable counters.
- Dispatches
Cumulative fiber dispatches.
- Poll_Batches
Cumulative event-poller batches.
- Poll_Events
Cumulative host events delivered.
- Wakeups
Cumulative task wake requests.
- Migrations_In
Cumulative migrations entering observed groups.
- Migrations_Out
Cumulative migrations leaving observed groups.
Geometric_Mean_Speedup
function Geometric_Mean_Speedup (Result : Comparison) return Long_Float
Return the geometric mean paired speedup. A value greater than one means the contender is faster.
Parameters
- Result
Completed comparison.
Return value
Geometric mean of paired reference-time/contender-time ratios.
Iteration_Count
type Iteration_Count is range 0 .. Long_Long_Integer'Last;
Number of logical benchmark operations. Zero is useful for caller-owned counters; a measured batch always contains at least one iteration.
Iterations_Per_Sample
function Iterations_Per_Sample
(Result : Measurement) return Iteration_Count
Return the calibrated logical operation count in each timed sample.
Parameters
- Result
Completed measurement.
Return value
Logical operations in each raw sample.
Lag_One_Correlation
function Lag_One_Correlation (Result : Comparison) return Long_Float
Return lag-one correlation of paired log-speedup samples.
Parameters
- Result
Completed comparison.
Return value
Lag-one sample correlation, or zero when undefined.
Linux_Hardware_Metrics
Linux_Hardware_Metrics : constant Metric_Set :=
(CPU_Cycles .. Branch_Misses => True, others => False);
Linux perf counters covering the calling pthread and the native tasks it creates afterwards. Axes remain unavailable when the kernel, host PMU, or perf permissions reject an event; Metric_Status reports which.
Max_Comparison_Cases
Max_Comparison_Cases : constant := 16;
Maximum number of implementations in one multi-way comparison.
Maximum_Nanoseconds
function Maximum_Nanoseconds (Result : Measurement) return Long_Float
Return the slowest retained per-operation sample.
Parameters
- Result
Completed measurement.
Return value
Slowest per-operation sample in nanoseconds.
Mean_Confidence_High_Nanoseconds
function Mean_Confidence_High_Nanoseconds
(Result : Measurement) return Long_Float
Return the upper endpoint of the bootstrap mean interval.
Parameters
- Result
Completed measurement.
Return value
Upper endpoint of the deterministic bootstrap mean interval.
Mean_Confidence_Low_Nanoseconds
function Mean_Confidence_Low_Nanoseconds
(Result : Measurement) return Long_Float
Return the lower endpoint of the bootstrap mean interval.
Parameters
- Result
Completed measurement.
Return value
Lower endpoint of the deterministic bootstrap mean interval.
Mean_Nanoseconds
function Mean_Nanoseconds (Result : Measurement) return Long_Float
Return the arithmetic mean of the retained per-operation samples.
Parameters
- Result
Completed measurement.
Return value
Arithmetic mean per operation in nanoseconds.
Mean_Time_Difference_Nanoseconds
function Mean_Time_Difference_Nanoseconds
(Result : Comparison) return Long_Float
Return the mean paired time difference. A negative value means the contender took less time.
Parameters
- Result
Completed comparison.
Return value
Arithmetic mean of contender-time minus reference-time pairs.
Measure
generic
with procedure Operation;
procedure Measure
(Config : Configuration := Default_Configuration;
Result : out Measurement)
Warm, calibrate, and measure one statically bound operation.
Generic formal parameters
- Operation
Parameters
- Config
Measurement policy.
- Result
Collected raw samples and summary statistics.
Measure_Batched
generic
with procedure Batch (Iterations : Iteration_Count);
procedure Measure_Batched
(Config : Configuration := Default_Configuration;
Result : out Measurement)
Warm, calibrate, and measure a caller-controlled batch. The caller must perform exactly Iterations logical operations before returning.
Generic formal parameters
- Batch
Parameters
- Config
Measurement policy.
- Result
Collected raw samples and summary statistics.
Measure_Result_Batched
generic
type Element is private;
with procedure Batch
(Iterations : Iteration_Count;
Value : out Element);
procedure Measure_Result_Batched
(Config : Configuration := Default_Configuration;
Result : out Measurement)
Measure a result-producing batch and pass its result to an opaque barrier after the ending timestamp. This avoids charging barrier cost to the measured operation.
Generic formal parameters
- Element
- Batch
Parameters
- Config
Measurement policy.
- Result
Collected raw samples and summary statistics.
Measure_With_Hooks
generic
with procedure Setup;
with procedure Operation;
with procedure Teardown;
procedure Measure_With_Hooks
(Config : Configuration := Default_Configuration;
Result : out Measurement)
Measure an operation with per-sample setup and teardown hooks. Teardown also runs when the measured operation raises, before the exception is propagated.
Generic formal parameters
- Setup
- Operation
- Teardown
Parameters
- Config
Measurement policy.
- Result
Collected raw samples and summary statistics.
Measurement
type Measurement is private;
Raw samples and summary statistics from one benchmark measurement.
Median_Absolute_Deviation_Nanoseconds
function Median_Absolute_Deviation_Nanoseconds
(Result : Measurement) return Long_Float
Return the median absolute deviation of per-operation time.
Parameters
- Result
Completed measurement.
Return value
Median absolute deviation in nanoseconds.
Median_Batch_Nanoseconds
function Median_Batch_Nanoseconds
(Result : Measurement) return Long_Float
Return the elapsed duration of one calibrated timed batch.
Parameters
- Result
Completed measurement.
Return value
Median sample batch duration in nanoseconds.
Median_Nanoseconds
function Median_Nanoseconds (Result : Measurement) return Long_Float
Return the median of the retained per-operation samples.
Parameters
- Result
Completed measurement.
Return value
Median per operation in nanoseconds.
Median_Speedup
function Median_Speedup (Result : Comparison) return Long_Float
Return the median paired speedup. A value greater than one means the contender is faster.
Parameters
- Result
Completed comparison.
Return value
Median paired reference-time/contender-time ratio.
Median_Timer_Cost_Nanoseconds
function Median_Timer_Cost_Nanoseconds
(Result : Measurement) return Long_Float
Return the median adjacent-clock interval observed at startup.
Parameters
- Result
Completed measurement.
Return value
Median clock-read interval in nanoseconds.
Metric_Attribution
type Metric_Attribution is
(Exact_Window,
Same_Native_Thread_Window,
Native_Task_Tree_Window,
Shared_Process_Window,
Shared_Runtime_Window,
Unattributable);
Quality of the boundary used to attribute a collected metric. This is deliberately separate from Metric_Availability: a process-wide value can be successfully collected while also including concurrent work outside the operation being observed.
Enumeration literals
- Exact_Window
The value belongs to the measured wall-clock window.
- Same_Native_Thread_Window
The value covers one native thread and is valid only when both boundaries execute on that thread.
- Native_Task_Tree_Window
The value covers one native thread and native children inherited by its counter group.
- Shared_Process_Window
The value covers the complete process and can include unrelated or concurrent work.
- Shared_Runtime_Window
The value covers a Flyology runtime or execution-group boundary rather than one operation exclusively.
- Unattributable
No valid attribution survived the two boundaries.
Metric_Availability
type Metric_Availability is
(Metric_Not_Requested,
Metric_Collected,
Unsupported_Platform,
Permission_Denied,
Unsupported_Event,
Counter_Resources_Unavailable,
Probe_Failed,
Metric_Partially_Collected);
Collection state retained for each requested metric.
Enumeration literals
- Metric_Not_Requested
The configuration did not select the axis.
- Metric_Collected
Every retained sample contains a value.
- Unsupported_Platform
The operating system has no backend.
- Permission_Denied
The operating system rejected probe access.
- Unsupported_Event
The host exposes no counter for the event, either because it has no performance monitoring unit or because that unit does not implement this event.
- Counter_Resources_Unavailable
The event could not be scheduled or allocated.
- Probe_Failed
A native snapshot, counter control, or read failed, or the kernel rejected the requested counter attributes.
- Metric_Partially_Collected
At least one retained sample contains a value, but one or more retained samples do not.
Metric_Available
function Metric_Available
(Result : Measurement;
Axis : Metric_Axis) return Boolean
Test whether complete samples exist for one axis.
Parameters
- Result
Completed measurement.
- Axis
Requested measurement axis.
Return value
True when every retained sample has a value.
Metric_Axis
type Metric_Axis is
(Wall_Time,
Process_CPU_Time,
Thread_CPU_Time,
Process_RSS,
Process_RSS_Change,
Minor_Page_Faults,
Major_Page_Faults,
Voluntary_Context_Switches,
…,
Flyology_Migrations);
One independently sampled measurement axis. Wall_Time remains the calibration and collection-budget clock even when it is not selected for reporting. Process counters include every thread in the benchmark process; thread CPU covers only the executing pthread. Linux PMU counters additionally inherit into child native tasks created after counter initialization. Flyology counters require Scheduler_Probe.
Enumeration literals
- Wall_Time
Monotonic elapsed nanoseconds per logical operation.
- Process_CPU_Time
User plus system CPU nanoseconds per operation across the process.
- Thread_CPU_Time
User plus system CPU nanoseconds per operation on the calling native pthread.
- Process_RSS
Resident bytes observed after the batch.
- Process_RSS_Change
Resident-byte change per logical operation.
- Minor_Page_Faults
Minor faults per logical operation.
- Major_Page_Faults
Major faults per logical operation.
- Voluntary_Context_Switches
Voluntary switches per operation.
- Involuntary_Context_Switches
Involuntary switches per operation.
- Disk_Read_Bytes
Storage bytes read per logical operation.
- Disk_Written_Bytes
Storage bytes written per logical operation.
- Filesystem_Input_Operations
Filesystem input operations per logical operation.
- Filesystem_Output_Operations
Filesystem output operations per logical operation.
- CPU_Cycles
Linux perf CPU cycles per logical operation.
- Instructions
Linux perf retired instructions per operation.
- Instructions_Per_Cycle
Linux perf instructions divided by cycles.
- Cache_Misses
Linux perf cache misses per logical operation.
- Branches
Linux perf branch instructions per logical operation.
- Branch_Misses
Linux perf branch misses per logical operation.
- Flyology_Dispatches
Scheduler dispatches per logical operation.
- Flyology_Poll_Batches
Poller batches per logical operation.
- Flyology_Poll_Events
Delivered poll events per logical operation.
- Flyology_Wakeups
Wake requests per logical operation.
- Flyology_Migrations
Inbound plus outbound migrations per logical operation.
Metric_Comparison_Method
type Metric_Comparison_Method is
(Relative_Ratio, Absolute_Difference);
Statistical form used to compare one metric.
Enumeration literals
- Relative_Ratio
Paired positive samples use ratios and percent.
- Absolute_Difference
Signed or zero-valued samples use differences.
Metric_Comparison_Result
type Metric_Comparison_Result is record
Available : Boolean := False;
Method : Metric_Comparison_Method := Absolute_Difference;
Reference_Median : Long_Float := 0.0;
Contender_Median : Long_Float := 0.0;
Change : Long_Float := 0.0;
Confidence_Low : Long_Float := 0.0;
Confidence_High : Long_Float := 0.0;
Verdict : Metric_Verdict := Metric_Inconclusive;
end record;
Paired comparison summary for one metric axis. Change is contender relative percent for Relative_Ratio and contender minus reference in Metric_Unit units for Absolute_Difference.
Record fields
- Available
Whether both sides retained complete axis samples.
- Method
Relative ratio or signed absolute difference.
- Reference_Median
Reference median in Metric_Unit units.
- Contender_Median
Contender median in Metric_Unit units.
- Change
Point estimate of contender change.
- Confidence_Low
Lower endpoint in the same change units.
- Confidence_High
Upper endpoint in the same change units.
- Verdict
Directional, equivalent, inconclusive, or diagnostic.
Metric_Direction
type Metric_Direction is
(Lower_Is_Better, Higher_Is_Better, Diagnostic);
Whether a smaller or larger value is normally resource-favorable. Diagnostic metrics receive no better/worse verdict.
Enumeration literals
- Lower_Is_Better
Smaller resource consumption is favorable.
- Higher_Is_Better
Larger efficiency is favorable.
- Diagnostic
No general optimization direction is asserted.
Metric_Name
function Metric_Name (Axis : Metric_Axis) return String
Return a stable human-readable metric name.
Parameters
- Axis
Selected measurement axis.
Return value
Stable display name used by reporters.
Metric_Requested
function Metric_Requested
(Result : Measurement;
Axis : Metric_Axis) return Boolean
Test whether an axis was selected for one measurement.
Parameters
- Result
Completed measurement.
- Axis
Measurement axis.
Return value
True when the configuration requested the axis.
Metric_Sample
function Metric_Sample
(Result : Measurement;
Axis : Metric_Axis;
Index : Sample_Index) return Long_Float
Return one retained metric sample.
Parameters
- Result
Completed measurement.
- Axis
Requested measurement axis.
- Index
One-based retained sample index.
Return value
Value in Metric_Unit units.
Raised exceptions
- Constraint_Error
If the axis is unavailable or Index exceeds the retained sample count.
Metric_Scope
type Metric_Scope is
(Batch_Wall_Clock, Benchmark_Process, Current_Native_Thread,
Native_Task_Tree, Flyology_Runtime);
Attribution boundary of a metric.
Enumeration literals
- Batch_Wall_Clock
Monotonic elapsed time surrounding the batch.
- Benchmark_Process
All native threads in the process.
- Current_Native_Thread
Only the pthread executing the probe.
- Native_Task_Tree
The executing pthread and child native tasks or processes it creates after counter initialization.
- Flyology_Runtime
Counters supplied by Flyology observability.
Metric_Set
type Metric_Set is array (Metric_Axis) of Boolean;
Set of axes requested for one run.
Metric_Statistics
function Metric_Statistics
(Result : Measurement;
Axis : Metric_Axis) return Metric_Summary
Return the distribution summary for one axis.
Parameters
- Result
Completed measurement.
- Axis
Requested measurement axis.
Return value
Available or unavailable summary.
Metric_Status
function Metric_Status
(Result : Measurement;
Axis : Metric_Axis) return Metric_Availability
Return why an axis is available, absent, or unusable.
Parameters
- Result
Completed measurement.
- Axis
Measurement axis.
Return value
Retained collection state with a specific failure class.
Metric_Summary
type Metric_Summary is record
Available : Boolean := False;
Samples : Natural := 0;
Minimum : Long_Float := 0.0;
Maximum : Long_Float := 0.0;
Mean : Long_Float := 0.0;
Median : Long_Float := 0.0;
P95 : Long_Float := 0.0;
P99 : Long_Float := 0.0;
Confidence_Low : Long_Float := 0.0;
Confidence_High : Long_Float := 0.0;
end record;
Distribution summary for one requested measurement axis.
Record fields
- Available
Whether at least one retained sample has this axis.
- Samples
Number of retained metric samples.
- Minimum
Smallest sample in Metric_Unit units.
- Maximum
Largest sample.
- Mean
Arithmetic sample mean.
- Median
Sample median.
- P95
Ninety-fifth percentile.
- P99
Ninety-ninth percentile.
- Confidence_Low
Lower endpoint of the bootstrap mean interval.
- Confidence_High
Upper endpoint of the bootstrap mean interval.
Metric_Unit
function Metric_Unit (Axis : Metric_Axis) return String
Return the metric's human-readable unit.
Parameters
- Axis
Selected measurement axis.
Return value
Unit string, including per-operation normalization.
Metric_Verdict
type Metric_Verdict is
(Metric_Inconclusive,
Metric_Practically_Equivalent,
Contender_Better,
Reference_Better,
Metric_Diagnostic);
Resource-oriented result of a metric comparison.
Enumeration literals
- Metric_Inconclusive
The interval establishes no direction.
- Metric_Practically_Equivalent
A relative interval lies inside the configured practical threshold.
- Contender_Better
The contender uses less resource or has greater efficiency, according to the metric direction.
- Reference_Better
The reference is favorable.
- Metric_Diagnostic
The axis has no general optimization direction.
Minimum_Nanoseconds
function Minimum_Nanoseconds (Result : Measurement) return Long_Float
Return the fastest retained per-operation sample.
Parameters
- Result
Completed measurement.
Return value
Fastest per-operation sample in nanoseconds.
Multi_Comparison
type Multi_Comparison is private;
Measurements and paired results for several implementations measured in common, position-balanced rounds. Case one is the reference.
Observed_Clock_Resolution_Nanoseconds
function Observed_Clock_Resolution_Nanoseconds
(Result : Measurement) return Long_Float
Return the smallest positive clock step observed during characterization.
Parameters
- Result
Completed measurement.
Return value
Observed clock step in nanoseconds, or zero if none was observed.
Order_Effect_Percent
function Order_Effect_Percent (Result : Comparison) return Long_Float
Return the estimated first-versus-second execution order effect.
Parameters
- Result
Completed comparison.
Return value
Difference between order-group geometric speedups, in percent.
Outlier_Counts
type Outlier_Counts is record
Low_Severe : Natural := 0;
Low_Mild : Natural := 0;
High_Mild : Natural := 0;
High_Severe : Natural := 0;
end record;
Tukey-fence classifications computed without removing any samples.
Record fields
- Low_Severe
Samples below the lower outer fence.
- Low_Mild
Samples between the lower outer and inner fences.
- High_Mild
Samples between the upper inner and outer fences.
- High_Severe
Samples above the upper outer fence.
Outliers
function Outliers (Result : Measurement) return Outlier_Counts
Return diagnostic Tukey-fence classifications without removing samples.
Parameters
- Result
Completed measurement.
Return value
Diagnostic outlier classifications, with no samples removed.
P95_Nanoseconds
function P95_Nanoseconds (Result : Measurement) return Long_Float
Return the 95th percentile of per-operation batch averages. This is not an individual-operation tail-latency percentile.
Parameters
- Result
Completed measurement.
Return value
Linearly interpolated 95th percentile in nanoseconds.
P99_Nanoseconds
function P99_Nanoseconds (Result : Measurement) return Long_Float
Return the 99th percentile of per-operation batch averages. This is not an individual-operation tail-latency percentile.
Parameters
- Result
Completed measurement.
Return value
Linearly interpolated 99th percentile in nanoseconds.
Practical_Threshold_Percent
function Practical_Threshold_Percent
(Result : Comparison) return Long_Float
Return the configured practical-effect threshold.
Parameters
- Result
Completed comparison.
Return value
Symmetric relative-time threshold in percent.
Process_Resource_Metrics
Process_Resource_Metrics : constant Metric_Set :=
(Wall_Time .. Filesystem_Output_Operations => True, others => False);
Portable Darwin/Linux process, thread, memory, fault, switch, and I/O counters in addition to wall time.
Progress_Handler
type Progress_Handler is access procedure
(Name : String;
Phase : Progress_Phase;
Completed : Natural;
Total : Natural);
Receives coarse benchmark progress. Total is zero when a phase has no meaningful bounded work count.
Parameters
- Name
Human-readable benchmark or implementation identity.
- Phase
Current benchmark stage.
- Completed
Completed work units in the current stage.
- Total
Total work units, or zero when the phase is unbounded.
Progress_Phase
type Progress_Phase is
(Starting, Waiting_For_CPU_Quiescence, Warming, Calibrating, Sampling,
Analyzing, Finished);
Stage reported by an optional progress callback. Callbacks execute only outside timed regions.
Enumeration literals
- Starting
The run is initializing its clock and state.
- Waiting_For_CPU_Quiescence
The harness is waiting for sustained low host CPU utilization before warmup.
- Warming
The operation is executing outside timed sampling.
- Calibrating
The harness is selecting a batch size.
- Sampling
Timed samples are being collected.
- Analyzing
Statistics and confidence intervals are being computed.
- Finished
The result is complete.
Quantization_Floor_Nanoseconds
function Quantization_Floor_Nanoseconds
(Result : Measurement) return Long_Float
Return the clock-quantization floor amortized over one sample batch.
Parameters
- Result
Completed measurement.
Return value
Nominal resolution divided by calibrated iterations.
Reference_First_Samples
function Reference_First_Samples (Result : Comparison) return Natural
Return how many timed pairs ran the reference first.
Parameters
- Result
Completed comparison.
Return value
Timed pairs that ran the reference side first.
Reference_Measurement
function Reference_Measurement (Result : Comparison) return Measurement
Return the reference side of a paired comparison.
Parameters
- Result
Completed comparison.
Return value
Reference-side measurement using the shared sample schedule.
Reference_Wins
function Reference_Wins (Result : Comparison) return Natural
Return the number of sample pairs won by the reference.
Parameters
- Result
Completed comparison.
Return value
Pairs in which the reference took less time.
Relative_Time_Change_Confidence_High
function Relative_Time_Change_Confidence_High
(Result : Comparison) return Long_Float
Return the upper endpoint of the contender's relative time interval.
Parameters
- Result
Completed comparison.
Return value
Upper endpoint of the relative-time-change interval.
Relative_Time_Change_Confidence_Low
function Relative_Time_Change_Confidence_Low
(Result : Comparison) return Long_Float
Return the lower endpoint of the contender's relative time interval.
Parameters
- Result
Completed comparison.
Return value
Lower endpoint of the relative-time-change interval.
Relative_Time_Change_Percent
function Relative_Time_Change_Percent
(Result : Comparison) return Long_Float
Return the contender's relative time change. A negative value means the contender took less time.
Parameters
- Result
Completed comparison.
Return value
Contender time change relative to the reference, in percent.
Sample_Count
subtype Sample_Count is Positive range 10 .. 1_000;
Number of independently timed samples collected for one measurement.
Sample_Index
subtype Sample_Index is Positive range 1 .. Sample_Count'Last;
Index into the raw samples retained by a measurement.
Sample_Lag_One_Correlation
function Sample_Lag_One_Correlation
(Result : Measurement) return Long_Float
Return lag-one correlation of sequential sample means.
Parameters
- Result
Completed measurement.
Return value
Lag-one sample correlation, or zero when undefined.
Sample_Nanoseconds
function Sample_Nanoseconds
(Result : Measurement;
Index : Sample_Index) return Long_Float
Return one retained per-operation sample.
Parameters
- Result
Completed measurement.
- Index
One-based index into its collected raw samples.
Return value
Per-operation duration in nanoseconds.
Raised exceptions
- Constraint_Error
If Index exceeds the collected sample count.
Sample_Speedup
function Sample_Speedup
(Result : Comparison;
Index : Sample_Index) return Long_Float
Return the speedup ratio retained for one adjacent sample pair.
Parameters
- Result
Completed comparison.
- Index
One-based index into its paired raw samples.
Return value
Reference-time/contender-time ratio for the pair.
Raised exceptions
- Constraint_Error
If Index exceeds the collected sample count.
Samples
function Samples (Result : Measurement) return Sample_Count
Return the number of independently timed samples.
Parameters
- Result
Completed measurement.
Return value
Number of collected raw samples.
Scope
function Scope (Axis : Metric_Axis) return Metric_Scope
Return the attribution boundary of one metric.
Parameters
- Axis
Selected measurement axis.
Return value
Wall, process, current-thread, native-task-tree, or Flyology runtime scope.
Shootout_Batching
function Shootout_Batching
(Result : Multi_Comparison) return Comparison_Batch_Policy
Return the batch calibration policy used by a multi-way comparison.
Parameters
- Result
Completed multi-way comparison.
Return value
Equal-time or shared-iteration batch policy.
Shootout_Schedule
function Shootout_Schedule
(Result : Multi_Comparison) return Shootout_Schedule_Policy
Return the schedule used to collect a multi-way comparison.
Parameters
- Result
Completed multi-way comparison.
Return value
Balanced or sequential shootout schedule.
Shootout_Schedule_Policy
type Shootout_Schedule_Policy is (Balanced_Rounds, Sequential_Cases);
Controls how Compare_Many orders implementation batches. Balanced_Rounds interleaves cases and rotates their positions. Sequential_Cases completes one case's sample block before the next.
Enumeration literals
- Balanced_Rounds
Interleave and position-balance implementation batches.
- Sequential_Cases
Collect one implementation's block at a time.
Speedup_Confidence_High
function Speedup_Confidence_High
(Result : Comparison) return Long_Float
Return the upper endpoint of the paired bootstrap speedup interval.
Parameters
- Result
Completed comparison.
Return value
Upper endpoint of the paired bootstrap speedup interval.
Speedup_Confidence_Low
function Speedup_Confidence_Low
(Result : Comparison) return Long_Float
Return the lower endpoint of the paired bootstrap speedup interval.
Parameters
- Result
Completed comparison.
Return value
Lower endpoint of the paired bootstrap speedup interval.
Standard_Deviation_Nanoseconds
function Standard_Deviation_Nanoseconds
(Result : Measurement) return Long_Float
Return the sample standard deviation of per-operation time.
Parameters
- Result
Completed measurement.
Return value
Sample standard deviation in nanoseconds.
Ties
function Ties (Result : Comparison) return Natural
Return the number of equal-time sample pairs.
Parameters
- Result
Completed comparison.
Return value
Pairs with equal reported per-operation time.
Time_Metrics
Time_Metrics : constant Metric_Set := (Wall_Time => True, others => False);
Wall-time results only, without additional native probes.
Timer_Cost_Nanoseconds
function Timer_Cost_Nanoseconds (Result : Measurement) return Long_Float
Return the measured timestamp cost used for optional subtraction.
Parameters
- Result
Completed measurement.
Return value
Minimum observed adjacent-clock cost in nanoseconds.
Verdict
function Verdict (Result : Comparison) return Comparison_Verdict
Return the practical/statistical verdict for the comparison.
Parameters
- Result
Completed comparison.
Return value
Verdict derived from the interval and configured threshold.
Versus_Reference
function Versus_Reference
(Result : Multi_Comparison;
Index : Comparison_Case_Index) return Comparison
Return one case's paired comparison against case one.
Parameters
- Result
Completed multi-way comparison.
- Index
Contender index in enumeration order.
Return value
Selected paired comparison against the reference.
Raised exceptions
- Constraint_Error
If Index is one or exceeds the case count.