Skip to content

Getting Started

This guide walks through setting up and using nim-debra in your lock-free data structures.

Installation

Add nim-debra to your .nimble file:

requires "debra >= 0.1.0"

Or install globally:

nimble install debra

Basic Usage

The following example demonstrates the complete DEBRA+ lifecycle:

  1. Initialize the manager
  2. Register the thread
  3. Pin/unpin critical sections
  4. Retire objects for later reclamation
  5. Periodically reclaim memory
# examples/basic_usage.nim
## Basic DEBRA+ usage: initialize manager, register thread, pin/unpin, retire, reclaim.

import debra
import std/atomics

# Node type using ref object pattern for self-reference
type
  NodeObj = object
    value: int
    next: Atomic[Managed[ref NodeObj]]
  Node = ref NodeObj

# Helper to perform one pin/unpin cycle with retirement
proc doCycle(handle: ThreadHandle[4], manager: var DebraManager[4], value: int) =
  # Enter critical section
  let u = unpinned(handle)
  let pinned = u.pin()

  # Create a managed node (GC won't collect until retired)
  let node = managed Node(value: value)

  # Retire the node for later reclamation
  let ready = retireReady(pinned)
  discard ready.retire(node)

  # Exit critical section
  let unpinResult = pinned.unpin()

  # Handle neutralization if it occurred
  case unpinResult.kind:
  of uUnpinned:
    discard
  of uNeutralized:
    discard unpinResult.neutralized.acknowledge()

proc main() =
  # 1. Initialize manager (supports up to 4 threads)
  var manager = initDebraManager[4](../../examples)
  setGlobalManager(addr manager)

  # 2. Register this thread
  let handle = registerThread(manager)

  # 3. Simulate some operations
  for i in 0..<10:
    doCycle(handle, manager, i)

    # Advance epoch periodically
    if i mod 3 == 0:
      manager.advance()

  # 4. Attempt reclamation
  let reclaimResult = reclaimStart(addr manager)
    .loadEpochs()
    .checkSafe()

  case reclaimResult.kind:
  of rReclaimReady:
    let count = reclaimResult.reclaimready.tryReclaim()
    echo "Reclaimed ", count, " objects"
  of rReclaimBlocked:
    echo "Reclamation blocked (normal at startup)"

  echo "Basic usage example completed successfully"

when isMainModule:
  main()

View full source

Key Concepts

  • Manager: Coordinates epoch-based reclamation across threads
  • Handle: Per-thread registration for DEBRA operations
  • Pin/Unpin: Mark critical sections where shared data is accessed
  • Managed[T]: Wrapper type that prevents GC from collecting objects until retired
  • Retire: Mark removed objects for later safe reclamation
  • Reclaim: Free objects when all threads have advanced past their epoch

Next Steps