Crate numa_shim 

numa-shim — dependency-free NUMA detection and placement.

Key selling point: zero third-party C/C++ dependencies (no libnuma, no hwloc) — the crate calls the system libc/Win32 API surface directly via FFI rather than binding a third-party C library.

• Linux: mbind(2) via raw syscall(2) (no libnuma, no hwloc).
• Linux node detection: reads /sys/devices/system/node/nodeN/cpumap directly via open/read/close from the C runtime (always present in glibc/musl).
• Windows: VirtualAllocExNuma for NUMA-preferred reservations; GetCurrentProcessorNumberEx + GetNumaProcessorNodeEx for detection.
• macOS / miri: detection reports “unavailable”; the reservation API returns Err(UnsupportedPlatform) (no silent no-ops — task #1306).

This is rare in the Rust ecosystem — typical NUMA crates bind to libnuma or hwloc, pulling in heavy C dependencies. numa-shim has zero non-system dependencies in its default configuration.

Usage

use numa_shim::current_node;

match current_node() {
    Some(node) => println!("Running on NUMA node {node}"),
    None       => println!("NUMA topology unavailable (detection failed or unsupported platform)"),
}

Runnable form: tests/smoke.rs.

Safety

The public API is safe to call from #![forbid(unsafe_code)] consumers — the crate has NO pub unsafe fn. unsafe is confined to the per-OS mod platform blocks plus a small set of crate-root Linux mbind FFI helpers (mbind_preferred_linux, libc_mbind, and the extern "C" { fn syscall(...) } declaration), each with // SAFETY: proof comments. task #1277 (review N7): the old claim that unsafe was “confined to platform modules” was false — those crate-root helpers sit outside every mod platform. The bind_range byte-range API (previously the single pub unsafe fn) was removed in task #1306 as it was confirmed broken (unaligned addr → silent EINVAL; mbind default flags affect only FUTURE faults, not already-touched pages).

Feature flags

Flag	Effect
vmem-integration	Enables reserve_preferred_on_node, which uses the aligned-vmem crate for the reservation step. Windows path uses VirtualAllocExNuma; Linux reserves then calls mbind.

Platform matrix

Platform	current_node	reserve_preferred_on_node (feature)
Linux x86_64/aarch64 (non-miri)	sched_getcpu + sysfs cpumap	mmap then mbind (complete span, before first touch)
Linux other arch (non-miri)	sched_getcpu + sysfs cpumap	UnsupportedArchitecture error
Windows 64-bit (non-miri)	GetCurrentProcessorNumberEx	VirtualAllocExNuma
macOS	None	UnsupportedPlatform error
miri	None	UnsupportedPlatform error
other	None	UnsupportedPlatform error

Windows is supported on 64-bit targets only (x86_64-pc-windows-msvc and equivalent); 32-bit Windows (target_pointer_width = "32") is explicitly out of scope — an owner policy decision (task #1313, fifteenth review finding F11), matching a Windows FFI test layout that has always assumed a 64-bit pointer width and CI coverage that has only ever run 64-bit windows-latest. This policy is compile-time enforced (task #1321, sixteenth review P2): the crate root emits compile_error! under cfg(all(windows, target_pointer_width = "32")), so a 32-bit Windows build fails loudly instead of silently compiling an unsupported configuration; 32-bit non-Windows targets are unaffected and keep compiling normally. The README’s platform table states the same policy; the two are kept in sync deliberately.

Structs

NodeId

A NUMA node identifier for the reservation/policy API.

Reservation

Re-exported so callers of reserve_preferred_on_node can name the return type as numa_shim::Reservation without adding a direct aligned-vmem dependency of their own. This re-export makes the intentional semver coupling between the two sibling crates visible in numa-shim’s own public API (item 46, docs/CORRECTNESS_OPEN_ITEMS.md) rather than leaving it implicit — see reserve_preferred_on_node’s own doc section on the coupling for the full rationale. An owning handle to one aligned span of anonymous virtual memory.

Enums

NodeResolution

Outcome of a NUMA-node determination attempt for the calling thread.

ReserveNumaError

The failure cause of a NUMA-preferred reservation attempt.

Constants

NO_NODE

Sentinel value meaning “no NUMA node / feature disabled / unsupported platform”. This constant is useful when interfacing with APIs that return a raw u32 node index and need a “not available” sentinel.

Functions

current_node

Return the NUMA node id of the calling thread, or None if not determinable.

current_node_resolution

Return the NUMA-node resolution status for the calling thread.

reserve_preferred_on_node

Reserve size bytes of anonymous virtual memory with a NUMA preference for node, aligned to align.