Crate nmbrs_runtime

Expand description

§nmbrs-runtime

Workload execution runtime for nmbrs. Owns the async dispatch loop, the adapter trait that workload backends implement, op sequencing across stanzas, error-handler integration, observer callbacks, and the runner that ties everything together.

This is the integration crate — it depends on every other nb-* library and is depended on by nmbrs (and by every persona binary). External consumers shouldn’t usually need to reach into it directly; the public-facing path is nmbrs run or [runner::Runner].

§Pieces

adapter::DriverAdapter — the trait every workload backend implements. CQL, HTTP, stdout, testkit, plotter, and user-supplied adapters all register via the inventory pattern in [adapters].
activity::Activity — one running concurrency unit. Owns the cycle source, the op sequencer, the fiber pool, the error router, and the metrics scope. Multiple activities can run concurrently within one phase.
[runner::Runner] — orchestrates the whole session: parse workload, build component tree, route metrics, walk the scenario tree, supervise activities.
scope_tree / scene_tree — the canonical scenario- tree shape and the runtime presentation surface (SRD 18b).
[scheduler] — schedule= CLI param parses to a [scheduler::ScheduleSpec]; the [scheduler::TreeScheduler] walks the tree and forks concurrent siblings via tokio::JoinSet + Semaphore based on per-level limits.
observer::RunObserver — lifecycle callbacks (phase start / progress / complete / fail). The TUI is one implementor; stderr is the default.
bindings / scope — workload bindings → Polydat Kernel compilation, with cache-and-rebind across phase iterations.

§Out of scope

Polydat DSL parsing and compilation: see polydat.
Workload YAML parsing: see nmbrs_workload.
Component tree, instruments, cadence reporter: see nmbrs_metrics.
Rate limiting: see nmbrs_rate.
Error handler primitives: see nmbrs_errorhandler.

§See also

SRD 29 (docs/SRD/29_execution_engine.md) — the engine front door: this crate’s public contract surface, the load-bearing axioms, and the SRD ↔ module map.
SRD 01 (docs/SRD/01_system_overview.md) — overall architecture.
SRD 18b — scenario-tree, scope-tree, scheduler.
SRD 22 (docs/SRD/22_op_sequencing.md) — op sequencing and stanza model.
SRD 30 (docs/SRD/30_adapter_interface.md) — adapter trait surface.

Modules§

activity: Activity: the unit of concurrent execution.
adapter: Adapter traits: the tiered interface that database/protocol drivers implement (SRD 38).
bindings: Binding expression compiler: parses nosqlbench-style binding chains into Polydat Kernel node wiring.
checkpoint: Workload checkpointing — see SRD-44.
concurrent: SRD-88 — the headless observer + single-run headless helper.
control_catalog: SRD-23 — the dynamic-control capability catalog.
exec_events: Structured exec-event exemplars — the wrapper-facing tap onto the system’s structured event sink (the observer surface, SRD-81/-88).
execution_context: SRD-88 — the task-local ExecutionContext.
fiber_engine: The engine nmbrs runs its kernels on.
fixture: Init-time scope fixture and cycle-time pull plan.
lifecycle: Lifecycle event vocabulary: the kind-tag lifecycle::EventType and its lifecycle::SubjectKind, shared by the readout binder and the checkpoint log. Lifecycle event vocabulary — the kind-tag [EventType] plus its [SubjectKind].
log_sink: Asynchronous log file sink.
observer: Run observer: callback trait for phase lifecycle events.
op_modifier: Per-op field modifiers via initializer-time currying.
opseq: Op sequencing: maps cycles to op templates via a ratio-based LUT.
optimize: SRD-86 — the optimizer service boundary: the Optimizer/Objective contract + registry the phase-execution driver uses, defined here in the core with no dependency on any algorithm crate. Public so algorithm crates (e.g. nmbrs-optimizers) can register against it and the CLI can discover. SRD-86 — the optimizer seam on the runtime side.
output_channel: SRD-87 Output Channel — the single typed terminal-output conduit.
phase_end_triggers: Phase-end trigger registry — content-agnostic callbacks that fire after every phase completion or failure. Used by the watch=plots / watch=report CLI flags to keep an external view (plot image, report html) up-to-date as the run progresses. Phase-end trigger registry.
phase_outcome: SRD-76 phase outcome disposition (structured per-phase status + error list). SRD-76 — Phase Outcome Disposition.
polydat_nodes: Polydat node registrations that need nmbrs-runtime’s runtime services (component tree, controls, fiber context).
readouts: Readout engine — see docs/SRD/63_status_readouts.md.
refine_plan: SRD-77 refine plan — pre-computed skip set + next-execution id, derived from a session’s prior phase_outcomes rows. The runner builds one when nmbrs refine re-attaches to an existing session; the executor’s phase-walk gate checks it before dispatching each phase’s per-cycle work. SRD-77 refine: the per-execution skip plan.
report_anchor: Anchor resolution for nmbrs report --add (SRD-64 §6.1).
resource_pool: Generic resource lifecycle and sharing pool — SRD-35 Push A.
runner: Shared run pipeline for persona binaries.
scene_tree: Scene tree — the runtime hierarchy as it’s surfaced to renderers.
scope: Typed binding scope model for Polydat Kernel compilation.
scope_kernel: A node of nmbrs’s scope tree: a kernel on the fiber engine, beside the interpreter program scope synthesis reads.
scope_synth: Scope-construction substrate for nmbrs-runtime.
scope_tree: Canonical scope tree for a workload’s runtime hierarchy.
session: Session: the root context for a workload run.
session_signals: Session-wide signal handling — the THREE-LEVEL shutdown ladder.
synthesis: Per-fiber Polydat Kernel construction.
sysmon: Session-level system-performance sampler.
throttle: Phase throttle: — the adaptive backpressure governor (SRD-83 Part 9).
timeval: Shared parser for user-facing time-valued settings.
validation: Result validation and relevancy measurement (SRD 47).
wires: WireSource — narrow read trait for op-template name resolution.
workload_lint: Load-time authoring lints for semantic surfaces serde cannot check (SRD-83 follow-up). Runs once at workload load — before any phase dispatch, dryrun included — per the dryrun-as-validation-floor doctrine and “never ignore silently”.
wrapper_registry: SRD-32a — Op Wrapper Registry.
wrapper_resolver: SRD-32a — Wrapper composition resolver.
wrappers: Composable op dispenser wrappers.

Macros§

diag: Convenience macros for logging through the global observer.
trace_event: Format-and-emit a trace event. Same shape as diag! but takes a labels handle first and only fires when the trace router is active.

Functions§

build_inline_refresh_context: SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private). SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private). SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private).
is_internal_counter: SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private). SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private). SRD-100 P2 — the per-phase status builder, re-exported for the display consumer (nmbrs-tui) that now folds active_phases and renders each phase’s status line itself (the module otherwise stays crate-private). Average batch size for the rows/batch: chip — rows written per successful batch op.