Crate subetha_sidecar 

Sidecar control plane for adaptive primitives.

One background thread per detected NUMA node; each thread polls the registered primitive instances bound to its node:

1. Drains each instance’s ObservationRing into a per-instance InstanceStats accumulator.
2. Asks the instance’s Policy whether a strategy migration is warranted.
3. If yes, calls HandshakeHeader::set_tag to install the new strategy.

Heavy migrations (data swap) are NOT handled here; primitives that need them invoke their own migration logic from within the policy callback (e.g. subetha-cxc::AdaptiveIpc::migrate_to).

Safety model

Registration takes raw pointers to the user’s HandshakeHeader and ObservationRing. The contract is:

• The user must keep these alive until unregister returns.
• unregister blocks until any in-flight scan finishes, so the user can drop the underlying memory immediately after.

The SidecarBox<T> wrapper enforces this contract by holding a Box<T> (stable address) alongside an auto-unregistering SidecarHandle.

Modules

bench_safe

Bench-safety helpers and the cardinal pattern for adaptive primitive benches.

Structs

FixedPolicy

Convenient policy that always returns the same tag (testing).

InstanceStats

Aggregated statistics for one registered instance.

NoMigrationPolicy

Convenient policy that never migrates (default for primitives that haven’t shipped their adaptation logic yet).

Sidecar

The sidecar singleton. Internally a pool of one NodeSidecar per detected NUMA node; each node has its own scanning thread + Vec of registered primitive instances. Registration routes by current_numa_node() so cross-NUMA cache traffic on the scan path stays minimal. InstanceId encodes (node_index, slot) so unregister

SidecarBox

Boxed primitive + auto-unregistering sidecar handle.

SidecarHandle

RAII handle that auto-unregisters its instance on drop.

Constants

DEFAULT_MAX_INSTANCES

Default hard cap on registered instances. Sized to fail fast on the “bench creates a SidecarBox per b.iter()” mistake, which exhausts the host near 94k registrations: this cap refuses an order of magnitude before that, while leaving room above the 10..1000 range production workloads sit in.

MAX_TRACKED_THREADS_PER_KIND

Maximum distinct producer thread ids tracked per op kind. Picked to be cheap (484 = 128 bytes per instance) while sufficient for the policy decisions that read this - once cardinality crosses 1, the policy migrates regardless of the exact count.

N_OP_KINDS

Number of op_kind slots the InstanceStats tracks. Primitives use op_kind values 1..=N to identify per-op-kind buckets (e.g., load vs store for AdaptiveCell; insert/get/remove/snapshot for the snapshot map). Op kind 0 is reserved for “unspecified”.

Traits

AdaptiveInstance

Trait implemented by adaptive primitive instances that opt into sidecar observation. The Box guarantees stable addresses for the header and ring.

Policy

Decides when and how to migrate a primitive instance’s strategy.

Functions

current_numa_node

Per-NUMA-node sidecar sharding scaffolding. The default global sidecar handles all instances; multi-sidecar deployment with per-NUMA pinning would spawn one Sidecar per node and route registrations by spawn-thread affinity. The detection function numa_node_count surfaces the topology; the routing layer plugs in here when load testing on a multi-socket host motivates it.

global

Get the process-wide sidecar singleton.

numa_node_count

Number of NUMA nodes detected on this host. Used by the (in-progress) per-NUMA sidecar sharding to decide how many sidecar threads to spawn.

Type Aliases

InstanceId

Stable identifier for a registered primitive instance.