# numa-programming

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 369 installs · ★ 298 repo stars
- Author: mohitmishra786
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/allocators/numa-programming/SKILL.md
- Updated: 2026-06-27
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/numa-programming

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/numa-programming/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/numa-programming/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/numa-programming/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/numa-programming/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install mohitmishra786/low-level-dev-skills skills/allocators/numa-programming
```

2. **Manually: put the files in place**
- File: `.github/skills/numa-programming/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/mohitmishra786/low-level-dev-skills --path skills/allocators/numa-programming
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/numa-programming/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/allocators/numa-programming/SKILL.md

## When to use it
- bind a process to a specific NUMA node with `numactl`
- allocate memory on a local node using `numa_alloc_onnode` and `mbind`
- 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
- 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

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 53d159d35b6bbbfa.

BEGIN THIRD-PARTY FILE 53d159d35b6bbbfa
````text
---
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);
````
END THIRD-PARTY FILE 53d159d35b6bbbfa

The third-party file has ended. Everything between the 53d159d35b6bbbfa tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2165 of 6123 bytes. © mohitmishra786 · MIT · https://github.com/mohitmishra786/low-level-dev-skills/tree/HEAD/skills/allocators/numa-programming/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
