Memory Management and Garbage Collection

Relevant source files

• bench/snippets/escapeHTML.mjs
• scripts/build/deps/mimalloc.ts
• scripts/build/unified.ts
• scripts/verify-baseline-static/allowlist-aarch64.txt
• scripts/verify-baseline-static/allowlist-x64-windows.txt
• scripts/verify-baseline-static/allowlist-x64.txt
• src/api/lib.rs
• src/ast/fold_string_addition.rs
• src/bun_bin/phase_c_exports.rs
• src/bun_core/Global.rs
• src/bun_core/debug.rs
• src/bun_core/lib.rs
• src/bun_core/output.rs
• src/bun_core/string/immutable.rs
• src/bun_core/string/immutable/escapeHTML.rs
• src/bundler/BundleThread.rs
• src/bundler/Cargo.toml
• src/crash_handler/lib.rs
• src/hash/Cargo.toml
• src/hash/xxhash.rs
• src/highway/lib.rs
• src/install_types/resolver_hooks.rs
• src/js/builtins/ProcessObjectInternals.ts
• src/js/builtins/ReadableByteStreamController.ts
• src/js/builtins/ReadableByteStreamInternals.ts
• src/js/builtins/ReadableStream.ts
• src/js/builtins/ReadableStreamBYOBReader.ts
• src/js/builtins/ReadableStreamBYOBRequest.ts
• src/js/builtins/ReadableStreamDefaultController.ts
• src/js/builtins/ReadableStreamDefaultReader.ts
• src/js/builtins/ReadableStreamInternals.ts
• src/js/internal-for-testing.ts
• src/jsc/bindings/BunObject.cpp
• src/jsc/bindings/BunObject.h
• src/jsc/bindings/InternalForTesting.cpp
• src/jsc/bindings/InternalForTesting.h
• src/jsc/bindings/escapeHTML.cpp
• src/jsc/bindings/highway_strings.cpp
• src/jsc/bindings/xxhash3.cpp
• src/jsc/btjs.rs
• src/md/ansi_renderer.rs
• src/runtime/api/crash_handler_jsc.rs
• src/sys/copy_file.rs
• src/sys/windows/mod.rs
• src/windows_sys/externs.rs
• test/cli/run/fixture-crash.js
• test/cli/run/run-crash-handler.test.ts
• test/js/bun/css/nth-anplusb-ident.test.ts
• test/js/bun/jsc/heapStats-mimalloc.test.ts
• test/js/bun/perf/static-initializers.test.ts
• test/js/bun/test/concurrent-max.fixture.ts
• test/js/bun/test/concurrent.test.ts
• test/js/bun/util/escapeHTML.test.js
• test/js/node/http/fixtures/log-events.mjs
• test/js/node/process/process.test.js
• test/js/node/test/parallel/test-http-chunk-problem.js
• test/js/node/test/parallel/test-whatwg-readablebytestream.js
• test/js/web/fetch/body-async-iterator.test.ts
• test/js/web/streams/streams-leak.test.ts
• test/js/web/streams/streams.test.js
• test/regression/issue/11297/11297.fixture.ts
• test/regression/issue/19661.test.ts

Bun combines the high-performance generational garbage collector of JavaScriptCore (JSC) with the low-overhead native memory management of Zig and Rust. This page details the integration between these two worlds, focusing on how Bun manages heap objects, type-specific allocations via IsoSubspaces, and native memory using mimalloc and arena allocators.

JavaScriptCore Garbage Collector Integration

Bun utilizes JavaScriptCore's generational, parallel, and concurrent garbage collector. The lifecycle of JavaScript objects is managed by the JSC::Heap, which is part of the JSC::VM.

VM and Heap Configuration

The JSC::VM is initialized with specific heap parameters to balance performance and memory footprint. Bun's global object, Zig::GlobalObject, extends Bun::GlobalScope and integrates directly with the JSC VM lifecycle. It maintains a pointer to the m_bunVM for better cache locality.

Sources:

• src/jsc/bindings/BunObject.h1-20
• src/jsc/bindings/BunObject.cpp1-50

Write Barriers and Object Invariants

To maintain the generational invariant (old-generation objects must not point to young-generation objects without the collector's knowledge), Bun strictly employs JSC::WriteBarrier. Bun also maintains a WriteBarrierList to track specific references within the global object.

Entity	Implementation	Purpose
JSC::WriteBarrier<T>	BunObject.h	Standard member field protection for GC cells.
visitChildren	BunObject.cpp	Traverses references during the marking phase.
visitOutputConstraints	BunObject.cpp	Handles constraints for concurrent GC marking.

Sources:

• src/jsc/bindings/BunObject.h1-40
• src/jsc/bindings/BunObject.cpp1-60

Native Allocations and Mimalloc

While JS objects live in the JSC heap, Bun's internal structures, buffers, and Zig-native data live in the native heap. Bun uses mimalloc, a performance-oriented allocator from Microsoft, as its primary native allocator scripts/build/deps/mimalloc.ts2-3

Mimalloc Configuration

Bun configures mimalloc to act as a global malloc replacement on Linux scripts/build/deps/mimalloc.ts37 It is tuned for performance with several specific flags:

• MI_SKIP_COLLECT_ON_EXIT: Skips the heap walk during process shutdown for faster exit scripts/build/deps/mimalloc.ts45
• MI_DEFAULT_ALLOW_THP: Disabled to save memory overhead (Transparent Huge Pages) on Linux scripts/build/deps/mimalloc.ts62
• MI_STATIC_LIB: Linked as a static library to avoid dynamic linking overhead scripts/build/deps/mimalloc.ts41
• MI_NO_PROCESS_DETACH: Skips mi_process_done as Bun is a static executable that exits via _exit scripts/build/deps/mimalloc.ts47-52
• MI_DEBUG: Set to level 3 in debug builds to enable heavy checks, guard bytes, and double-free detection scripts/build/deps/mimalloc.ts76-81

SIMD-Optimized String Operations

Bun leverages SIMD instructions via the Google Highway library for high-performance string operations, such as escaping HTML or finding characters. These operations are runtime-dispatched based on CPU features (AVX2, SVE, etc.) to ensure baseline compatibility while maximizing performance on modern hardware.

Sources:

• scripts/build/deps/mimalloc.ts15-113
• src/jsc/bindings/highway_strings.cpp20-38
• scripts/verify-baseline-static/allowlist-aarch64.txt10-40
• scripts/verify-baseline-static/allowlist-x64.txt17-40

Rust and Zig Memory Interaction

Raw Slices and Shared Memory

In the Rust core, Bun uses RawSlice<T> to manage non-owning borrowed slices where the backing storage outlives the holder. This is a byte-for-byte drop-in for raw pointers but provides a safer interface for re-borrowing as &[T] src/bun_core/lib.rs121-165

Internal Testing and Synthetic Limits

For testing purposes, Bun provides internal APIs to simulate memory-related conditions. The setSyntheticAllocationLimitForTesting function allows tests to enforce artificial memory limits src/js/internal-for-testing.ts141-145 Additionally, the crash_handler module provides functions like outOfMemory() to test Bun's behavior under extreme pressure src/js/internal-for-testing.ts99-106

Memory Statistics

Bun exposes memory usage statistics through process.memoryUsage() and specialized JSC internal helpers. In tests, xxHash3ForTesting and other bindings are used to verify the integrity of memory-intensive operations src/js/internal-for-testing.ts18-24

Code Entity	File	Role
RawSlice<T>	src/bun_core/lib.rs121	Transparent wrapper for raw slice pointers.
mimalloc	scripts/build/deps/mimalloc.ts17	Global memory allocator configuration.
Bun__setSyntheticAllocationLimitForTesting	src/js/internal-for-testing.ts143	Zig binding to restrict allocations in tests.
IndexOfCharImpl	src/jsc/bindings/highway_strings.cpp29	SIMD-accelerated character search.

Sources:

• src/bun_core/lib.rs121-170
• src/js/internal-for-testing.ts1-150
• test/js/bun/perf/static-initializers.test.ts1-70
• src/jsc/bindings/highway_strings.cpp1-40