Crate windows_topology_sys

Expand description

Safe enumeration of Windows processor, cache, and memory topology, with a JSON-describable schema for discovered or synthetic topologies.

§What this crate is

Two things, deliberately separated:

MachineMemoryTopology::discover reads the running system’s processor groups, cores, caches, and NUMA nodes safely, via GetLogicalProcessorInformationEx.
MachineMemoryTopology, Domain, and friends are plain data. They need no Windows API call to construct: build one by hand, or (with the serde feature) deserialize one from JSON written for a machine you do not have. See examples/print_topology.rs for the shape a description takes.

That is a claim about not calling the platform, not about other platforms: this crate is Windows-only and does not build elsewhere. An earlier version of these docs said it degraded to an empty shell on other targets, which was never true and never built in CI – raised in PR #56 review. That correction reached the prose but not the code, leaving two modules ungated and the crate genuinely buildable off Windows with a two-type API; a compile_error! now enforces the claim – raised in PR #61 review. Depend on it under [target.'cfg(windows)'.dependencies].

§What this crate is not

Not a topology renderer. It hands back faithful records and an open-kinded Domain over a set of processors; it does not decide what a “locality domain worth partitioning by” is. That decision – by NUMA node, by last-level cache, by processor package – belongs to the consumer, because the right answer depends on the workload and on hardware this crate cannot see (see DESIGN-NOTES.md’s “Why the NUMA node is the wrong key”).

Not a partitioning policy. This crate never decides how many rings, threads, or buffer pools a consumer should create. It exists to serve windows-ioring-sys’s locality story without that crate having to own such a policy either.

Not a device topology. Domains cover processors and memory; nothing here names an NVMe controller, a NIC, or a GPU as a topology participant, and there is no per-initiator, per-target attributed-distance model (HMAT). Both were considered and explicitly declined for now – see D-9 in DESIGN-NOTES.md for the reasoning and what would justify revisiting it. If your question is “which device sits close to which processor,” this crate does not answer it.

§Availability

Windows 11 / Windows Server 2025 and later.

That is the floor this crate claims, and it is a claim about what is tested rather than the oldest version the APIs might work on. GetLogicalProcessorInformationEx is documented back to Vista, and an earlier version of this section said so – but MachineMemoryTopology::discover also calls GetSystemCpuSetInformation, which is documented only from Windows 10 / Server 2016, and this crate imports it statically. A down-level system would therefore fail to load the process, not merely get a poorer answer. Raised in PR #56 review.

The floor is stated at Windows 11 / Server 2025 rather than at the older version the imports would technically permit, because nothing below that is tested here and an untested floor is a guess presented as a guarantee. Server 2025 is the server release built on the Windows 11 codebase; Server 2022 is not, despite the adjacent version numbers.

Nothing here is gated on a runtime capability probe the way windows-ioring-sys needs one.

§The JSON schema is not semver-covered

With the serde feature, MachineMemoryTopology and Domain serialize to and deserialize from a JSON shape documented on Domain itself. That shape is not covered by this crate’s semver contract (D-8 in DESIGN-NOTES.md), even though the Rust types that produce it are, as always. This is what makes the deferrals in D-9 safe to defer rather than merely convenient: extending the schema later is a schema evolution, not a breaking change to a promise never made.

Structs§

AttributeObservation: One source’s claim about one processor’s attribute.
CacheRelation: A cache level shared by a set of logical processors.
CoreRelation: A processor core: one or more logical processors sharing a physical core as SMT siblings.
CpuSet: One processor as the CPU-set API describes it.
Domain: One domain: a named relationship over a set of processors.
EnumerationAnomaly: A record that did not fit the buffer that contained it.
GroupRelation: One processor group Windows has created.
MachineMemoryTopology: A processor, cache, and memory topology: a set of processors and the domains that relate them.
NumaNodeRelation: A NUMA node, as Windows reports it: a set of logical processors.
Observation: One source’s report of a relation, carrying that source’s own label for it.
PackageRelation: A physical processor package (socket).
Processor: One logical processor.
ProcessorFacts: Everything this crate knows about one processor, with each absence named.
ProcessorId: The identity of one logical processor: its group and its number within that group.
ProcessorSet: A set of logical processors, correctly spanning more than one processor group.
Proximity: What a set of processors shares, and how far the answer can be trusted.
Relations: Every relationship Windows reports, decoded and owned.

Enums§

AnomalyKind: What made a record undecodable.
AttributeValue: A plain value for an unrecognised DomainKind::Other’s attributes.
CacheKind: What a CacheRelation holds.
Coherence: How the two Win32 sources agreed when a topology was collected.
DomainKind: What a Domain represents.
Granularity: One element of the granularity order: something a set of processors can be observed to share.
Observed: A value that may be absent, saying which absence it means.
ProcessorAttribute: A per-processor attribute that more than one source may describe.
Provenance: Where a MachineMemoryTopology’s content came from.
Source: Which platform API reported something.

Functions§

discover: Enumerate every processor, package, cache, NUMA node, and group relation the system reports.