Module bridge

Expand description

SnapshotBridge is the request/reply channel between the scenario executor and the host capture pipeline. Implements callbacks (CaptureCallback, WatchRegisterCallback), the per-thread bridge installation guard (BridgeGuard), the diagnostic event log (SnapshotBridgeEvent), and the storage caps (MAX_STORED_SNAPSHOTS, MAX_STORED_EVENTS, MAX_WATCH_SNAPSHOTS).

Modules§

accessor_worker_state: State codes for the accessor-init worker, written to the SnapshotBridge::accessor_worker_state atomic. Two-bit encoding leaves the high bits open for future sub-states (e.g. “shutting down”).

BridgeGuard: RAII guard returned by SnapshotBridge::set_thread_local. Restores the prior thread-local bridge on drop so a nested scenario inside an outer one cannot leak its bridge into the outer scope.
CgroupProcsSnapshot: A single cgroup.procs snapshot captured by Op::CaptureCgroupProcs.
SnapshotBridge: Host-side capture pipeline that the freeze coordinator routes Op::CaptureSnapshot and Op::WatchSnapshot requests through.

SnapshotBridgeEvent: A structured event surfaced by the SnapshotBridge during its own operation (capture, storage, drain). Promotes the previous tracing::warn!-only diagnostic channel into an operator- drainable structured row so tests can assert on bridge-side conditions (eviction, missing capture, invariant violations) instead of grepping stderr.

MAX_STORED_EVENTS: Maximum number of SnapshotBridgeEvent entries the bridge retains between SnapshotBridge::drain_events calls. A scenario that triggers many cap-eviction events (a Loop step that captures a unique tag every 30ms for 10 minutes produces ~20 000 events, each ~100 bytes) would otherwise grow the events log without bound. The bridge enforces FIFO eviction at this cap — when push would exceed it, the oldest event is dropped, the dropped count is tracked on SnapshotStore::events_dropped, and the next SnapshotBridge::drain_events call appends a synthetic SnapshotBridgeEvent::EventLogTruncated entry at the tail so the operator never silently loses events. The cap is loose enough (1024 events × ~100 bytes ≈ 100 KiB) that legitimate scenarios never hit it; only runaway capture frequency does.
MAX_STORED_SNAPSHOTS: Maximum number of FailureDumpReports the bridge keeps. Captures driven by a Loop step with a unique tag per iteration would otherwise grow the storage map without bound — every report renders a full BTF tree (potentially hundreds of KB), so an uncapped bridge under hostile/runaway capture frequency drains host memory. The bridge enforces FIFO eviction at this cap so the most recent captures stay reachable; eviction logs a tracing::warn! naming the dropped tag so the operator sees the truncation.
MAX_WATCH_SNAPSHOTS: Shared state owning the capture closure plus the captured-report map.

with_active_bridge: Run f with the active bridge if one is installed. When no bridge is installed, returns None without invoking f — the caller’s responsibility to fall through to its own no-bridge path.

CaptureCallback: Closure type the bridge invokes to capture a snapshot.
KernelOpCallback: Closure type the bridge invokes for a host-side kernel-memory write or read (Op::WriteKernel{Hot,Cold} / Op::ReadKernel{Hot,Cold}).
WatchRegisterCallback: Closure type the bridge invokes to register a hardware-watchpoint snapshot.