Struct KernelCacheConfig 

pub struct KernelCacheConfig {
    pub capacity: usize,
    pub max_total_bytes: Option<u64>,
    pub verify_on_get: bool,
    pub registry: Option<Arc<dyn KernelRegistry>>,
}

Construction-time configuration for KernelCache.

Holds the small set of policy knobs the cache supports today: capacity (count cap) and whether to recompute the per-entry BLAKE3 integrity hash on every get. Future knobs (per-byte cap, eviction policy choice) will land here without breaking the existing KernelCache::with_capacity / KernelCache::with_disk_persistence shorthands — those construct an equivalent KernelCacheConfig under the hood.

Construct via KernelCacheConfig::default (which mirrors the historical defaults — capacity DEFAULT_CAPACITY, verify-on-get true) and refine with the with_* builders, then hand the config to KernelCache::with_config.

Fields

capacity: usize

Soft maximum L1 entry count. Clamped to >= 1 inside the cache.

max_total_bytes: Option<u64>

Optional soft maximum on the total bytes of cached PTX text held in L1, summed across every live entry (each entry contributes cached.ptx.text.len()). When Some(cap), KernelCache::put evicts LRU entries — using the same eviction queue the count cap drives — until the running byte total fits under cap, after admitting the new entry. The count cap (Self::capacity) still applies independently; whichever cap binds first wins.

Why this exists: the count cap alone is a DoS vector. A 256-slot cache fed adversarial multi-MB PTX blueprints (a deliberately unrolled kernel can emit 10 MB of PTX) reaches ~2.5 GB of resident L1 — see the memory-ceiling note on DEFAULT_CAPACITY. The byte cap bounds the worst case regardless of per-entry size.

A single entry larger than cap is still admitted (the cache never refuses an insert outright — it would otherwise wedge the dispatch path) but it will evict every other entry first; the byte total may transiently exceed cap by at most one such oversized entry.

Default None (preserves the historical count-only behaviour). Set via Self::with_max_total_bytes. Track the live total via KernelCache::total_bytes.

verify_on_get: bool

When true (the default), KernelCache::get recomputes a BLAKE3 over the cached ptx.text on every L1 hit and compares the result against the entry’s stored integrity_hash (jit S-3 in-mem poisoning defence). When false, the recompute is skipped — the cache still refuses entries whose stored hash is all-zero (the construction signal for “built without CachedKernel::new”) as defence-in-depth.

The recompute costs ~10 µs over a typical multi-KB PTX blob; skipping it shaves that off every L1 hit at the cost of widening the in-memory poisoning window from “one get call” to “the lifetime of the entry in L1”. Operators on a high-QPS path with multi-MB PTX where the recompute dominates can opt out, but the safe default is verify-on-get.

registry: Option<Arc<dyn KernelRegistry>>

Optional registry consulted on L1+L2 miss. v0.4 path: caller resolves (tenant, blueprint, sm_version) → (name, version) via an external lookup, then KernelCache::get_with_registry_fallback consults the registry by that pair. v0.3.8 ships a resolve_by_blueprint_hint trait method on the cache config for the resolver step; the in-memory test impl resolves blueprint fingerprint → name@version directly via a HashMap.

Implementations

impl KernelCacheConfig

pub fn with_capacity(self, capacity: usize) -> Self

Override the L1 entry count cap. Clamped to >= 1 at cache construction time; values below 1 are silently raised.

pub fn with_max_total_bytes(self, max_total_bytes: u64) -> Self

Set the soft total-bytes cap on resident L1 PTX. None (the default) preserves the historical count-only behaviour; Some(cap) makes KernelCache::put evict LRU entries until the running PTX byte total fits under cap. See the field-level docs on Self::max_total_bytes for the DoS-mitigation rationale and the single-oversized-entry caveat.

pub fn with_verify_on_get(self, on: bool) -> Self

Toggle the per-get BLAKE3 recompute. Default true; setting false is the high-QPS opt-out. See the field-level docs on Self::verify_on_get for the threat-model trade-off.

pub fn with_registry(self, reg: Arc<dyn KernelRegistry>) -> Self

Attach a KernelRegistry as the L3 fallback consulted by KernelCache::get_with_registry_fallback on an L1+L2 miss. Default is None (registry path disabled). See the field-level docs on Self::registry for the resolution contract.

Trait Implementations

impl Clone for KernelCacheConfig

fn clone(&self) -> KernelCacheConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KernelCacheConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for KernelCacheConfig

fn default() -> Self

Returns the “default value” for a type.