Garbage Collection API

The GC singleton provides script-level control over the garbage collector for performance tuning and memory management.

Pause & Resume

Pauses automatic garbage collection. Objects continue to accumulate in memory.

Returns: the GC object (for chaining)

Resumes automatic garbage collection after a pause.

Returns: the GC object (for chaining)

Checks whether garbage collection is currently paused.

Returns: boolean

Collection

Forces an immediate garbage collection cycle. If GC is paused, it temporarily re-enables for this cycle and pauses again.

Returns: the GC object (for chaining)

// Force cleanup after a large temporary allocation
GC.cycle()

// Works even while paused:
GC.pause()
// ... allocate lots of temporary objects ...
GC.cycle()    // Collects garbage, then re-pauses

Memory Info

Returns the number of bytes currently allocated and tracked by the garbage collector.

Returns the current GC threshold — the byte count at which the next automatic collection triggers.

Threshold Configuration

Sets the GC threshold. Values below 1024 are clamped to 1024 to prevent thrashing.

• threshold (number) — the new threshold in bytes (minimum 1024)

Returns: the GC object (for chaining)

// Higher threshold = less frequent collections
GC.setBytesThreshold(1048576)   // 1 MB

// Lower threshold = more aggressive collection
GC.setBytesThreshold(65536)     // 64 KB

Common Patterns

Performance-Critical Section

GC.pause()

var i = 0
while (i < 100000) {
    // ... heavy allocation work ...
    i = i + 1
}

GC.cycle()     // Clean up all at once
GC.resume()    // Back to normal

Memory Monitoring

var before = GC.getBytesTracked()
doExpensiveWork()
var after = GC.getBytesTracked()
print("Allocated: " + str(after - before) + " bytes")

See also: Continuations API — List API — Map API