Overview

jemalloc is a general-purpose malloc(3) replacement with emphasis on fragmentation avoidance and scalable multi-threaded concurrency. It was originally developed for FreeBSD, adopted by Firefox, and later became the default allocator for Rust. Meta uses it across their entire C++ server fleet.

The PascalAI binding exposes the full jemalloc API: raw allocation, aligned allocation, arena management, per-thread cache control, heap profiling, and statistics — all via a thin wrapper over libpai_jemalloc.so.

Key Characteristics

Performance

jemalloc consistently outperforms the system allocator in multi-threaded workloads and reduces resident memory usage through better fragmentation management.

vs Other Allocators

Quick Start

Basic allocation and free

uses jemalloc;

{ Allocate 1024 bytes, use it, then free }
var ptr := Alloc(1024);
WriteLn('Allocated ' + IntToStr(AllocSize(ptr)) + ' usable bytes');
Free(ptr);

{ Allocate zeroed memory (safe for structs) }
var buf := AllocZero(64, 8);  { 64 elements x 8 bytes each }
FreeSized(buf, 64 * 8);      { faster free when size is known }

Aligned allocation (SIMD, DMA buffers)

uses jemalloc;

{ 64-byte alignment for AVX-512 SIMD operations }
var simdBuf := AllocAligned(64, 4096);
WriteLn('Aligned ptr: ' + IntToStr(simdBuf));
Free(simdBuf);

{ Resize an allocation (realloc-style) }
var p := Alloc(256);
p := Realloc(p, 512);
Free(p);

Arena per thread (isolate allocations)

uses jemalloc;

{ Create a dedicated arena and bind this thread to it }
var myArena := NewArena();
BindArena(myArena);
WriteLn('Thread using arena ' + IntToStr(CurrentArena()));

{ ... do work ... }

PurgeArena(myArena);   { return dirty pages to OS }
DestroyArena(myArena); { must be empty before destroy }

Dump statistics

uses jemalloc;

{ Human-readable stats to stderr }
PrintStats();

{ Machine-readable JSON }
var json := StatsJSON();
WriteLn(Copy(json, 1, 120) + '...');

{ Structured stats record }
var s := GetStats();
WriteLn('Allocated : ' + IntToStr(s.Allocated) + ' bytes');
WriteLn('Resident  : ' + IntToStr(s.Resident) + ' bytes');
WriteLn('Metadata  : ' + IntToStr(s.Metadata) + ' bytes');
WriteLn('Version   : ' + JEMallocVersion());

Types

TJEArena

An arena handle — an Integer index identifying a jemalloc arena. Returned by NewArena and CurrentArena. Pass to arena management functions.

TJEStats

Global allocator statistics snapshot returned by GetStats.

TJEArenaStats

Per-arena statistics returned by GetArenaStats(arena).

Allocation API

Core allocation functions. All pointers are returned as Int64 (raw address). You are responsible for tracking pointer lifetimes — jemalloc does not perform garbage collection.

Arena API

Arenas are independent memory pools. Assigning each thread a dedicated arena eliminates all cross-thread locking for allocation-heavy workloads.

Thread Cache API

The per-thread cache (tcache) is jemalloc's primary mechanism for lock-free fast-path allocation. Small objects are served from the tcache without touching the arena at all.

Statistics API

jemalloc maintains detailed internal counters updated atomically. Stats collection has negligible overhead and is safe to call in production.

Heap Profiling API

Heap profiling requires jemalloc built with --enable-prof. Output files are compatible with jeprof (a pprof-compatible tool) and can be visualized as flame graphs or call-graph PDFs.

uses jemalloc;

StartProfiling();

{ ... run your workload ... }
DumpProfile('/tmp/heap_before.heap');

{ ... more work ... }
DumpProfile('/tmp/heap_after.heap');

StopProfiling();

{ Analyze with: jeprof --pdf ./myapp /tmp/heap_after.heap > report.pdf }

Info API