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.3.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

Example source not mirrored

The examples/basic_usage.nim source was part of the standalone nim-debra repo and is not included in this frozen mirror. View it at the upstream link below, or see the live SMR guide for the current lockfree/smr/nebr API.

:material-file-code: 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
  • retain[T]: GC-pin a ref T and return a raw ptr T suitable for atomic storage (debra/refptr)
  • releaseDestructor[T](): Return a captureless Destructor function pointer that pairs the retain at reclamation time
  • Retire: Mark a removed pointer (and its destructor) for later safe reclamation
  • Reclaim: Run pending destructors once all threads have advanced past the retiring epoch

Next Steps