Allocator Decision Record (ADR): jemalloc Evaluation

[justinjoy]

Allocator Decision Record (ADR): jemalloc Evaluation

Date: 2026-02-23
Status: Decided — jemalloc not adopted for Phase 0-1
Participants: Planner, Architect, Critic (consensus planning)

Context

wirelog targets both embedded (ARM/RISC-V, <256MB) and enterprise (x86-64, GB-scale) environments.
Current C11 codebase has ~35 allocation calls (malloc/calloc/realloc) across 5 files (parser, AST, IR, program).
Memory-intensive execution is delegated to Differential Dataflow (Rust) via FFI.

Decision

Do not adopt jemalloc in Phase 0-1. Design Region/Arena allocator after Phase 2 benchmarks.

Rationale

1. C11 side handles only query-scale allocations: wirelog C11 manages parser/optimizer memory only.
   Data-scale (GB) memory is managed by DD's Rust allocator. jemalloc provides no practical benefit
   for the C11 layer.

2. Embedded target conflict: jemalloc's ~2MB metadata overhead directly conflicts with the
   500KB-2MB standalone binary target for embedded deployments.

3. Arena/Region is a better fit: AST and IR follow a clear "create -> use -> bulk-free" lifecycle
   (3 distinct phases: parsing, IR conversion, program metadata). This pattern is ideal for
   Region-based allocation, not general-purpose allocator replacement.

4. Premature optimization: 35 allocation calls in Phase 0 are not a bottleneck. Optimizer passes
   (Phase 1) will introduce new allocation patterns that must stabilize before designing the allocator.

Alternatives Considered

Alternative	Verdict	Reason
jemalloc	Deferred	~2MB overhead, no benefit for query-scale allocations
mimalloc	Deferred	Smaller than jemalloc but same fundamental mismatch
Self-built Arena	Preferred (Phase 2)	Matches AST/IR lifecycle; simplifies error-path cleanup
Region-based allocator	Preferred (Phase 2)	Hierarchical regions map to parsing/IR/program phases
System malloc (current)	Retain (Phase 0-1)	Sufficient for current scale; no bottleneck evidence
wl_allocator_t interface	Phase 1 late	Define after optimizer allocation patterns stabilize
Meson build-time selection	Phase 2+	option('allocator', ...) following existing embedded/threads pattern

Re-evaluation Trigger

If Phase 2 benchmarks show system malloc as a measurable bottleneck
in the enterprise path, reconsider jemalloc or mimalloc for that target only.

Open Items from This Review

• DD FFI memory ownership (copy vs transfer vs shared buffer) affects allocator category design
• strdup_safe exists as 3 independent static copies — consolidate into shared internal utility
• WIRELOG_EMBEDDED build macro is defined but not yet used in C source #ifdef guards