Module host_context 

Host runtime state captured at sidecar-write time.

HostContext is a snapshot of the host running the tool: kernel release, CPU identity, memory size, hugepages config, transparent-hugepage policy, kernel scheduler tunables, NUMA node count, and kernel cmdline. Static fields (CPU identity, total memory, hugepage size, NUMA count, uname triple, per-CPU cpufreq governor) are memoized in OnceLock across the process; dynamic fields (sched tunables, hugepages totals, THP policy, cmdline) are re-read on every call so run-time sysctl changes or hugepage reservations between tests are not hidden by the cache.

Static-cache staleness under hotplug

The static-field cache pins the first snapshot it observes for the life of the process. This is OUR invariant, not the kernel’s: /proc/meminfo’s MemTotal, /sys/devices/system/node/*, and the uname() return all update live when memory or NUMA hotplug fires, and a freshly- started process would pick up the new values on its next collect call. It is STATIC_HOST_INFO’s OnceLock that binds a single read for the process lifetime — not any kernel-side caching.

So on a host where CPU / NUMA / memory hotplug fires between two collect calls in the same process, HostContext continues to report the pre-hotplug values — total_memory_kib stays at the original snapshot, numa_nodes does not reflect an added/removed node. arch is the only field genuinely immune (a reboot is required to change architecture).

cpufreq_governor is similarly pinned: the per-CPU scaling_governor map is read once on first collect_host_context call and reused thereafter. A test that writes to /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor mid-process will not see the post-write value reflected in later snapshots. Governor changes are rare (they typically happen at boot via cpupower, systemd unit, or kernel default) and the cache trades that rare-mutation visibility for eliminating up to N × M sysfs reads per process (N = online CPUs, M = collect_host_context invocations).

Tests that need live-updated values must either (a) avoid reading HostContext after the hotplug event, or (b) restart the process to force a fresh OnceLock population. No reset hook is exposed in production; the #[cfg(test)]-only reset machinery is for unit tests, not runtime recapture.

Structs

HostContext

Host-level runtime state snapshot attached to each SidecarResult. Every field is optional so a partial read (missing /proc entry, permission denied, parse failure) still records the fields that did succeed instead of dropping the whole snapshot.

HostContextSnapshots

Paired pre-run / post-run HostContext snapshots captured from a single test run, intended for sidecar persistence so downstream analysis can diff the drift-prone dynamic fields (sched_tunables, hugepages_*, thp_*) between the two endpoints.

Enums

DelayacctState

Build + runtime state of kernel delay accounting, probed from /proc/sys/kernel/task_delayacct. Determines which taskstats delay-family fields are actually being populated:

XacctState

Build state of extended task accounting (CONFIG_TASK_XACCT), probed from /proc/config.gz. Gates the taskstats memory watermark fields (hiwater_rss_bytes, hiwater_vm_bytes), which xacct_add_tsk (kernel/tsacct.c) fills whenever CONFIG_TASK_XACCT is built in — there is NO runtime toggle, unlike delay accounting.

Functions

collect_host_context

Capture the host context. Static fields are collected once and cached; dynamic fields are re-read on every call so intra-run sysctl / hugepage / THP changes are reflected.

collect_host_context_pre_run

Capture the host context at the start of a run, before the VM boots or the test body mutates any sysctl / hugepage / THP setting. Semantic alias for collect_host_context — the collection mechanism is identical (same static-cache + dynamic re-read policy) and callers remain free to call either function on either side of the run, but the name pins intent: collect_host_context_pre_run documents that the returned snapshot is the authoritative view of the drift-prone dynamic fields (sched_tunables, hugepages_total / hugepages_free, thp_enabled / thp_defrag) as the scheduler saw them.

parse_bracketed_active_policy

Extract the bracketed active policy from a kernel mm menu-style string such as "always [madvise] never" (THP enabled) or "always defer defer+madvise [madvise] never" (THP defrag). Returns the content between the first [ and first subsequent ], or None if either bracket is missing.