Use ORC for deterministic cleanup in graph‑heavy Nim services

Use ORC for deterministic cleanup in graph‑heavy Nim services

When a Nim service processes graph‑like data (e.g., scene graphs, dependency trees) the default tracing collector --gc:refc can introduce stop‑the‑world pauses that hurt tail latency. Compiling with the ORC garbage collector gives reference counting with an incremental cycle collector, providing prompt destructor runs and eliminating full‑heap pauses.

Useful takeaway: compile your whole program with --gc:orc (and --threads:on if you need parallelism) to get deterministic refcount‑based cleanup while still reclaiming reference cycles.

How ORC changes object lifetime

ORC is a compile‑time selector. The Nim instrumented code increments a reference count on every assignment to a ref type and decrements it when the reference goes out of scope. When the count reaches zero the object's destructor runs immediately, without waiting for a GC cycle.

Example showing prompt cleanup:

type Node = ref object
  value: int
  destructor: proc (self: Node) =
    echo "Node ", self.value, " freed"

proc makeNode(): Node =
  result = Node(value: 42)

proc use() =
  let a = makeNode()
  let b = a   # refcount ++
  # leaving `use` drops `a` and `b`; refcount reaches zero
  # destructor prints immediately

Compile the file with:

nim c --gc:orc --threads:on app.nim

Run this command from the directory that contains app.nim. No special privileges are required; the flag applies to the current compilation unit and all imported Nim modules. The generated C code will contain calls to nimIncRef and nimDecRef around each reference assignment.

Limits and common mistakes

• ORC still incurs a small runtime cost for the incremental cycle collector; if you know your data structure is acyclic you may prefer --gc:arc to avoid that overhead.
• Mixing GC modes across dependencies is unsafe. All Nim code linked into the binary must be compiled with the same --gc:arc, --gc:orc or --gc:refc flag; otherwise the refcount layout differs and the program can crash.
• When --threads:on is used, refcount updates must be thread‑safe. Any Nim procedure that can be called from another thread should be marked with the {.gcsafe.} pragma, and you must avoid implicit GC operations (e.g., allocating a seq inside a callback) unless the allocator is thread‑local.
• Finalizers run when the reference count reaches zero, but the order between interdependent objects is not guaranteed. Do not rely on a finalizer of one object to execute before another's finalizer for correctness.
• If you deliberately choose ARC to avoid the incremental collector cost, remember that ARC does not collect reference cycles. Break cycles manually with weakref or switch to ORC when cycles are possible.

Practical way to check the result

1. Compile three variants of the same program:
   • nim c --gc:refc app.nim
   • nim c --gc:arc app.nim
   • nim c --gc:orc app.nim
2. Run each binary under a realistic load (e.g., a request‑processing loop that creates and drops many Node objects).
3. Use the --showGcStats flag to print GC activity. With ORC you should see destructor side effects (e.g., the echo in the example) occurring promptly after the last reference drops, rather than being clustered after a pause.
4. Inspect the generated C (nimcache/app.c) for the presence of nimIncRef and nimDecRef calls around reference assignments; their absence indicates the tracer is still in use.
5. Monitor allocation rate and tail latency (e.g., p99 response time) before and after switching to ORC. If latency regresses, keep the previous binary as a rollback option and redeploy it while you investigate.