API Reference¶
Auto-generated API documentation from source code.
Main Module¶
nim-debra: DEBRA+ Safe Memory Reclamation
This library provides typestate-enforced epoch-based reclamation with signal-based neutralization for lock-free data structures.
registerThread raises ¶
proc registerThread(manager: var DebraManager[MaxThreads]): ThreadHandle[MaxThreads]Register current thread with the DEBRA manager.
Must be called once per thread before any epoch operations. Raises DebraRegistrationError if max threads already registered.
Parameters
-
manager(var DebraManager[MaxThreads])
Returns
ThreadHandle[MaxThreads]
Raises
DebraRegistrationError
neutralizeStalled ¶
proc neutralizeStalled(manager: var DebraManager[MaxThreads]; epochsBeforeNeutralize: uint64 = 2): intSignal all stalled threads. Returns number of signals sent.
Parameters
-
manager(var DebraManager[MaxThreads]) -
epochsBeforeNeutralize(uint64)
Returns
int
advance inline ¶
proc advance(manager: var DebraManager[MaxThreads])Advance the global epoch.
Parameters
-
manager(var DebraManager[MaxThreads])
currentEpoch inline ¶
proc currentEpoch(manager: var DebraManager[MaxThreads]): uint64Get current global epoch.
Parameters
-
manager(var DebraManager[MaxThreads])
Returns
uint64
Core Types¶
Type definitions for DEBRA+ manager and thread state.
Core types for DEBRA+ implementation.
initDebraManager ¶
proc initDebraManager(): DebraManager[MaxThreads]Initialize a new DEBRA+ manager.
The global epoch starts at 1 (not 0) so that epoch 0 can represent "never observed" in thread state.
Returns
DebraManager[MaxThreads]
Constants¶
Configuration constants for DEBRA+ algorithm.
Constants for DEBRA+ implementation.
const DefaultMaxThreadsDefault maximum number of threads that can be registered.
const CacheLineBytesCache line size for alignment to prevent false sharing.
Limbo Bags¶
Data structures for thread-local retire queues.
Limbo bag data structures for DEBRA+ retire queues.
A limbo bag holds up to 64 retired objects. Bags are linked together forming a thread-local retire queue.
allocLimboBag ¶
proc allocLimboBag(): ptr LimboBagfreeLimboBag ¶
proc freeLimboBag(bag: ptr LimboBag)Free a limbo bag (does NOT call destructors).
Parameters
-
bag(ptr LimboBag)
reclaimBag ¶
proc reclaimBag(bag: ptr LimboBag)Call destructors for all objects in bag, then free bag.
Parameters
-
bag(ptr LimboBag)
unreffer ¶
proc unreffer(): DestructorGenerate a destructor that calls GC_unref for type T.
Used internally by retire() to create type-specific destructors for Managed[T] objects.
Returns
Destructor
Signal Handling¶
POSIX signal handling for neutralization protocol.
Signal handler for DEBRA+ thread neutralization.
When a thread is stalled (hasn't advanced its epoch), other threads can send SIGUSR1 to force it to unpin, allowing reclamation to proceed.
installSignalHandler ¶
proc installSignalHandler()Install SIGUSR1 handler for DEBRA+ neutralization.
Safe to call multiple times - subsequent calls are no-ops. Called automatically during first DebraManager initialization.
isSignalHandlerInstalled ¶
proc isSignalHandlerInstalled(): boolsetGlobalManager ¶
proc setGlobalManager(manager: pointer)Set the global manager pointer for signal handler.
Must be called once after manager initialization.
Parameters
-
manager(pointer)
Typestates¶
Signal Handler¶
Signal handler installation lifecycle.
SignalHandler typestate.
Ensures signal handler is installed before DEBRA operations.
initSignalHandler ¶
proc initSignalHandler(): HandlerUninstalledCreate uninstalled signal handler context.
Returns
HandlerUninstalled
install transition ¶
proc install(h: HandlerUninstalled): HandlerInstalledInstall SIGUSR1 handler for DEBRA+ neutralization.
Parameters
-
h(HandlerUninstalled)
Returns
HandlerInstalled
isInstalled ¶
func isInstalled(h: HandlerInstalled): boolCheck if handler is installed.
Parameters
-
h(HandlerInstalled)
Returns
bool
Manager¶
Manager initialization and shutdown lifecycle.
DebraManager lifecycle typestate.
Ensures manager is initialized before use and properly shut down.
uninitializedManager ¶
proc uninitializedManager(mgr: ptr DebraManager[MaxThreads]): ManagerUninitialized[MaxThreads]Wrap a manager pointer as uninitialized.
Parameters
-
mgr(ptr DebraManager[MaxThreads])
Returns
ManagerUninitialized[MaxThreads]
initialize transition ¶
proc initialize(m: sink ManagerUninitialized[MaxThreads]): ManagerReady[MaxThreads]Initialize the manager. Sets epoch to 1, clears all state.
Parameters
-
m(sink ManagerUninitialized[MaxThreads])
Returns
ManagerReady[MaxThreads]
shutdown transition ¶
proc shutdown(m: sink ManagerReady[MaxThreads]): ManagerShutdown[MaxThreads]Shutdown manager. Reclaims all remaining limbo bags.
Parameters
-
m(sink ManagerReady[MaxThreads])
Returns
ManagerShutdown[MaxThreads]
getManager ¶
func getManager(m: ManagerReady[MaxThreads]): ptr DebraManager[MaxThreads]Get the underlying manager pointer.
Parameters
-
m(ManagerReady[MaxThreads])
Returns
ptr DebraManager[MaxThreads]
Registration¶
Thread registration lifecycle.
Registration typestate for thread registration.
Handles thread registration with the DEBRA manager, ensuring threads properly claim slots in the thread array using lock-free CAS operations.
unregistered ¶
proc unregistered(mgr: ptr DebraManager[MaxThreads]): Unregistered[MaxThreads]Create unregistered context for a thread.
Parameters
-
mgr(ptr DebraManager[MaxThreads])
Returns
Unregistered[MaxThreads]
register transition ¶
proc register(u: sink Unregistered[MaxThreads]): RegisterResult[MaxThreads]Try to register thread by claiming a slot. Returns Registered if successful, RegistrationFull if all slots are taken.
Parameters
-
u(sink Unregistered[MaxThreads])
Returns
RegisterResult[MaxThreads]
idx ¶
func idx(r: Registered[MaxThreads]): intGet the thread slot index.
Parameters
-
r(Registered[MaxThreads])
Returns
int
getHandle ¶
func getHandle(r: Registered[MaxThreads]): ThreadHandle[MaxThreads]Extract ThreadHandle for use in pin/unpin operations.
Parameters
-
r(Registered[MaxThreads])
Returns
ThreadHandle[MaxThreads]
Thread Slot¶
Thread slot allocation and release.
ThreadSlot typestate for thread slot lifecycle.
Tracks the lifecycle of a thread slot in the DEBRA manager: - Free: Slot is available for claiming - Claiming: Thread is attempting to claim the slot - Active: Slot is actively in use by a thread - Draining: Thread is unregistering, draining limbo bags - Free: Slot released back to pool
freeSlot ¶
proc freeSlot(idx: int; mgr: ptr DebraManager[MaxThreads]): Free[MaxThreads]Create a free slot context.
Parameters
-
idx(int) -
mgr(ptr DebraManager[MaxThreads])
Returns
Free[MaxThreads]
claim transition ¶
proc claim(f: sink Free[MaxThreads]): Claiming[MaxThreads]Begin claiming this slot. Transition to Claiming state.
Parameters
-
f(sink Free[MaxThreads])
Returns
Claiming[MaxThreads]
activate transition ¶
proc activate(c: sink Claiming[MaxThreads]): Active[MaxThreads]Complete slot claim. Transition to Active state. This is where the slot becomes fully owned by a thread.
Parameters
-
c(sink Claiming[MaxThreads])
Returns
Active[MaxThreads]
drain transition ¶
proc drain(a: sink Active[MaxThreads]): Draining[MaxThreads]Begin unregistration. Transition to Draining state. Thread will drain its limbo bags before releasing the slot.
Parameters
-
a(sink Active[MaxThreads])
Returns
Draining[MaxThreads]
release transition ¶
proc release(d: sink Draining[MaxThreads]): Free[MaxThreads]Release slot back to free pool. Transition back to Free state. This completes the lifecycle, making the slot available for reuse.
Parameters
-
d(sink Draining[MaxThreads])
Returns
Free[MaxThreads]
idx ¶
func idx(s: Active[MaxThreads]): intGet the slot index from Active state.
Parameters
-
s(Active[MaxThreads])
Returns
int
idx ¶
func idx(s: Draining[MaxThreads]): intGet the slot index from Draining state.
Parameters
-
s(Draining[MaxThreads])
Returns
int
manager ¶
func manager(s: Active[MaxThreads]): ptr DebraManager[MaxThreads]Get the manager pointer from Active state.
Parameters
-
s(Active[MaxThreads])
Returns
ptr DebraManager[MaxThreads]
manager ¶
func manager(s: Draining[MaxThreads]): ptr DebraManager[MaxThreads]Get the manager pointer from Draining state.
Parameters
-
s(Draining[MaxThreads])
Returns
ptr DebraManager[MaxThreads]
Epoch Guard¶
Pin/unpin critical section lifecycle.
EpochGuard typestate for pin/unpin lifecycle.
Ensures threads properly enter/exit critical sections.
unpinned ¶
proc unpinned(handle: ThreadHandle[MaxThreads]): Unpinned[MaxThreads]Create unpinned epoch guard context.
Parameters
-
handle(ThreadHandle[MaxThreads])
Returns
Unpinned[MaxThreads]
pin transition ¶
proc pin(u: sink Unpinned[MaxThreads]): Pinned[MaxThreads]Enter critical section. Blocks reclamation of current epoch.
Parameters
-
u(sink Unpinned[MaxThreads])
Returns
Pinned[MaxThreads]
unpin transition ¶
proc unpin(p: sink Pinned[MaxThreads]): UnpinResult[MaxThreads]Leave critical section. Returns Neutralized if signaled.
Parameters
-
p(sink Pinned[MaxThreads])
Returns
UnpinResult[MaxThreads]
acknowledge transition ¶
proc acknowledge(n: sink Neutralized[MaxThreads]): Unpinned[MaxThreads]Acknowledge neutralization. Required before re-pinning.
Parameters
-
n(sink Neutralized[MaxThreads])
Returns
Unpinned[MaxThreads]
epoch ¶
func epoch(p: Pinned[MaxThreads]): uint64Get the epoch this thread is pinned at.
Parameters
-
p(Pinned[MaxThreads])
Returns
uint64
handle ¶
func handle(p: Pinned[MaxThreads]): ThreadHandle[MaxThreads]Get the thread handle.
Parameters
-
p(Pinned[MaxThreads])
Returns
ThreadHandle[MaxThreads]
Retire¶
Object retirement to limbo bags.
Retire typestate for adding objects to limbo bags.
Must be pinned to retire objects.
retireReady ¶
proc retireReady(p: Pinned[MaxThreads]): RetireReady[MaxThreads]Create retire context from pinned state.
Parameters
-
p(Pinned[MaxThreads])
Returns
RetireReady[MaxThreads]
retireReadyFromRetired ¶
proc retireReadyFromRetired(r: sink Retired[MaxThreads]): RetireReady[MaxThreads]Get back to RetireReady after retiring (for multiple retires).
Parameters
-
r(sink Retired[MaxThreads])
Returns
RetireReady[MaxThreads]
retire transition ¶
proc retire(r: sink RetireReady[MaxThreads]; obj: Managed[T]): Retired[MaxThreads]Retire a managed object for epoch-based reclamation.
The object will be freed (via GC_unref) when its epoch becomes safe for reclamation.
Parameters
-
r(sink RetireReady[MaxThreads]) -
obj(Managed[T])
Returns
Retired[MaxThreads]
handle ¶
func handle(r: RetireReady[MaxThreads]): ThreadHandle[MaxThreads]Parameters
-
r(RetireReady[MaxThreads])
Returns
ThreadHandle[MaxThreads]
Reclamation¶
Safe memory reclamation from limbo bags.
Reclaim typestate for safe memory reclamation.
Walks limbo bags and reclaims objects retired before safeEpoch.
reclaimStart ¶
proc reclaimStart(mgr: ptr DebraManager[MaxThreads]): ReclaimStart[MaxThreads]Begin reclamation attempt.
Parameters
-
mgr(ptr DebraManager[MaxThreads])
Returns
ReclaimStart[MaxThreads]
loadEpochs transition ¶
proc loadEpochs(s: ReclaimStart[MaxThreads]): EpochsLoaded[MaxThreads]Load global epoch and compute minimum epoch across pinned threads.
Parameters
-
s(ReclaimStart[MaxThreads])
Returns
EpochsLoaded[MaxThreads]
safeEpoch ¶
func safeEpoch(e: EpochsLoaded[MaxThreads]): uint64checkSafe transition ¶
proc checkSafe(e: EpochsLoaded[MaxThreads]): ReclaimCheck[MaxThreads]Check if any epochs are safe to reclaim.
Parameters
-
e(EpochsLoaded[MaxThreads])
Returns
ReclaimCheck[MaxThreads]
tryReclaim notATransition ¶
proc tryReclaim(r: ReclaimReady[MaxThreads]): intReclaim all eligible objects from all threads' limbo bags. Returns count of objects reclaimed.
Parameters
-
r(ReclaimReady[MaxThreads])
Returns
int
Neutralization¶
Thread neutralization protocol.
Neutralize typestate for DEBRA+ neutralization signaling.
Ensures proper sequence: ScanStart -> Scanning -> ScanComplete
When the epoch needs to advance, scan all threads and send SIGUSR1 to pinned threads that are stalled (behind globalEpoch by threshold).
scanStart ¶
proc scanStart(mgr: ptr DebraManager[MaxThreads]): ScanStart[MaxThreads]Begin neutralization scan.
Parameters
-
mgr(ptr DebraManager[MaxThreads])
Returns
ScanStart[MaxThreads]
loadEpoch transition ¶
proc loadEpoch(s: ScanStart[MaxThreads]; epochsBeforeNeutralize: uint64 = 2): Scanning[MaxThreads]Load global epoch and compute threshold for stalled threads. Threads with epoch < (globalEpoch - epochsBeforeNeutralize) get signaled.
Parameters
-
s(ScanStart[MaxThreads]) -
epochsBeforeNeutralize(uint64)
Returns
Scanning[MaxThreads]
globalEpoch ¶
func globalEpoch(s: Scanning[MaxThreads]): uint64Get the global epoch loaded during scan start.
Parameters
-
s(Scanning[MaxThreads])
Returns
uint64
threshold ¶
func threshold(s: Scanning[MaxThreads]): uint64Get the epoch threshold for neutralization.
Parameters
-
s(Scanning[MaxThreads])
Returns
uint64
scanAndSignal transition ¶
proc scanAndSignal(s: Scanning[MaxThreads]): ScanComplete[MaxThreads]Scan all registered threads and send SIGUSR1 to stalled pinned threads. Returns count of signals sent.
Parameters
-
s(Scanning[MaxThreads])
Returns
ScanComplete[MaxThreads]
signalsSent ¶
func signalsSent(c: ScanComplete[MaxThreads]): intGet number of signals sent during scan.
Parameters
-
c(ScanComplete[MaxThreads])
Returns
int
extractSignalCount ¶
func extractSignalCount(c: ScanComplete[MaxThreads]): intExtract the count of signals sent. Terminal operation.
Parameters
-
c(ScanComplete[MaxThreads])
Returns
int
Epoch Advance¶
Global epoch advancement.
EpochAdvance typestate for advancing the global epoch.
Ensures atomic increment of the global epoch counter.
advanceCurrent ¶
proc advanceCurrent(mgr: ptr DebraManager[MaxThreads]): Current[MaxThreads]Create epoch advance context.
Parameters
-
mgr(ptr DebraManager[MaxThreads])
Returns
Current[MaxThreads]
advance transition ¶
proc advance(c: sink Current[MaxThreads]): Advancing[MaxThreads]Begin advancing the global epoch.
Parameters
-
c(sink Current[MaxThreads])
Returns
Advancing[MaxThreads]
complete transition ¶
proc complete(a: sink Advancing[MaxThreads]): Advanced[MaxThreads]Complete epoch advance by atomically incrementing globalEpoch.
Parameters
-
a(sink Advancing[MaxThreads])
Returns
Advanced[MaxThreads]
newEpoch ¶
func newEpoch(a: Advanced[MaxThreads]): uint64Get the new epoch value after advancement.
Parameters
-
a(Advanced[MaxThreads])
Returns
uint64
oldEpoch ¶
func oldEpoch(a: Advanced[MaxThreads]): uint64Get the old epoch value before advancement.
Parameters
-
a(Advanced[MaxThreads])
Returns
uint64