Crate light_qsbr

Crate light_qsbr 

Source
Expand description

§light-qsbr

light-qsbr provides a lightweight Quiescent-State-Based Reclamation (QSBR) mechanism for asynchronous runtimes and lock-free data structures.

It is designed as a minimal alternative to heavy garbage collectors and allows safe memory reclamation in concurrent environments, where objects can only be freed once all participating threads have advanced past a known epoch.

§Core Concepts

  • SharedManager is the global manager. It tracks the current global epoch and the number of executors participating in each epoch.

  • LocalManager is the thread-local manager. Each executor (thread or runtime worker) has its own local manager, which schedules memory to be deallocated or dropped when it is safe.

  • Epochs are global counters. Memory is only reclaimed once all executors have passed the epoch in which the memory was retired.

§Workflow

  1. Create a SharedManager.
  2. For each executor (thread/worker), call SharedManager::register_new_executor. This installs a thread-local LocalManager.
  3. Executors schedule memory for deallocation or dropping via LocalManager::schedule_deallocate, LocalManager::schedule_deallocate_slice, or LocalManager::schedule_drop.
  4. Periodically, executors call LocalManager::maybe_pass_epoch to attempt to advance the epoch and trigger safe reclamation.
  5. When shutting down, executors must call unsafe { LocalManager::deregister() } to deregister themselves.

§Example

use std::cell::Cell;
use light_qsbr::{SharedManager, local_manager, LocalManager};
use light_qsbr::orengine_utils::instant::OrengineInstant;

let shared = SharedManager::new();

// Register an executor for this thread
shared.register_new_executor();

// Schedule deallocation or dropping through the local manager
let value = Box::new(42);
let ptr = Box::into_raw(value);
unsafe {
    local_manager().schedule_deallocate(ptr);
}

// Periodically try to advance the epoch (e.g., in an event loop)
local_manager().maybe_pass_epoch(OrengineInstant::now());

// Deregister before thread exit
unsafe { LocalManager::deregister() };

§Safety Guarantees

  • Objects scheduled for reclamation will only be freed once all executors have passed the epoch in which they were retired.
  • The API is intentionally minimal: the runtime must periodically call LocalManager::maybe_pass_epoch to make progress.

§When to Use

  • Implementing lock-free collections that need safe memory reclamation.
  • Async runtimes that want QSBR without the overhead of hazard pointers or full garbage collection.
  • Situations where you control executor lifecycle and can ensure correct registration/deregistration.

§When Not to Use

  • If you need automatic reclamation without explicit epoch-passing.
  • If your workload is highly dynamic with frequent thread churn—QSBR works best with stable executor sets.

§See Also

Re-exports§

pub use orengine_utils;

Structs§

LocalManager
A local manager of objects that need to be deallocated or dropped when it is safe.
SharedManager
A shared manager that coordinates memory reclamation across executors.

Functions§

local_manager
Returns a reference to the thread-local LocalManager.