Skip to content

API Overview

This section provides complete API reference documentation for all numaperf types and functions.

Crate Organization

numaperf (facade - use this)
├── Core Types      → NodeId, CpuSet, NodeMask, NumaError
├── Configuration   → HardMode, EnforcementLevel, Capabilities
├── Topology        → Topology, NumaNode
├── Affinity        → ScopedPin, get_affinity, set_affinity
├── Memory          → NumaRegion, MemPolicy, HugePageMode, Prefault
├── Scheduling      → NumaExecutor, NumaExecutorBuilder, StealPolicy
├── Sharding        → NumaSharded, ShardedCounter, CachePadded
├── I/O             → DeviceMap, DeviceLocality, DeviceType
└── Observability   → StatsCollector, LocalityStats, LocalityReport

Quick Reference

Core Types

Type Description See
NodeId NUMA node identifier Core Types
CpuSet Set of CPU IDs Core Types
NodeMask Set of NUMA nodes Core Types
NumaError Error type Errors

Configuration

Type Description See
HardMode Soft vs strict enforcement Core Types
EnforcementLevel Actual enforcement achieved Core Types
Capabilities System capability detection Core Types

Topology

Type Description See
Topology System NUMA topology Topology
NumaNode Single NUMA node info Topology

Affinity

Type Description See
ScopedPin RAII thread pinning Affinity
get_affinity() Query current affinity Affinity

Memory

Type Description See
NumaRegion NUMA-aware memory Memory
MemPolicy Memory placement policy Memory
HugePageMode Huge page settings Memory
Prefault Page fault strategy Memory

Scheduling

Type Description See
NumaExecutor Work executor Scheduler
NumaExecutorBuilder Executor configuration Scheduler
StealPolicy Work stealing policy Scheduler

Sharding

Type Description See
NumaSharded<T> Per-node sharded data Sharded
ShardedCounter Sharded atomic counter Sharded
CachePadded<T> Cache-line padding Sharded

I/O

Type Description See
DeviceMap Device-to-node mapping I/O
DeviceLocality Device locality info I/O
DeviceType Device type enum I/O

Observability

Type Description See
StatsCollector Locality metrics Observability
LocalityStats Metrics snapshot Observability
LocalityReport Diagnostic report Observability
LocalityHealth Health classification Observability

Common Patterns

Create Once, Share Everywhere

use numaperf::Topology;
use std::sync::Arc;

let topo = Arc::new(Topology::discover()?);
// Share topo across threads

RAII Resource Management

use numaperf::{ScopedPin, NumaRegion};

{
    let _pin = ScopedPin::pin_current(cpus)?;
    // Pinned here
}
// Automatically restored

{
    let region = NumaRegion::anon(...)?;
    // Memory mapped
}
// Automatically unmapped

Check Enforcement

use numaperf::EnforcementLevel;

let region = NumaRegion::anon(...)?;
match region.enforcement() {
    EnforcementLevel::Strict => { /* guaranteed */ }
    EnforcementLevel::BestEffort { reason } => { /* check reason */ }
    EnforcementLevel::None { reason } => { /* no NUMA */ }
}

Thread Safety Summary

Type Send Sync Notes
Topology ✓ ✓ Immutable
NumaNode ✓ ✓ Immutable
ScopedPin ✗ ✗ Thread-local
NumaRegion ✓ ✓ Memory shareable
NumaExecutor ✓ ✓ Submit from anywhere
NumaSharded<T> If T If T Depends on T
StatsCollector ✓ ✓ Lock-free