Diagnosing Memory Leaks and Cycle Bloat in Nim ARC/ORC

The Problem: Unbounded RSS Growth

When moving from the legacy garbage collector to --mm:arc (Automatic Reference Counting) or --mm:orc (ORC), developers often encounter a steady increase in Resident Set Size (RSS) or unexpected latency spikes. Unlike the legacy mark-and-sweep collector, ARC/ORC relies on deterministic destruction. If you have circular references or incorrect ownership annotations, memory will not be freed, leading to a leak that looks like a traditional memory leak but is actually a failure of ownership logic.

Diagnostic Matrix: Identifying the Leak Type

Symptom	Likely Cause	Diagnostic Tool
Linear RSS growth; no recovery	Reference cycles or missing sink	--debug:memleak + Valgrind
Sudden CPU spikes / Pause spikes	ORC cycle collection triggering	GC_getStatistics()
C-library memory growth	Unmanaged pointers / Missing GC_unref	Valgrind --leak-check=full

Step-by-Step Diagnostic Workflow

1. Baseline Verification: Ensure you are using Nim 2.0+ (where ORC is default) or Nim 1.6+ for memory debugging tools. Confirm you are not mixing --mm:arc and --mm:refc in the same process, as this leads to undefined behavior.
2. Check for Ownership Warnings: Run the compiler with --warn:unused. In ARC/ORC, the compiler tracks whether a value is "borrowed" or "owned." If you see warnings about unused variables in functions taking sink parameters, you may be failing to transfer ownership, preventing the object from being destroyed.
3. Isolate Cycles: If you suspect a reference cycle, temporarily compile with --gc:markAndSweep. If the memory growth disappears, you have a reference cycle that ARC cannot handle and ORC is struggling to collect efficiently.
4. Memory Leak Profiling: Compile your application with --mm:orc --debug:memleak. Run the resulting binary through Valgrind:

   # Run on Linux with root/user permissions for the binary
   valgrind --leak-check=full ./your_nim_binary

   Note: --debug:memleak adds significant overhead and must never be used in production.

Applying the Fixes

1. Breaking Reference Cycles

If two ref objects point to each other, neither will ever reach a reference count of zero. Use the {.weak.} pragma for the "back-reference" to prevent the cycle.

type
  Parent = ref object
    child: Child
  Child = ref object
    parent: {.weak.} Parent # Prevents the cycle

2. Correcting Ownership Annotations

Use sink when a function takes ownership of an object and lent when it only needs to read it. A common leak occurs when a sink parameter is not passed to another sink or destroyed, leaving the object in limbo.

proc processData(data: sink MyObject) = 
  # If we don't pass 'data' to another sink or let it go out of scope,
  # ARC handles the cleanup. But if we store it in a global without 
  # proper management, it may leak.
  echo data.name

3. Managing C-Interop

Pointers allocated in C are invisible to Nim's ARC/ORC. If you wrap C pointers in Nim objects, you must manually implement the destroy hook or use GC_ref/GC_unref to ensure the C memory is freed when the Nim wrapper is collected.

Verification and Limits

To verify the fix, monitor the cycle collection statistics in ORC. You can call GC_getStatistics().cyclesCollected at the end of a heavy workload. If this number is extremely high, your application is relying too heavily on the cycle collector rather than deterministic ARC, which will impact p99 latency.

Practical Check: Run your binary under Valgrind again. The goal is "zero definitely lost bytes." If RSS still exceeds 2x the expected baseline after fixing cycles and annotations, the leak may be within a linked C library.

Escalation Criteria

If the following conditions persist after applying the above fixes, create a minimal reproducible example (MRE) for the Nim issue tracker:

• RSS continues to grow linearly despite zero "definitely lost" bytes in Valgrind.
• p99 pause times exceed 50ms specifically during ORC cycle collection phases.
• The leak only occurs when using specific --mm:orc optimization levels.