Reduce static TLS from 856 to 16 bytes with a heap-allocated per-thread struct

[devmotion]

Follow-up to #57. Fixes #56.

PR #50 made the generators' setup caches _Thread_local to fix data races, which gave libRmath-julia an 856-byte static TLS segment. glibc draws a dlopen'd module's TLS block from a fixed ~1664-byte process-wide surplus shared with every other shared library, so consuming half of it made unrelated libraries fail to load:

ERROR: InitError: could not load library "libgomp.so.1"
libgomp.so.1: cannot allocate memory in static TLS block

The glibc.rtld.optional_static_tls tunable that would raise the surplus only exists from glibc 2.32, so it does not help the affected users (#56 reports glibc 2.27).

Approach

Move the state to the heap, in one Rmath_tls container reached through a single thread-local pointer. 856 → 16 bytes: that pointer, plus sunif.c's seed.

Each generator keeps its own struct, nested in one container so there is one allocation, one free and one cleanup registration. Field names are unchanged from upstream so re-applying patches/thread-local.patch after make update stays mechanical.

sunif.c's I1/I2 stay _Thread_local deliberately: 8 bytes is exactly the size of the pointer that would replace it (zero gain), it is the hottest path in the library, and set_seed() returns void so it could not report an allocation failure.

Every field moved was confirmed to be written — by const-qualifying each one and checking the compiler rejects the assignment. All 74 qualify; the read-only coefficient tables stay const static, per the rule #57 added to the README.

Cleanup is automatic, with no new public API

include/Rmath.h is untouched. src/rmath_tls.c registers a thread-exit destructor via pthread_key_create() on POSIX and FlsAlloc() on Windows.

Windows avoids pthreads deliberately: on mingw-w64 -lpthread resolves through winpthreads and adds a runtime dependency on libwinpthread-1.dll, which Rmath_jll does not ship (its Yggdrasil recipe declares no dependencies) — the same class of load failure this PR fixes. On every Unix target -lpthread is free: libpthread.so.0 is part of glibc itself (folded into libc from 2.34), musl's is an empty stub, macOS has it in libSystem and FreeBSD in base.

Two pre-existing bugs fixed along the way

• wilcox_free() never freed anything for m,n ≤ 50. It routed through a helper guarded on m > WILCOX_MAX || n > WILCOX_MAX, but w_init_maybe() floors both allocated_* at WILCOX_MAX, so the test never fired. Harmless upstream where the table is a process-wide cache; a ~25 kB per-thread leak since Improve thread-safety #50 made it _Thread_local.
• src/Makefile had no header dependencies. Editing a header rebuilt nothing. Survivable while the headers were stable, but rmath_tls.h is included by seven .c files and declares Rmath_tls_ptr as _Thread_local: a partial rebuild links objects that disagree about whether to reach it through TLS, which links fine and then segfaults on the first call. Found the hard way on this branch.

Verification

• RNG stream byte-identical to pre-refactor: 288 000 variates over a parameter schedule covering every algorithm branch, with repeats and alternations to exercise both cache hit and invalidation.
• d/p/q signrank/wilcox byte-identical, including through the reallocation paths and the public *_free() calls.
• Cleanup measured: *_free() releases 24 624 of the 25 536 bytes allocated; heap stays flat across 2000 thread create/join cycles, against 49.7 MB leaked with the destructor disabled.
• make update round-trip: the regenerated patch applies to pristine R 4.4.1 sources and reproduces the working tree byte-for-byte in all eight files.
• Not slower. Loads per object dropped 40–61% and TLV relocations went from 36–100 to 2. On Darwin every _Thread_local access is a thunk call, so rhyper went from 23 per invocation to one, measuring 30–38% faster. Expect roughly neutral on Linux, where GCC already hoists one __tls_get_addr per function.

Notes for review

• The container is 856 bytes with zero padding waste — the same bytes as before, moved from a rationed pool to an unrationed one. It is also now lazy: a thread that never calls these generators pays nothing, where before every thread in the process paid eagerly.
• rhyper reuses the cached s as a scratch temporary (s = ym / yn in branch III's large case), so that slot never needed caching. The aliasing is preserved exactly rather than "fixed", to keep the stream identical.
• The new test.jl testset was verified to fail when the container pointer is made process-wide. CI now runs with four threads; it was single-threaded, so the pre-existing threaded testset never actually exercised concurrency.
• No leak test for the thread-exit destructor: Julia pools its threads, so none ever exits and the destructor never fires. That path was verified with a C driver instead.

🤖 Generated with Claude Code

[nalimilan]

Impressive!

[nalimilan]

How about doing beta = st->beta after loading st? That would reduce the diff size and reduce the risk of conflicts when updating Rmath version.

[devmotion]

Copying in doesn't quite work here: these are a cache that survives across calls (keyed on olda/oldb), so without a copy-back before every return qsame would just serve stale coefficients. rhyper and rpois have a lot of exits and I would rather not depend on getting that right.

So instead I aliased the fields back to the upstream names at the fetch site:

    struct rbeta_state *st = &Rmath_tls_get()->rbeta;
#define beta	st->beta
#define olda	st->olda

with #undefs after the function. The bodies are byte-identical to R's now, which helps more than copy-in would have: upstream lines removed by the patch went 245 -> 38 (rhyper.c: 92 -> 10), and they are all in the declaration block, so upstream algorithm changes can no longer conflict. Patch went 1447 -> 804 lines.

If a future R version adds a local with a colliding name, the alias expands into it and it fails to compile at that line, which seems like the right failure mode. Noted in the README.

Does not work for signrank.c/wilcox.c since the state is shared with w_init_maybe/csignrank/cwilcox and has to be passed as a parameter there.

Stream is byte-identical (288k variates over all algorithm branches, clang and gcc-15).

[nalimilan]

Nice. Is it really useful to call #undef at the end of the file though? For .c file (which are not #included anywhere), does it make any difference?

[devmotion]

Good point, they're at EOF in every one of those files so they guard nothing — dropped.

[devmotion]

Pushed 9f0ecb5. Two things in there that you did not ask for:

make update was broken, and would have silently undone part of #50. patches/thread-local.patch had a hunk for src/sunif.c, but R ships that file under src/nmath/standalone/, which the extraction in the update target excludes. So the hunk was re-applied to a file that had never been reset:

patching file src/sunif.c
Reversed (or previously applied) patch detected!  Assume -R? [y]

Non-interactively patch answers [y], i.e. it reverses the hunk and strips _Thread_local off I1/I2, putting the seed data race back. Dropped the hunk (sunif.c keeps the qualifier as committed) and wrote the rule down in the README, since the trap is easy to walk back into when regenerating the patch.

CI now asserts the static TLS size, which the README claimed but nothing enforced. readelf on the Linux job, budget 64 bytes against the actual 16. Given that the whole problem in #56 is that growth here breaks other libraries, a regression should not have to be noticed by a downstream user.

Verification, all re-run after the rewrite:

• RNG stream over 288 000 variates and d/p/q signrank/wilcox byte-identical to master under both clang and gcc-15. (The two compilers do not agree with each other on arm64 — FP contraction — but each agrees with master.)
• Heap flat across 2000 thread create/join cycles; *_free() still releases 24 624 of 25 536 bytes.
• Allocation failure exits 1 with the message, under an interposed failing calloc.
• Patch applies with no prompts and reproduces the tree byte-for-byte in all 128 files of src/.
• julia --threads=4 test.jl passes.