Class GCManager

Scope-based GC Manager for automatic lifecycle management of Julia objects.

This module provides efficient garbage collection integration between JavaScript and Julia runtimes using scope-based isolation.

Design:

Uses a Julia Vector{Any} as backing storage
Scope-based: each value belongs to a scope_id, scopes can be released independently
Thread-safe: protected by mutex in C layer
Concurrent-safe: scopes can be released in any order (safe for async)
Efficient: O(1) push, O(n) release (only touches scope's values)
FinalizationRegistry fallback: escaped objects are auto-cleaned when JS GC runs

API:

scopeBegin(): Create a new scope, returns unique scope_id
pushScoped(value, scopeId): Push value to specific scope
scopeEnd(scopeId): Release all values in scope
transfer(idx, newScopeId): Move value to another scope (for escape)

Index

Constructors

Accessors

capacity isInitialized isPerfInitialized perfCapacity perfSize size

Methods

close get getScope init perfInit perfMark perfPush perfRelease pushScoped registerEscape scopeBegin scopeEnd set transfer unregisterEscape

Constructors

constructor

new GCManager(): GCManager
Returns GCManager

Accessors

`Static`capacity

get capacity(): number
Get the current capacity of the root stack.

Returns number
- Defined in jlbun/gc.ts:170

`Static`isInitialized

get isInitialized(): boolean
Check if GCManager is initialized.

Returns boolean
- Defined in jlbun/gc.ts:67

`Static`isPerfInitialized

get isPerfInitialized(): boolean
Check if perf mode GC is initialized.

Returns boolean
- Defined in jlbun/gc.ts:223

`Static`perfCapacity

get perfCapacity(): number
Get the perf stack capacity.

Returns number
- Defined in jlbun/gc.ts:269

`Static`perfSize

get perfSize(): number
Get the current perf stack size.

Returns number
- Defined in jlbun/gc.ts:262

`Static`size

get size(): number
Get the number of protected objects.

Returns number
- Defined in jlbun/gc.ts:163

Methods

`Static`close

close(): void
Internal
Clean up the GC manager. Called by Julia.close().

Returns void
- Defined in jlbun/gc.ts:199

`Static`get

get(idx: number): unknown
Get the value at a specific index (for debugging).
Parameters
- idx: number
  The index to read
Returns unknown
The pointer at that index
- Defined in jlbun/gc.ts:145

`Static`getScope

getScope(idx: number): bigint
Get the scope ID of a value at the given index.
Parameters
- idx: number
  The index to query
Returns bigint
The scope ID (0 for global scope or unassigned)
- Defined in jlbun/gc.ts:131

`Static`init

init(capacity?: number): void
Internal
Initialize the GC manager. Called by Julia.init() after Julia is fully initialized.
Parameters
- capacity: number = ...
Returns void
- Defined in jlbun/gc.ts:43

`Static`perfInit

perfInit(capacity?: number): void
Initialize the performance mode GC stack. Only call this if you plan to use perf mode scopes.
Parameters
- capacity: number = 1024
  Initial capacity (default 1024)
Returns void
- Defined in jlbun/gc.ts:216

`Static`perfMark

perfMark(): number
Get the current perf stack position (mark point). Use this before pushing values, then release to this mark.

Returns number
Current stack position
- Defined in jlbun/gc.ts:233

`Static`perfPush

perfPush(value: JuliaValue): number
Push a Julia value onto the perf stack. The value will be protected until perfRelease() is called.
Parameters
- value: JuliaValue
  The Julia value to protect
Returns number
The index where the value was stored
- Defined in jlbun/gc.ts:244

`Static`perfRelease

perfRelease(mark: number): void
Release all values from mark position to current top. This is O(1) amortized - just resets the stack pointer and clears the slots.
Parameters
- mark: number
  The mark position to release to
Returns void
- Defined in jlbun/gc.ts:255

`Static`pushScoped

pushScoped(value: JuliaValue, scopeId: bigint): number
Push a Julia value with explicit scope ownership. The value will be protected until scopeEnd(scopeId) is called.
Parameters
- value: JuliaValue
  The Julia value to protect
- scopeId: bigint
  The scope this value belongs to
Returns number
The index in the stack where the value was stored
- Defined in jlbun/gc.ts:95

`Static`registerEscape

registerEscape(value: JuliaValue, idx: number): void
Register an escaped value with FinalizationRegistry. When the JS object is garbage collected, the Julia root slot will be cleared.
Parameters
- value: JuliaValue
  The Julia value to register
- idx: number
  The index in the GC stack where the value is stored
Returns void
- Defined in jlbun/gc.ts:181

`Static`scopeBegin

scopeBegin(): bigint
Begin a new scope and get a unique scope ID. Values pushed with this scope_id will be released together when scopeEnd is called.

This is the recommended API for async scopes that may run concurrently.

Returns bigint
A unique scope ID (never 0, which is reserved for global scope)
- Defined in jlbun/gc.ts:83

`Static`scopeEnd

scopeEnd(scopeId: bigint): void
End a scope and release all values belonging to it. This is safe to call even if other scopes are still active.
Parameters
- scopeId: bigint
  The scope to release
Returns void
- Defined in jlbun/gc.ts:105

`Static`set

set(idx: number, value: JuliaValue): void
Set a value at a specific index. Used internally for clearing slots.
Parameters
- idx: number
  The index to write
- value: JuliaValue
  The value to store
Returns void
- Defined in jlbun/gc.ts:156

`Static`transfer

transfer(idx: number, newScopeId: bigint): number
Transfer a value to a different scope (for escape). The value will now be released when the new scope ends.
Parameters
- idx: number
  The index of the value to transfer
- newScopeId: bigint
  The new scope to transfer to (use 0n for global/permanent)
Returns number
The same index, or -1 on error
- Defined in jlbun/gc.ts:117

`Static`unregisterEscape

unregisterEscape(value: JuliaValue): void
Unregister an escaped value from FinalizationRegistry. Call this if you manually release the value.
Parameters
- value: JuliaValue
  The Julia value to unregister
Returns void
- Defined in jlbun/gc.ts:191