Nim Memory Management

What this skill does

# Nim Memory Management

## Introduction

Nim provides flexible memory management combining automatic garbage collection
with manual control options. This hybrid approach enables safe high-level programming
while allowing low-level optimization for performance-critical code. Understanding
memory management is crucial for systems programming and embedded applications.

Nim supports multiple garbage collectors (GC), move semantics for efficiency,
destructors for resource cleanup, and manual memory management through pointers.
The compiler's static analysis prevents many memory errors at compile time,
while runtime checks catch others during development.

This skill covers garbage collection strategies, ref vs ptr types, move semantics,
destructors and hooks, manual memory management, memory safety patterns, and
optimization techniques for minimal allocations and predictable performance.

## Garbage Collection Strategies

Nim offers multiple GC implementations with different trade-offs for throughput,
latency, and memory usage.

```nim
# Default GC (--gc:refc)
# Reference counting with cycle detection
type Node = ref object
  value: int
  next: Node

var head = Node(value: 1)
head.next = Node(value: 2)
head.next.next = Node(value: 3)

# Arc GC (--gc:arc)
# Automatic reference counting without cycle detection
# Fastest but requires breaking cycles manually
{.experimental: "strictFuncs".}

proc processData() =
  var data = @[1, 2, 3, 4, 5]  # Heap allocated
  # Automatically freed when out of scope
  echo data

# ORC GC (--gc:orc)
# Arc with cycle collection
proc createCycle() =
  type
    Node = ref object
      next: Node

  var a = Node()
  var b = Node()
  a.next = b
  b.next = a  # Cycle collected by ORC

# Manual GC control
proc lowLatencyOperation() =
  GC_disable()  # Disable GC during critical section
  # Time-sensitive code here
  GC_enable()

# GC statistics
proc checkMemory() =
  echo "GC Memory: ", getOccupiedMem()
  echo "GC Total: ", getTotalMem()
  echo "GC Free: ", getFreeMem()

# Forcing collection
proc cleanupMemory() =
  GC_fullCollect()  # Force full collection

# GC hints
proc allocateLarge() =
  var data: ref array[1000000, int]
  new(data)
  GC_ref(data)  # Add external reference
  # Use data
  GC_unref(data)  # Remove reference

# Region-based allocation
proc useRegion() =
  var region: MemRegion
  region = newMemRegion()
  # Allocations in region
  freeMemRegion(region)

# Stack allocation for value types
proc stackAlloc() =
  var data: array[1000, int]  # Stack allocated
  # Automatically freed on scope exit

# Compile-time GC selection
when defined(gcArc):
  echo "Using Arc GC"
elif defined(gcOrc):
  echo "Using ORC GC"
else:
  echo "Using default GC"

# GC-safe operations
{.push gcsafe.}
proc threadSafeProc() =
  echo "No global GC state accessed"
{.pop.}
```

Choose GC strategy based on application needs: Arc for speed, ORC for safety,
refc for compatibility.

## Ref and Ptr Types

Ref types use garbage collection while ptr types require manual memory management.

```nim
# Ref types (GC-managed)
type
  Person = ref object
    name: string
    age: int

proc createPerson(): Person =
  Person(name: "Alice", age: 30)

var p = createPerson()
# Automatically freed by GC

# Ptr types (manual management)
type
  Buffer = ptr object
    data: array[1024, byte]
    size: int

proc createBuffer(): Buffer =
  cast[Buffer](alloc0(sizeof(Buffer)))

proc destroyBuffer(buf: Buffer) =
  dealloc(buf)

# Using ptr types
proc useBuffer() =
  var buf = createBuffer()
  # Use buffer
  destroyBuffer(buf)

# Ref vs ptr performance
proc refExample() =
  var items: seq[ref int]
  for i in 0..<1000:
    var x: ref int
    new(x)
    x[] = i
    items.add(x)

proc ptrExample() =
  var items: seq[ptr int]
  for i in 0..<1000:
    var x = cast[ptr int](alloc(sizeof(int)))
    x[] = i
    items.add(x)

  # Manual cleanup required
  for item in items:
    dealloc(item)

# Shared pointers
type SharedPtr[T] = ref object
  data: T
  refCount: int

proc newShared[T](value: T): SharedPtr[T] =
  SharedPtr[T](data: value, refCount: 1)

# Weak references
type
  WeakRef[T] = object
    target: ptr T

proc newWeakRef[T](target: ref T): WeakRef[T] =
  WeakRef[T](target: cast[ptr T](target))

# Pointer arithmetic
proc ptrArithmetic() =
  var arr = [1, 2, 3, 4, 5]
  var p = addr arr[0]
  p = cast[ptr int](cast[int](p) + sizeof(int))
  echo p[]  # 2

# Safe pointer usage
proc safePtrUsage() =
  var x = 42
  var p = addr x  # Stack address
  echo p[]  # Safe while x in scope
  # p becomes invalid after scope

# Pointer aliasing
proc aliasing() =
  var x = 10
  var p1 = addr x
  var p2 = addr x
  p1[] = 20
  echo p2[]  # 20
```

Use ref for automatic memory management, ptr for manual control and C interop.

## Move Semantics and Ownership

Move semantics transfer ownership without copying, improving performance for
large data structures.

```nim
# Move vs copy
proc moveExample() =
  var s1 = @[1, 2, 3, 4, 5]
  var s2 = s1  # Copy by default

  var s3 = @[10, 20, 30]
  var s4 = move(s3)  # Move ownership
  # s3 is now empty

# Sink parameters (consume ownership)
proc consume(s: sink seq[int]) =
  echo s.len
  # s automatically moved

proc producer(): seq[int] =
  result = @[1, 2, 3]
  # result moved to caller

# Lent parameters (borrow)
proc borrow(s: lent seq[int]) =
  echo s.len
  # s cannot be modified or moved

# Move in containers
proc containerMoves() =
  var items: seq[string]
  var s = "large string" & "x".repeat(1000)
  items.add(move(s))  # Moved, not copied

# Move assignment
proc moveAssignment() =
  var s1 = @[1, 2, 3]
  var s2: seq[int]
  s2 = move(s1)  # s1 becomes empty

# Destructive move
proc destructiveMove[T](src: var T): T =
  result = move(src)
  reset(src)

# Move optimization
proc optimizedMove() =
  var data = newSeq[int](1000000)
  # Fill data
  var result = move(data)  # O(1) instead of O(n)
  return result

# Move with destructors
type
  Resource = object
    handle: int

proc `=destroy`(r: var Resource) =
  if r.handle != 0:
    echo "Closing resource: ", r.handle
    r.handle = 0

proc `=copy`(dest: var Resource, src: Resource) =
  dest.handle = src.handle

proc `=sink`(dest: var Resource, src: Resource) =
  dest.handle = src.handle

# Using move semantics
proc useMove() =
  var r1 = Resource(handle: 42)
  var r2 = move(r1)  # Moved, r1.handle = 0
  # r2 destroyed on scope exit
```

Move semantics eliminate unnecessary copies for significant performance gains.

## Destructors and Hooks

Destructors provide deterministic cleanup while hooks customize copy and move
behavior.

```nim
# Basic destructor
type
  File = object
    path: string
    handle: int

proc `=destroy`(f: var File) =
  if f.handle != 0:
    echo "Closing file: ", f.path
    # Close file handle
    f.handle = 0

# Copy hook
proc `=copy`(dest: var File, src: File) =
  dest.path = src.path
  # Duplicate file handle
  dest.handle = src.handle

# Sink/Move hook
proc `=sink`(dest: var File, src: File) =
  if dest.handle != 0:
    echo "Cleaning up dest"
  dest.path = src.path
  dest.handle = src.handle

# RAII pattern
proc useFile() =
  var f = File(path: "data.txt", handle: 123)
  # Use file
  # Automatically closed on scope exit

# Scope guards
template defer(cleanup: untyped): untyped =
  try:
    body
  finally:
    cleanup

proc scopedResource() =
  var resource = acquireResource()
  defer:
    releaseResource(resource)
  # Use resource
  # Cleaned up even if exception

# Custom allocator with destructor
type
  Pool = object
    buffer: ptr UncheckedArray[byte]
    size: int
    used: int

proc `=destroy`(p: var Pool) =
  if p.buffer != nil:
    dealloc(p.buffer)
    p.buffer = nil

proc newPool(size: int): Pool =
  result.size = size
  result.buffer = cast[ptr UncheckedArray[byte]](alloc(size))
  result.used = 0

# Reference counting with destructor
type
  Counted = ref object
    value: int
    count: int

proc `=destroy`(c: var Counted) =
  dec c.count
  if c.count == 0: