`(sigil gc)`

(sigil gc) - Garbage Collector Control

Control the garbage collector for diagnostics, manual collection, and fine-tuning for latency-sensitive applications like games.

(import (sigil gc))

;; Force immediate garbage collection
(gc-collect!)

;; Spread GC work across game frames
(define (game-loop)
  (gc-step! 100)  ; Process up to 100 objects per frame
  (update)
  (render)
  (game-loop))

;; Check memory usage
(gc-allocated-bytes)  ; => 1234567

Exports

gc-collect!procedure

Force a full garbage collection cycle.

Pauses execution until all unreachable objects are freed. Use sparingly—may cause noticeable pauses.

(gc-collect!)

gc-step!procedure

Perform incremental GC work.

Processes up to the specified number of objects, then returns. Use in game loops to spread GC work across frames and avoid pauses.

;; In your game loop:
(gc-step! 100)  ; Process up to 100 objects per frame

gc-allocated-bytesprocedure

Get the current heap size in bytes.

Returns the total memory currently allocated by the garbage collector. Useful for monitoring memory usage and detecting leaks.

(gc-allocated-bytes)
; => 1234567

;; Monitor allocation in a loop
(let ((before (gc-allocated-bytes)))
  (do-work)
  (- (gc-allocated-bytes) before))
; => 5000  ; bytes allocated during do-work

gc-phaseprocedure

Get the current GC phase.

Returns a symbol indicating what the collector is currently doing:

idle — not collecting, normal execution
marking — tracing live objects
sweeping — reclaiming dead objects

(gc-phase)
; => idle

(gc-step! 10)
(gc-phase)
; => marking  ; or sweeping, depending on progress

gc-thresholdprocedure

Get the allocation threshold that triggers the next GC cycle.

When gc-allocated-bytes exceeds this value, a collection begins. The threshold grows automatically as your program uses more memory.

(gc-threshold)
; => 2000000

;; Check how close to triggering GC
(- (gc-threshold) (gc-allocated-bytes))
; => 765433  ; bytes until next GC

gc-statsprocedure

Get detailed GC statistics as an association list.

Returns all GC metrics in one call. Fields include:

allocated-bytes — current heap size
threshold — bytes until next GC triggers
phase — current collector phase
gray-count — objects pending marking (during collection)

(gc-stats)
; => ((allocated-bytes . 1234567)
;     (threshold . 2000000)
;     (phase . idle)
;     (gray-count . 0))

;; Extract a specific stat
(cdr (assq 'allocated-bytes (gc-stats)))
; => 1234567