numa-programming — Claude Code skill: NUMA topology and libnuma
Skill teaches the agent NUMA programming: detect topology with numactl and lstopo, bind processes to local memory, use libnuma API, build per-node data structures, and diagnose remote access penalties.
MIT 369 installs ★ 298 updated 2026-06-27
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-codeWhat numa-programming does
Agent gets instructions for NUMA-aware programming: topology detection with numactl --hardware and lstopo, process binding via numactl --cpunodebind and --membind, memory allocation on specific nodes using numa_alloc_onnode and mbind, building per-node freelists to avoid cross-socket synchronization. Covers remote access diagnosis with perf stat tracking node-load-misses and cache-misses, measuring remote penalty (1.5–3× depending on interconnect), and lstopo visualization for DPDK NIC placement.
Without libnuma installed, API calls will not compile; without aligning threads and memory to the same node, multi-socket servers show poor scaling due to cross-socket latency. Instructions include working with sysfs (/sys/devices/system/node/), memory policies MPOL_BIND and MPOL_INTERLEAVE, thread affinity via pthread_setaffinity_np.
Skill provides patterns for HPC, DPDK, custom allocators; includes a decision tree for diagnosing poor scaling, a table of common problems (OOM on one node while others have free RAM, 2× slowdown with remote access, OS page migration) and fixes.
What it helps with
- bind a process to a specific NUMA node with
numactl - allocate memory on a local node using
numa_alloc_onnodeandmbind - build per-node freelist to eliminate cross-socket synchronization
- measure remote access penalty with
perf stat node-load-misses - visualize socket topology, caches, and PCI devices with
lstopo
Example prompts for the agent
- Show NUMA topology on this server and distances between nodes
- Write an allocator with per-node freelist and thread pinning
- Measure latency of local vs remote access for 1 GB of memory
How to install numa-programming
1Skills CLI (Vercel)
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code2Manually: put the files in place
~/.claude/skills/numa-programming/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/numa-programming/
1Skills CLI (Vercel)
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a codex2Manually: put the files in place
.agents/skills/numa-programming/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a cursor2Manually: put the files in place
.cursor/skills/numa-programming/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mohitmishra786/low-level-dev-skills skills/allocators/numa-programming2Manually: put the files in place
.github/skills/numa-programming/SKILL.md1Skills CLI (Vercel)
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a gemini-cli2Platform CLI
gemini skills install https://github.com/mohitmishra786/low-level-dev-skills --path skills/allocators/numa-programmingManually: put the files in place
.devin/skills/numa-programming/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about numa-programming
How to install numa-programming in Claude Code?
Run npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code, the skill will be in ~/.claude/skills/numa-programming/SKILL.md.
What does numa-programming do?
Teaches the agent to detect NUMA topology, bind processes to nodes with numactl, use libnuma API, build per-node data structures, and diagnose remote memory access with perf stat.
What does numa-programming require?
libnuma library (apt install libnuma-dev), numactl and lstopo utilities, multi-socket system with NUMA. Without libnuma, code using numa_alloc_onnode will not compile.
Source text
SKILL.md · MIT
---
name: numa-programming
description: NUMA programming skill for multi-socket memory locality. Use when detecting NUMA topology, binding processes with numactl, using libnuma API, building NUMA-aware data structures, or measuring remote access penalties. Activates on queries about numactl, libnuma, NUMA topology, mbind, lstopo, or remote memory access.
---
# NUMA Programming
## Purpose
Guide agents through NUMA-aware programming: topology detection with `numactl` and sysfs, libnuma API (`numa_alloc_onnode`, `mbind`, `set_mempolicy`), process binding with `numactl`, NUMA-aware data structures, remote access diagnosis with `perf stat`, and `lstopo` visualization.
## When to Use
- Multi-socket server shows poor scaling despite low CPU utilization
- Memory bandwidth saturation on one NUMA node
- Binding database or cache process to local memory
- Designing per-node freelists or sharded allocators
- Measuring remote vs local memory access latency
- Tuning HPC, DPDK, or custom allocator for socket locality
## Workflow
### 1. Topology detection
```bash
# Hardware topology summary
numactl --hardware
# Detailed topology with distances
lstopo --of console
# sysfs nodes
ls /sys/devices/system/node/
cat /sys/devices/system/node/node0/meminfo
cat /sys/devices/system/node/node0/cpulist
```
Typical output:
```
available: 2 nodes (0-1)
node 0 cpus: 0-15
node 0 size: 65536 MB
node 1 cpus: 16-31
node 1 size: 65536 MB
node distances:
node 0 1
0: 10 21
1: 21 10
```
Distance 10 = local, higher = remote (cross-socket).
### 2. Process binding with numactl
```bash
# Bind to node 0 CPUs and memory
numactl --cpunodebind=0 --membind=0 ./myapp
# Interleave memory across all nodes
numactl --interleave=all ./myapp
# Preferred node (fallback if full)
numactl --preferred=0 ./myapp
# Show process NUMA policy
numactl --show
cat /proc/self/numa_maps
```
### 3. libnuma API
```c
#include <numa.h>
#include <numaif.h>
#include <stdio.h>
int main(void) {
if (numa_available() < 0) {
fprintf(stderr, "NUMA not available\n");
return 1;
}
int node = numa_node_of_cpu(0);
printf("CPU 0 on node %d\n", node);
// Allocate on specific node
size_t size = 1024 * 1024 * 1024;
void *mem = numa_alloc_onnode(size, 0);
if (!mem) return 1;
// Bind existing memory
unsigned long nodemask = 1UL << 0;
mbind(mem, size, MPOL_BIND, &nodemask, sizeof(nodemask) * 8, 0);
numa_free(mem, size);
return 0;
}
```
```bash
gcc -o numa_test numa_test.c -lnuma
```
| API | Purpose |
|-----|---------|
| `numa_alloc_onnode` | Allocate on specific node |
| `numa_alloc_local` | Allocate on current CPU's node |
| `mbind` | Set policy on existing mapping |
| `set_mempolicy` | Default policy for subsequent allocs |
| `move_pages` | Migrate pages to target node |
### 4. NUMA-aware data structures
```c
// Per-node freelist — avoids cross-node synchronization
#define MAX_NODES 8
struct per_node_pool {
void *free_list[MAX_NODES];
int node_count;
};
void *pool_alloc_numa(struct per_node_pool *p) {
int node = numa_node_of_cpu(sched_getcpu());
void *blk = p->free_list[node];
if (blk) {
p->free_list[node] = *(void **)blk;
return blk;
}
return numa_alloc_onnode(BLOCK_SIZE, node);
}
```
Pin threads to cores on the same node as their pool.
### 5. Thread affinity alignment
```bash
# Pin thread 0 to CPU 0 (node 0), allocate on node 0
numactl --cpunodebind=0 --membind=0 ./worker --id 0
numactl --cpunodebind=1 --membind=1 ./worker --id 1
```
```c
#include <pthread.h>
#include <sched.h>
cpu_set_t cpuset;
CPU_ZERO(&cpuset);
CPU_SET(target_cpu, &cpuset);
pthread_setaffinity_np(pthread_self(), sizeof(cpuset), &cpuset);
```
### 6. Remote access diagnosis
```bash
# Cache misses often spike with remote memory
perf stat -e cache-misses,cache-references,node-load-misses \
numactl --cpunodebind=0 --membind=1 ./myapp
# Compare local vs remote binding
perf stat numactl --cpunodebind=0 --membind=0 ./myapp
perf stat numactl --cpunodebind=0 --membind=1 ./myapp
```
```bash
# NUMA hit/miss stats (if available)
perf stat -e node-loads,node-load-misses,node-stores ./myapp
```
### 7. Measuring remote penalty
```c
// Microbenchmark: touch 1GB on local vs remote node
clock_t start = clock();
for (size_t i = 0; i < size; i += 4096)
sum += ((char *)mem)[i];
```
Expect 1.5–3x slowdown for remote access depending on interconnect (QPI/UPI/Infinity Fabric).
### 8. lstopo visualization
```bash
# Graphical (if X11)
lstopo
# Text with memory/PCI
lstopo --of ascii
# Export for documentation
lstopo file.png
```
Shows: NUMA nodes, cores, caches, PCI devices — essential for DPDK NIC placement.
### 9. Decision tree
```
Poor scaling on multi-socket?
├── Check numactl --hardware
├── Verify thread and memory on same node
├── perf stat node-load-misses
├── Remote misses high?
│ ├── numactl --membind=local
│ └── Per-node data partitioning
└── Still slow → memory bandwidth bound; reduce sharing
```
## Common Problems
| Symptom | Cause | Fix |
|---------|-------|-----|
| OOM on one node despite free RAM elsewhere | MPOL_BIND too strict | Use `--preferred` or interleave |
| 2x slower after scaling threads | Remote memory access | `numactl --membind` matching CPU node |
| Inconsistent benchmark results | OS migrated pages | `mbind` MPOL_BIND; mlock if needed |
| DPDK NIC on wrong socket | PCI far from CPU | `lstopo`; bind EAL to local socket |
| libnuma not found | Package not installed | `apt install libnuma-dev` |
| First-touch policy surprise | Alloc on node 0, run on node 1 | Allocate from bound thread |
## Related Skills
- `skills/allocators/custom-allocators` — per-node pool allocators
- `skills/async-io/dpdk` — `rte_malloc_socket`, NIC NUMA locality
- `skills/hpc/mpi` — MPI process binding per NUMA node
- `skills/profilers/hardware-counters` — cache miss measurement
- `skills/profilers/linux-perf` — perf NUMA events
- `skills/low-level-programming/cpu-cache-opt` — cache locality fundamentals
© mohitmishra786 · MIT · mohitmishra786/low-level-dev-skills