Description
Runs one registered benchmark case per fresh process. The package does not discover cases, aggregate statistics, report a suite, or set process status. A suite supplies one exact stable identity and retains the returned worker hierarchy.
The parent uses posix_spawn(3), never fork followed by Ada execution. The same executable enters Worker_Mode, announces readiness, executes one ordinary or paired case, and writes one bounded binary result envelope to a dedicated descriptor. Standard output and error are separate bounded diagnostics and are never parsed as protocol data.
Add
procedure Add (Item : in out Environment; Name : String; Value : String)
Add one exact name/value override. Duplicate additions, a name also removed, invalid forms, NULs, and bounded-size violations are rejected.
Parameters
- Item
Policy to update.
- Name
Exact environment variable name.
- Value
Exact environment variable value.
Announce_Ready
procedure Announce_Ready (Request : Worker_Request)
Write the startup marker after CLI/configuration validation and before host setup, warmup, calibration, or timed work.
Parameters
- Request
Validated worker request.
Comparison_Value
function Comparison_Value (Result : Worker_Result) return Comparison
Return one successful paired result.
Parameters
- Result
Successful paired worker result.
Return value
Reconstructed comparison retaining within-worker pairing.
Configuration_Error
Configuration_Error : exception;
Raised when parent launch policy or worker request data is invalid.
Create_Environment
function Create_Environment
(Mode : Environment_Mode := Strict_Mode;
Locale : Locale_Policy := Clear_Locale;
Timezone : Timezone_Policy := Clear_Timezone) return Environment
Construct an environment policy with no additions or removals.
Parameters
- Mode
Strict allowlist or explicit complete inheritance.
- Locale
Locale handling under strict mode.
- Timezone
Timezone handling under strict mode.
Return value
New environment policy.
Current_Request
function Current_Request return Worker_Request
Parse and validate the complete internal worker request.
Return value
Exact request for one registered case.
Derive_Seed
function Derive_Seed (Parent_Seed : Long_Long_Integer; Repetition : Positive) return Long_Long_Integer
Derive a stable nonzero seed from one parent seed and a one-based repetition. Repetitions are independent resampling units; callers must not flatten their within-worker samples into one paired stream.
Parameters
- Parent_Seed
Suite-level deterministic seed.
- Repetition
One-based independent process index.
Return value
Stable nonzero worker seed.
Diagnostic_Limit
subtype Diagnostic_Limit is Natural range 0 .. Maximum_Diagnostic_Bytes;
Retained byte capacity for each diagnostic stream.
Directory_Mode
type Directory_Mode is (Inherit_Directory, Use_Directory);
Working-directory policy is named explicitly. Use_Directory requires a nonempty directory value and resolves it before spawning.
Enumeration literals
- Inherit_Directory
Keep the parent's current directory.
- Use_Directory
Resolve and enter Working_Directory before exec.
Environment
type Environment is private;
Validated environment construction policy and explicit edits.
Environment_Fingerprint
function Environment_Fingerprint (Result : Worker_Result) return String
Return the non-echoing effective environment-name fingerprint.
Parameters
- Result
Worker process result. Values are excluded so inherited credentials cannot be recovered from shared reports by testing guesses against the fingerprint.
Return value
Sixteen lowercase hexadecimal digits for the variable-name set.
Environment_Locale_Policy
function Environment_Locale_Policy (Result : Worker_Result) return Locale_Policy
Return the effective strict-mode locale policy.
Parameters
- Result
Worker process result.
Return value
Clear or preserve locale policy supplied to the worker.
Environment_Mode
type Environment_Mode is (Strict_Mode, Inherit_Mode);
Environment construction policy. Strict_Mode starts from a small execution allowlist. Inherit_Mode copies the complete parent environment and must be selected explicitly.
Enumeration literals
- Strict_Mode
Start from the documented minimal allowlist.
- Inherit_Mode
Copy the complete parent environment explicitly.
Environment_Policy
function Environment_Policy (Result : Worker_Result) return Environment_Mode
Return the selected environment construction mode.
Parameters
- Result
Worker process result.
Return value
Strict or inherited mode.
Environment_Timezone_Policy
function Environment_Timezone_Policy (Result : Worker_Result) return Timezone_Policy
Return the effective strict-mode timezone policy.
Parameters
- Result
Worker process result.
Return value
Clear or preserve timezone policy supplied to the worker.
Exit_Code
function Exit_Code (Result : Worker_Result) return Natural
Return a nonzero ordinary exit code, or zero when not applicable.
Parameters
- Result
Worker process result.
Return value
Portable exit code.
Forced_Termination
function Forced_Termination (Result : Worker_Result) return Boolean
Report whether timeout escalation required hard termination.
Parameters
- Result
Worker process result.
Return value
True after the grace deadline required SIGKILL.
Identity
function Identity (Result : Worker_Result) return String
Return the exact requested stable identity.
Parameters
- Result
Worker process result.
Return value
Case identity validated against the envelope.
Kind
function Kind (Result : Worker_Result) return Result_Kind
Return the expected result shape.
Parameters
- Result
Worker process result.
Return value
Ordinary or paired kind.
Launch_Configuration
type Launch_Configuration is record
Repetitions : Repetition_Count := 1;
Startup_Timeout : Positive_Duration := 5.0;
Total_Timeout : Positive_Duration := 60.0;
Termination_Grace : Nonnegative_Duration := 0.250;
Diagnostic_Capacity : Diagnostic_Limit := 65_536;
Directory : Directory_Mode := Inherit_Directory;
Working_Directory : Ada.Strings.Unbounded.Unbounded_String;
end record;
Each repetition gets its own startup and total monotonic deadline. Total_Timeout includes spawn and setup. Spawn duration is also reported separately and is never included in the worker's operation samples.
Record fields
- Repetitions
Independent worker process count.
- Startup_Timeout
Spawn-to-ready deadline for each worker.
- Total_Timeout
Complete per-worker deadline starting before spawn.
- Termination_Grace
Delay between graceful and forced termination.
- Diagnostic_Capacity
Retained bytes per stdout or stderr stream.
- Directory
Named working-directory policy.
- Working_Directory
Path required only by Use_Directory.
Locale
function Locale (Item : Environment) return Locale_Policy
Return strict-mode locale handling.
Parameters
- Item
Environment policy.
Return value
Locale policy.
Locale_Policy
type Locale_Policy is (Clear_Locale, Preserve_Locale);
Locale and timezone are omitted in strict mode unless explicitly preserved. In inherited mode they are already part of the selected complete environment.
Enumeration literals
- Clear_Locale
Omit locale variables in strict mode.
- Preserve_Locale
Retain LANG and LC_* in strict mode.
Maximum_Configuration_Bytes
Maximum_Configuration_Bytes : constant := 16_384;
Largest encoded benchmark configuration carried in internal argv.
Maximum_Diagnostic_Bytes
Maximum_Diagnostic_Bytes : constant := 1_048_576;
Largest retained diagnostic stream.
Maximum_Environment_Bytes
Maximum_Environment_Bytes : constant := 65_536;
Largest complete environment including terminators.
Maximum_Environment_Entries
Maximum_Environment_Entries : constant := 256;
Largest effective or edited environment entry count.
Maximum_Environment_Name_Length
Maximum_Environment_Name_Length : constant := 255;
Largest environment variable name.
Maximum_Environment_Value_Length
Maximum_Environment_Value_Length : constant := 16_384;
Largest environment variable value.
Maximum_Exception_Name_Length
Maximum_Exception_Name_Length : constant := 4_096;
Largest exception identity carried in a result envelope.
Maximum_Host_Lock_Path_Length
Maximum_Host_Lock_Path_Length : constant := 4_096;
Largest host-lock path carried to a worker.
Maximum_Identity_Length
Maximum_Identity_Length : constant := 512;
Largest encoded stable case identity.
Maximum_Progress_Name_Length
Maximum_Progress_Name_Length : constant := 512;
Largest progress identity carried to a worker.
Maximum_Result_Message_Length
Maximum_Result_Message_Length : constant := 16_384;
Largest exception or configuration message carried in an envelope.
Maximum_Worker_Repetitions
Maximum_Worker_Repetitions : constant := 256;
Largest repetition request accepted by one Run call.
Measurement_Value
function Measurement_Value (Result : Worker_Result) return Measurement
These queries require Normal_Result and the matching result kind.
Parameters
- Result
Successful ordinary worker result.
Return value
Reconstructed measurement including raw samples and metrics.
Mode
function Mode (Item : Environment) return Environment_Mode
Return the selected base environment mode.
Parameters
- Item
Environment policy.
Return value
Strict or inherited mode.
Outcome
function Outcome (Result : Worker_Result) return Worker_Outcome
Return the classified worker outcome.
Parameters
- Result
Worker process result.
Return value
Distinct completion or failure class.
Process_Id
function Process_Id (Result : Worker_Result) return Interfaces.C.int
Return the launch-time process identifier for diagnostics only.
Parameters
- Result
Worker process result.
Return value
Reaped root PID, which the host may already have reused.
Protocol_Error
Protocol_Error : exception;
Raised when a worker-side request or result envelope fails validation.
Protocol_Version
Protocol_Version : constant := 6;
Current binary envelope schema.
Reason
function Reason (Result : Worker_Result) return String
Return bounded classification detail without captured stderr.
Parameters
- Result
Worker process result.
Return value
Human diagnostic for the outcome.
Remove
procedure Remove (Item : in out Environment; Name : String)
Remove one name after the selected base policy is constructed. Duplicate removals and a name also added are rejected.
Parameters
- Item
Policy to update.
- Name
Exact environment variable name.
Repetition
function Repetition (Result : Worker_Result) return Positive
Return the one-based worker repetition.
Parameters
- Result
Worker process result.
Return value
Independent process index.
Repetition_Count
subtype Repetition_Count is Positive range 1 .. Maximum_Worker_Repetitions;
Number of independent worker processes requested for one case.
Requested_Configuration
function Requested_Configuration
(Request : Worker_Request; Template : Configuration := Default_Configuration) return Configuration
Rebuild the serializable measurement policy in the worker. Process- local callback values come from Template; no access value crosses exec.
Parameters
- Request
Validated worker request.
- Template
Worker-local callback sources.
Return value
Reconstructed measurement configuration.
Requested_Identity
function Requested_Identity (Request : Worker_Request) return String
Return the selected case identity.
Parameters
- Request
Validated worker request.
Return value
Exact stable identity.
Requested_Kind
function Requested_Kind (Request : Worker_Request) return Result_Kind
Return the selected result shape.
Parameters
- Request
Validated worker request.
Return value
Ordinary or paired kind.
Requested_Repetition
function Requested_Repetition (Request : Worker_Request) return Positive
Return the selected process repetition.
Parameters
- Request
Validated worker request.
Return value
One-based repetition.
Requested_Seed
function Requested_Seed (Request : Worker_Request) return Long_Long_Integer
Return the worker's derived seed.
Parameters
- Request
Validated worker request.
Return value
Deterministic per-process seed.
Result_Kind
type Result_Kind is (Ordinary_Measurement, Paired_Comparison);
Result shape retained inside one worker. Direct comparisons remain paired in one process. Later protocol versions may add result kinds; this version truthfully supports the suite's ordinary and paired set.
Enumeration literals
- Ordinary_Measurement
One standalone Measurement.
- Paired_Comparison
One Comparison retaining both sides and pairing.
Return_Benchmark_Exception
procedure Return_Benchmark_Exception (Request : Worker_Request; Name : String; Message : String)
Return explicit non-success envelopes without mixing diagnostics into the result stream.
Parameters
- Request
Validated worker request.
- Name
Exception identity.
- Message
Bounded exception message.
Return_Invalid_Configuration
procedure Return_Invalid_Configuration (Request : Worker_Request; Message : String)
Return an explicit invalid-configuration envelope.
Parameters
- Request
Validated worker request.
- Message
Configuration diagnostic.
Return_Result
procedure Return_Result (Request : Worker_Request; Result : Comparison)
Write one complete paired result envelope.
Parameters
- Request
Validated worker request.
- Result
Completed paired comparison.
Return_Result
procedure Return_Result (Request : Worker_Request; Result : Measurement)
Write one complete result envelope. Each operation may be called at most once and terminates protocol ownership for this worker.
Parameters
- Request
Validated worker request.
- Result
Completed ordinary measurement.
Run
procedure Run
(Executable : String;
Identity : String;
Kind : Result_Kind;
Config : Configuration;
Launch : Launch_Configuration;
Env : Environment;
Results : out Worker_Result_Array)
Spawn exactly Results'Length fresh processes. Results'Length must equal Launch.Repetitions. Executable is invoked directly and must contain a directory component; PATH is never searched. Host lock, placement, quiescence, interference observation, and metric sessions therefore run only inside the measuring worker. The caller must exclude process-wide SIGCHLD policies or other child reapers that consume these workers. If Run detects ownership loss, it stops signaling the unanchored PID and reports Parent_IO_Failure. A concurrent external reaper violates this exclusion contract and can race the observation-to-reap interval on hosts without stable handles.
Parameters
- Executable
Direct path to the same benchmark executable.
- Identity
Exact stable registered case identity.
- Kind
Expected ordinary or paired result shape.
- Config
Measurement policy serialized for each worker.
- Launch
Repetition, deadline, diagnostics, and cwd policy.
- Env
Environment construction policy.
- Results
Caller-sized output array retaining worker hierarchy.
Seed
function Seed (Result : Worker_Result) return Long_Long_Integer
Return the derived deterministic worker seed.
Parameters
- Result
Worker process result.
Return value
Seed used inside this worker.
Setup_Nanoseconds
function Setup_Nanoseconds (Result : Worker_Result) return Long_Float
Return post-spawn duration through the ready marker.
Parameters
- Result
Worker process result.
Return value
Setup duration in nanoseconds.
Spawn_Nanoseconds
function Spawn_Nanoseconds (Result : Worker_Result) return Long_Float
Return direct spawn duration outside timed workload.
Parameters
- Result
Worker process result.
Return value
Spawn duration in nanoseconds.
Standard_Error
function Standard_Error (Result : Worker_Result) return String
Return retained standard error bytes.
Parameters
- Result
Worker process result.
Return value
Bounded stderr prefix.
Standard_Error_Omitted
function Standard_Error_Omitted (Result : Worker_Result) return Natural
Return stderr bytes drained but not retained.
Parameters
- Result
Worker process result.
Return value
Exact omitted stderr byte count, saturating at Natural'Last.
Standard_Output
function Standard_Output (Result : Worker_Result) return String
Return retained standard output bytes.
Parameters
- Result
Worker process result.
Return value
Bounded stdout prefix.
Standard_Output_Omitted
function Standard_Output_Omitted (Result : Worker_Result) return Natural
Return stdout bytes drained but not retained.
Parameters
- Result
Worker process result.
Return value
Exact omitted stdout byte count, saturating at Natural'Last.
Terminating_Signal
function Terminating_Signal (Result : Worker_Result) return Natural
Return the terminating signal, or zero when not applicable.
Parameters
- Result
Worker process result.
Return value
Host signal number.
Timezone
function Timezone (Item : Environment) return Timezone_Policy
Return strict-mode timezone handling.
Parameters
- Item
Environment policy.
Return value
Timezone policy.
Timezone_Policy
type Timezone_Policy is (Clear_Timezone, Preserve_Timezone);
Controls timezone inheritance under strict environment mode.
Enumeration literals
- Clear_Timezone
Omit TZ in strict mode.
- Preserve_Timezone
Retain TZ in strict mode.
Worker_Mode
function Worker_Mode return Boolean
Worker-side entry protocol. A benchmark executable checks Worker_Mode before normal parent CLI handling. Current_Request validates the complete internal argument set and the independently recomputed environment fingerprint. No command string or shell syntax is parsed.
Return value
True only for the reserved internal argv marker.
Worker_Outcome
type Worker_Outcome is
(Normal_Result,
Benchmark_Exception,
Invalid_Worker_Configuration,
Startup_Timeout,
Execution_Timeout,
Crashed_By_Signal,
Nonzero_Exit,
Malformed_Protocol,
Parent_IO_Failure,
Spawn_Failure);
Parent classification for one independent worker process.
Enumeration literals
- Normal_Result
A complete validated result and zero process exit.
- Benchmark_Exception
Worker reported a benchmark exception.
- Invalid_Worker_Configuration
Worker rejected its configuration.
- Startup_Timeout
Ready marker missed the startup deadline.
- Execution_Timeout
Total per-worker deadline expired.
- Crashed_By_Signal
Worker terminated because of a signal.
- Nonzero_Exit
Worker exited nonzero without another classification.
- Malformed_Protocol
Result envelope failed closed validation.
- Parent_IO_Failure
Parent capture, observation, cleanup, or exclusive child-reaping ownership failed.
- Spawn_Failure
posix_spawn rejected the launch.
Worker_Request
type Worker_Request is private;
Validated worker-side request recovered from the internal argv protocol.
Worker_Result
type Worker_Result is private;
One parent-side process outcome and optional benchmark result.
Worker_Result_Array
type Worker_Result_Array is array (Positive range <>) of Worker_Result;
Hierarchy of independent process results retained in repetition order.