nx_pteam.nx
buildroot/runtime/nx_pteam.nx
about
nx_pteam.nx -- PERSISTENT BARRIER TEAM (fork-join parallel-for), the pool-
scaling fix. MEASURED (2026-07-10): the channel pool scales only ~4.5x on
14 threads (gcc OpenMP 8.8x) because workers pick tasks off the MPMC
channel via CONTENDED CAS -> serialized start. A fork-join team fixes it:
each worker owns a FIXED band index and reads it from a shared descriptor,
so all workers start SIMULTANEOUSLY -- no channel, no per-task queue, one
generation bump instead of 14 sends+wakes. Idle = futex-sleep on the
generation word (0 CPU), same eventcount discipline as the futex pool.
API: nx_pteam_new(n) ; nx_pteam_run(t, fn, ctx) calls fn(band, ctx) once
per band in [0,n) across the team and returns when all bands finish.
SINGLE-DRIVER (one thread calls run at a time) -- matches the LLM forward.
genealogy_id: openmp_static_forkjoin + eventcount_futex
lineage_id: substrate_pteam_v1
dependencies 6 imports · 3 importers
imports: nx_syscalls.nxnx_tier.nxnx_atom.nxnx_thread.nxnx_thread_pool.nxnx_hw.nx
imported by: nx_f32_lazy_weight.nxnx_pteam_gate.nxnx_raster_bench.nx
structs
| 39 | struct NxPTeam |
consts
| 23 | const PT_FUTEX: i64 = 98 // rv64 futex -> x86 202 (blessed table row) |
| 24 | const PT_WAIT_PRIV: i64 = 128 // FUTEX_WAIT | PRIVATE |
| 25 | const PT_WAKE_PRIV: i64 = 129 // FUTEX_WAKE | PRIVATE |
| 26 | const PT_SPIN: i64 = 50000 // BUSY-spin iters before sleeping (no sched_yield syscall; |
| 29 | const PT_SETAFF: i64 = 122 // rv64 sched_setaffinity -> x86 203 (blessed table row) |
| 52 | const NX_PTEAM_BYTES: i64 = 128 // >64 for the added field + head-line pad |
| 53 | const PT_OFF_GEN: i64 = 24 |
| 54 | const PT_OFF_DONE: i64 = 32 |
| 55 | const PT_OFF_ALIVE: i64 = 40 |
| 56 | const PT_OFF_SD: i64 = 48 |
| 57 | const PT_OFF_DWAIT: i64 = 56 |
| 58 | const PT_OFF_FLAGS: i64 = 64 |
| 59 | const PT_FLAG_STRIDE: i64 = 64 // one cache line per worker flag (no false sharing) |
functions
| 33 | func _pt_setaffinity(core: i64) -> i64 calls 1: sys_mmap |
| 62 | func _pt_wait(addr: *i64, seen: i64) -> i64 |
| 65 | func _pt_wake(addr: *i64) -> i64 |
| 70 | func _pteam_worker(arg: *u8) -> i64 |
| 126 | func nx_pteam_new(n_workers: i64) -> *NxPTeam |
| 165 | func _pt_all_done(flags: i64, nw: i64, gen: i64) -> i64 |
| 174 | func nx_pteam_run(t: *NxPTeam, fn: func(i64, i64) -> i64, ctx: i64) -> i64 |
| 222 | func nx_pteam_shutdown(t: *NxPTeam) -> i64 called by 2: mainmain calls 5: nx_atom_store_i64nx_atom_faa_i64_pt_wakenx_atom_load_i64nx_thread_yield |