К основному содержанию
скилл CX Codex

numa-programming — скилл для Claude Code: NUMA-программирование

Скилл numa-programming учит агента работать с NUMA-топологией: определять узлы через numactl и lstopo, привязывать процессы к локальной памяти, использовать libnuma API и строить структуры данных с учётом сокетов.

MIT 369 установок ★ 298 обновлён 2026-06-27

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code
Открыть на GitHub

Что делает numa-programming

Агент получает инструкции по NUMA-программированию: детектирование топологии командами numactl --hardware и lstopo, привязка процессов через numactl --cpunodebind и --membind, выделение памяти на конкретном узле функциями numa_alloc_onnode и mbind, построение per-node freelist для избежания межсокетной синхронизации. Включает диагностику удалённого доступа через perf stat с метриками node-load-misses и cache-misses, измерение штрафа за remote access (1.5–3× в зависимости от шины), визуализацию через lstopo для размещения DPDK-карт.

Без libnuma в системе вызовы API не скомпилируются; без привязки потоков и памяти к одному узлу масштабирование на многосокетных серверах проваливается из-за latency межсокетного обращения. Инструкции покрывают работу с sysfs (/sys/devices/system/node/), политики памяти MPOL_BIND и MPOL_INTERLEAVE, выравнивание thread affinity через pthread_setaffinity_np.

Скилл — набор паттернов для HPC, DPDK, кастомных аллокаторов; включает decision tree для диагностики плохого масштабирования, таблицу типичных проблем (OOM на одном узле, 2× замедление при remote access, миграция страниц ОС) и способы их устранения.

Какие задачи решает

  • привязать процесс к конкретному NUMA-узлу командой numactl
  • выделить память на локальном узле через numa_alloc_onnode и mbind
  • построить per-node freelist для устранения межсокетной синхронизации
  • измерить штраф за удалённый доступ через perf stat node-load-misses
  • визуализировать топологию сокетов, кешей и PCI-устройств через lstopo

Примеры запросов агенту

  • Покажи топологию NUMA на этом сервере и дистанции между узлами
  • Напиши код аллокатора с per-node freelist и привязкой потоков
  • Замерь latency локального и удалённого доступа к 1 ГБ памяти

Как установить numa-programming

1Через Skills CLI (Vercel)

npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code

2Вручную: положить файлы

~/.claude/skills/numa-programming/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/numa-programming/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о numa-programming

Как установить numa-programming в Claude Code?

Выполни npx skills add mohitmishra786/low-level-dev-skills --skill numa-programming -a claude-code, скилл окажется в ~/.claude/skills/numa-programming/SKILL.md.

Что делает numa-programming?

Учит агента детектировать NUMA-топологию, привязывать процессы к узлам через numactl, работать с libnuma API, строить структуры данных с учётом сокетов и диагностировать удалённый доступ к памяти через perf stat.

Что нужно для работы скилла numa-programming?

Библиотека libnuma (apt install libnuma-dev), утилиты numactl и lstopo, многосокетная система с NUMA. Без libnuma код с numa_alloc_onnode не скомпилируется.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Языки программирования» →
discover-training-system InfraRSI A0 (human-authored) Скилл discover-training-system для Claude Code помогает выяснить, как устроена система обучения и какой путь кода исполняется. Запускается в начале задачи и при расхождении между настройкой и результатом. CX Codex +1 ★ 99звёзд репо gke-batch-hpc официальный google Скилл gke-batch-hpc для Claude Code запускает batch-задачи и HPC-нагрузки в GKE: обучение моделей, CFD-симуляции и build-фермы в кластере. CX Codex +1 6 390установок remember-interactive-programming официальный github Скилл remember-interactive-programming для GitHub Copilot напоминает агенту работать через живой REPL и проверять текущее состояние системы. Помогает в интерактивной разработке, особенно в Clojure. CX Codex +1 9 000установок pacsomatic K-Dense-AI Скилл pacsomatic для Claude Code готовит и запускает геномный процесс nf-core/pacsomatic для пар опухоль–норма с PacBio HiFi. Он работает с исходными BAM и поддерживает локальный запуск или отправку в планировщик. CX Codex +1 1 700установок nextflow K-Dense-AI Скилл nextflow для Claude Code помогает создавать, запускать и отлаживать пайплайны Nextflow DSL2 и процессы nf-core. Он включается при работе с файлами .nf, конфигурацией, тестами и неудачными запусками. CX Codex +1 1 600установок reactive-programming aj-geddes Скилл reactive-programming для Claude Code помогает строить реактивные потоки для интерфейсов, событий и асинхронных данных. Подключается к задачам с RxJS, потоками событий и управлением состоянием. CX Codex +1 498установок

Из того же набора140

Весь набор →
adc-dac-baremetal Скилл adc-dac-baremetal для настройки АЦП и ЦАП на микроконтроллерах: выбор каналов, время выборки, калибровка, DMA-буферы и выходное напряжение. Пригодится при работе с аналоговыми датчиками, аудио или управляющими сигналами. CX Codex +1 378установок resource-optimization-lowend Скилл resource-optimization-lowend помогает уменьшать расход flash и RAM в прошивках для MCU, разбирать linker map и оценивать глубину стека. CX Codex +1 376установок llvm-passes Скилл llvm-passes учит агента писать, собирать и тестировать проходы оптимизации LLVM через New Pass Manager. CX Codex +1 373установок openmp Скилл учит агента писать и чинить код с OpenMP: параллельные циклы, редукции, задачи, SIMD и выгрузка на GPU. CX Codex +1 371установок dpdk Скилл для работы с DPDK — инициализация EAL, настройка poll-mode драйверов, mbuf-пулы, rte_ring, huge pages, RSS и проверка через testpmd. CX Codex +1 369установок timers-pwm-baremetal Скилл timers-pwm-baremetal для настройки таймеров микроконтроллера без ОС: ШИМ для управления яркостью и скоростью, захват входных импульсов, периодические прерывания через SysTick. Работает на STM32 и других платформах с голым железом. CX Codex +1 367установок mlir Скилл для работы с MLIR — инфраструктурой компиляторов, где каждый уровень абстракции живёт в своём диалекте. Пригодится при разработке специализированных компиляторов и оптимизаторов. CX Codex +1 366установок hypervisor-internals Скилл hypervisor-internals для Claude Code объясняет аппаратную виртуализацию Intel VT-x и AMD-V: VMCS, VMCB, EPT/NPT и обработку VMEXIT. Описывает основы создания минимального гипервизора. CX Codex +1 365установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой