mcap/modules/Default_Allocator/DIFFERENCES.md

How this Default_Allocator differs from Jai's

This module replaces Jai's modules/Default_Allocator with the rpmalloc 2.0.1 port from my_modules/rpmalloc (installed with its install.jai). Jai finds the default allocator by module name, so the replacement is the directory that comes first on the import path. This document lists everything that behaves differently. Facts about Jai's module refer to Jai beta 0.2.030.

Everything here is tested by the port's suite, my_modules/rpmalloc/tests:

• jai build.jai - swap installs this module with install.jai, builds a program whose only allocator is the installed copy, runs that program, and type-checks it for macOS and Linux.
• The port's own suite (89 tests) covers the allocator code itself.

1. Which allocator you get

Platform	Jai's Default_Allocator	This module
Windows x64	Stripped-down rpmalloc 1.4.4: one heap shared by every thread behind one lock, and no thread caches	rpmalloc 2.0.1 (port), one heap per thread (tested)
Linux x64	The same as on Windows x64	The same as on Windows (type-checked only; there is no Linux machine)
macOS ARM64	A thin wrapper over the C runtime's malloc / realloc / free	rpmalloc 2.0.1 (port) (tested)
macOS x64, Linux ARM64	Linux ARM64: C runtime wrapper; macOS x64: stripped-down rpmalloc 1.4.4	Builds, but untested
PS5, Switch 2, iOS, Android, WASM, 32-bit	Their own branches (rpmalloc 1.4.4 on PS5 and Switch 2; the C runtime wrapper elsewhere)	Not supported. The module stops with an #assert. Take my_modules off the import path for these targets.

The CAPS string tells you which allocator is in use: "rpmalloc 2.0.1 (Jai port) as Default_Allocator". Jai's reports "stripped-down rpmalloc 1.4.4 intended as Default_Allocator", or "Jai wrapper for C’s malloc/free/realloc functions.".

2. Exported interface

Name	Jai's	This module
allocator	Yes (rpmalloc branch only)	Yes
allocator_proc	Yes	Yes, same signature
unsafe_reset()	rpmalloc branch: forgets all state and starts over. C runtime branch: does nothing.	Releases every lock and keeps all state (§6)
initialize_if_needed() -> bool	Yes	Yes
is_initialized() -> bool	Yes	Yes
finalize()	Yes	Yes (the port's finalize)
usable_size(ptr) -> s64	Yes	Yes
is_this_yours(heap, ptr) -> bool	Walks the heap's span lists. It misses older large blocks (finding F4/M2, test HEAP-05) and the blocks of exited threads (HEAP-10). With a null heap it looks only in the one default heap.	Looks the address up in a bitmap of live spans and never reads memory it does not own. With a null heap it checks every thread heap (not first-class heaps).
heap_free_all(heap)	Yes	Yes
global_statistics()	A placeholder struct of 7 fields, always zero	rpmalloc's Global_Statistics (9 fields). It is zero unless ENABLE_STATISTICS. The memory committed now is active; committed and decommitted are running totals that only grow, as upstream. The pointer form global_statistics(*stats) also exists.
heap_statistics(heap)	{sizecache, spancache}	{allocated_size, committed_size, mapped_size}, zero unless HEAP_STATISTICS
allocator_default_heap	A global *Heap	Not provided. There is no single default heap; each thread has its own.
The rest of the rpmalloc API	No	initialize, thread_collect, trim, rpmalloc, rpaligned_alloc, heap_acquire, and the rest (see my_modules/rpmalloc/module.jai)

Module parameters. ENABLE_ASSERTS and ENABLE_VALIDATE_ARGS have the same names and defaults (both true). The port's other parameters are added: statistics, decommit, unmap, first-class heaps, the huge cache and test hooks. Runtime_Support imports the module without parameters, so the context allocator always uses the defaults. Importing it with other parameters creates a separate instance with its own state; the context allocator is not affected.

3. Allocator protocol

Mode	Jai's	This module
ALLOCATE / RESIZE / FREE with data == null	rpmalloc branch: the one default heap, behind a global lock. C runtime branch: malloc.	The calling thread's own heap, with no lock on the fast path. A block freed by another thread is handed back to its owning heap without blocking.
Out of memory	Asserts with asserts on (N1, tests SIZE-01 and SIZE-07)	Returns null
Negative or impossibly large size	Not caught (F11, SIZE-02 and SIZE-03). The C runtime wrapper panics in debug builds (N5).	Returns null; a refused RESIZE leaves the block intact
RESIZE old_size	Ignored	When the block moves, old_size bytes are copied; 0 means the whole old block. Passing a positive old_size smaller than the live data loses the rest.
RESIZE to the same size	Can move the block (I1, RE-02)	Keeps it
A refused RESIZE	Returns the old pointer (L6, RE-04)	Returns null
STARTUP	Does nothing; returns null	initialize(); returns null. Process/posix.jai stores this return value in context.allocator.data, where null means "the thread's heap".
SHUTDOWN	Forgets the default heap; later use fails (F3, LIFE-01)	finalize(); the next allocation initialises again
THREAD_START / THREAD_STOP	Do nothing	Set up / release the thread's heap. Both are optional: a thread gets its heap on its first allocation, and the heap is released when the thread exits. Jai's Thread module sends these only on Windows (N4).
CREATE_HEAP	rpmalloc branch: yes. C runtime branch: asserts.	Yes (with FIRST_CLASS_HEAPS, the default)
DESTROY_HEAP	Releases the heap; a new heap can then claim the destroyed heap's blocks (F5, HEAP-01). Blocks still in it leak: 1,970 MiB over 190 heaps (HEAP-11).	Frees every block in the heap, then releases it
IS_THIS_YOURS	rpmalloc branch: see §2. C runtime branch: asserts.	See §2
CAPS flags	rpmalloc branch: general heap, threads, CREATE_HEAP, FREE, ACTUALLY_RESIZE, IS_THIS_YOURS. C runtime branch: no heaps, no IS_THIS_YOURS.	The same as the rpmalloc branch, on every platform

First-class heaps. A heap from CREATE_HEAP is for one thread at a time, as in upstream rpmalloc. Putting it in a Context that several threads copy lets them race on it.

4. Threads

• Heap per thread. Each thread allocates from its own heap, kept in OS thread-local storage (TlsAlloc/FlsAlloc, or a pthread key). A Context copied to another thread does not share the heap.
• Heaps of exited threads are reused. A thread's heap is released when the thread exits, even without THREAD_STOP, and the next new thread takes it over. With Jai's module on Windows and Linux, all threads share one heap behind one lock: there is no per-thread state, but every allocation contends for that lock.
• Freeing another thread's block. A block freed by a thread other than its owner is queued without a lock. Its owner reuses it on that owner's next allocation, or on thread_collect(). If the owner has exited, or is idle in thread_idle(), the block is freed at once instead.
• Thread pools: call thread_idle(). A pool thread that sleeps makes no allocator calls, so blocks other threads free into its heap, and the heap's free pages, would stay committed until it wakes. Calling Default_Allocator.thread_idle() where a pool thread waits for work gives that memory back and parks the heap until the thread's next allocation. Jai's module has no per-thread state, so it needs no such call.
• Partly used pages per thread. Each heap keeps its own partly used pages, so a program with many threads holds some more memory in partly filled small pages (64 KiB each) than one shared heap would. Larger pages are committed as they fill.

5. Memory use

• Retention. The port keeps freed pages per thread and huge blocks in a cache of up to 128 MiB committed (HUGE_CACHE_LIMIT_MB; a program that frees and allocates many huge blocks may run faster with more, holding up to that much while it does). Cached entries idle for a second are decommitted; blocks beyond the budget are unmapped. It decommits free pages only after a delay. Jai's rpmalloc branch returns memory eagerly, and pays page faults for it on reuse (F1, RET-01: about 112 faults per warm cycle). trim() returns every free page of the calling thread's heap, plus the whole huge cache, at once. thread_collect() does the same for pages past their delay.

• Address space. Memory is reserved in 256 MiB spans and committed page by page. Virtual size therefore looks large; the committed size is what costs memory. A 128 KiB bitmap for IS_THIS_YOURS is mapped once.

• Measured footprint (MiB with the benchmark's live set allocated; my_modules/rpmalloc/tests/results/BENCH-*.md):

  Benchmark	Windows: Jai's	Windows: this	macOS: Jai's (C runtime)	macOS: this
  churn_medium	204	170	148	66
  churn_large	157	260	128	7.8
  churn_huge	296	452	28.5	4.2

• macOS. The port decommits with MADV_FREE_REUSABLE, so freed memory leaves the process's footprint.

6. fork()

Process/posix.jai calls unsafe_reset() in the child, then allocator_proc(.STARTUP). Jai's rpmalloc branch forgets its whole state at that point, so every block allocated before the fork leaks in the child. This module instead releases each lock that another thread of the parent might have held: the global heap lock, the heap-creation flag, the huge-cache lock, and an initialisation another thread had started. Everything else stays as it was. The forking thread's heap and its blocks remain valid in the child. Like Jai's, it cannot repair a list another thread was in the middle of changing; that window is a few instructions under one of those locks. jai build.jai - swap checks this: without unsafe_reset the smoke test hangs, and with it the test passes.

7. Compile time

Code in #run allocates through this module as well; the swap smoke test checks this. Jai's module also works at compile time.

8. Build

• This module imports Basic, Bit_Operations and Atomics; Jai's imports nothing.
• Its code is about 4,000 lines; Jai's rpmalloc branch is about 2,000.
• Unsupported platforms fail to compile (§1).
• One Context field. The module adds rpmalloc_default_allocator_thread_heap (a pointer) to every program's Context, a cache of the thread's heap, so allocations and frees need no OS thread-local storage call. A second import of the module with other parameters must pass CONTEXT_HEAP_CACHE = false, since two imports cannot add the same field. Jai's module adds nothing to the Context.
• It works in programs built with arithmetic_overflow_check = .FATAL: no code relies on unsigned wraparound. In my_modules/rpmalloc/tests, jai build.jai - swap overflow=fatal and the port's suite with overflow=fatal test this. Both pass on Windows and macOS; Linux is type-checked only.

9. Speed

Median ns per operation, module defaults, from my_modules/rpmalloc/tests/results/BENCH-*.md; lower is better.

Benchmark	Windows: Jai's	Windows: this	macOS: Jai's (C runtime)	macOS: this
pair_64 (alloc + free of 64 B)	34.3	13.1	9.7	12.2
pair_mixed (16..1024 B)	256	15.5	23.6	13.4
churn_medium (1..64 KiB)	1059	51.7	74.0	53.2
churn_large (64 KiB..1 MiB)	4600	32.3	122	30.9
churn_huge (2..32 MiB)	9526	20245	618	4751
realloc_double (64 B to 8 MiB)	184662	15492	6373	6601
mt_churn_8 (8 threads)	515	2.3	18.0	1.9
mt_producer (cross-thread frees)	484	46.4	122	87.3

On Windows this module is faster everywhere except churn_huge (replacing blocks of 2 MiB and up), where it is 2× slower. On macOS, where Jai's module is the system malloc, it is level or faster except on pair_64 (0.8×) and churn_huge (7× slower). That gap is shelved in the plan.

10. Test results

The test suite was run against Jai's module and against the port:

Platform	Jai's Default_Allocator	This module's code (the port)
Windows x64 (Jai's: rpmalloc 1.4.4)	30 pass, 11 fail, 4 crash (41 skipped: capabilities it lacks)	82 pass; every other test is SKIP or N/A
macOS ARM64 (Jai's: C runtime malloc)	30 pass, 6 fail, 2 crash (48 skipped)	83 pass; every other test is SKIP or N/A

What Jai's module fails, by kind:

• Correctness, Windows:
  • SIZE-01 and SIZE-07 assert when the OS refuses memory.
  • SIZE-02 and SIZE-03 accept negative sizes.
  • RE-02: a same-size resize moves the block.
  • RE-04: a refused resize returns the old pointer.
  • HEAP-01: a new heap claims a destroyed heap's blocks.
  • HEAP-05 and HEAP-10: IS_THIS_YOURS misses blocks it owns.
  • HEAP-11: destroyed heaps leak their blocks.
  • LIFE-01: the allocator is unusable after SHUTDOWN.
• Correctness, macOS: SIZE-02 crashes on a negative size, and RE-04 is the same as on Windows.
• Memory behaviour, Windows: RET-01, RET-06, RET-10 and RET-14 fail on page faults. Freed memory goes back to the OS and faults in again on every reuse (up to 2,053 faults per 8 MiB cycle).
• Memory behaviour, macOS: OS-07, RET-02, RET-07, RET-11 and RET-12 fail because the system malloc keeps freed memory private (258 of 258 MiB after freeing everything). THR-09: blocks freed by another thread are not reused first.

One upstream bug remains open in the port: U15 (POSIX only; at most one heap per exiting thread can leak, in a rare destructor order). See my_modules/rpmalloc/module.jai.

11. Before you switch a project

• Check every RESIZE / realloc call for a correct old_size (§3). Jai's module ignores it; this one relies on it.
• Expect a larger footprint on Windows for large and huge blocks, or call trim() at quiet points.
• Workloads with many huge blocks (2 MiB and up) are slower than with Jai's module (§9).
• Supported platforms are Windows and macOS; Linux is type-checked only.
• A block must still be freed by the allocator that made it. Each program and DLL compiled with this module has its own instance, just as with Jai's.