Module topology

Cache and core-topology detection for tuning, not for capability gating.

Why this is separate from CpuFeatures

CpuFeatures answers what a machine can execute – a wrong answer there is a crash. This module answers what shape the machine is – a wrong answer here is only a bad tuning choice. The two failure modes differ by orders of magnitude, so they stay separate types.

Why every field is optional

Detection reads sysfs, which is absent on some targets and restricted in some containers. An unknown cache size is reported as None, never as a plausible default: a fabricated 32 KiB that is really 64 KiB produces a tuning decision made on a number nobody measured. Callers must supply their own fallback explicitly, so the guess is visible at the call site.

Detection is Linux sysfs plus available_parallelism: no dependency, no unsafe, no CPUID, and the same code on x86_64 and aarch64. Other targets report no caches and undetermined core heterogeneity.

Evidence this matters

A radix sort in the mesh audit executed 18.9% fewer instructions than the comparison sort it replaced and ran 2.2x slower, because scattering into 256 buckets missed L1 four times as often. Instruction count could not see it; cache size explains it. That is the class of decision this module exists to inform.

Structs

CacheLevel

One cache level’s measured geometry.

CpuTopology

The measured shape of the host machine.