kcenon::container::epoch_manager Class Reference

Epoch-based memory reclamation for lock-free data structures. More...

#include <epoch_manager.h>

Collaboration diagram for kcenon::container::epoch_manager:

Public Member Functions
void	enter_critical () noexcept
	Enter critical section (pin to current epoch)
void	exit_critical () noexcept
	Exit critical section.
bool	in_critical_section () const noexcept
	Check if current thread is in critical section.
void	defer_delete (void *ptr, std::function< void(void *)> deleter)
	Defer deletion of a pointer.
template<typename T >
void	defer_delete (T *ptr)
	Defer deletion of a typed pointer.
size_t	try_gc ()
	Attempt garbage collection.
size_t	force_gc ()
	Force garbage collection of all epochs.
uint64_t	current_epoch () const noexcept
	Get the current global epoch.
size_t	gc_count () const noexcept
	Get the number of GC cycles performed.
size_t	reclaimed_count () const noexcept
	Get the total number of objects reclaimed.
size_t	pending_count () const
	Get the number of objects pending deletion.
	epoch_manager (const epoch_manager &)=delete
epoch_manager &	operator= (const epoch_manager &)=delete
	epoch_manager (epoch_manager &&)=delete
epoch_manager &	operator= (epoch_manager &&)=delete

Static Public Member Functions
static epoch_manager &	instance ()
	Get the singleton instance.

Static Public Attributes
static constexpr uint64_t	INACTIVE = UINT64_MAX
	Sentinel value indicating thread is not in critical section.
static constexpr size_t	NUM_EPOCHS = 3
	Number of epochs in rotation (must be at least 3 for safety)

Private Member Functions
	epoch_manager ()=default
	Private constructor for singleton.
	~epoch_manager ()
	Destructor - clean up any remaining deferred deletions.

Static Private Member Functions
static std::atomic< uint64_t > &	thread_epoch ()
	Get thread-local epoch reference.

Private Attributes
std::atomic< uint64_t >	global_epoch_ {0}
std::atomic< size_t >	gc_count_ {0}
std::atomic< size_t >	reclaimed_count_ {0}
std::array< std::mutex, NUM_EPOCHS >	retire_mutex_
std::array< std::vector< std::pair< void *, std::function< void(void *)> > >, NUM_EPOCHS >	retired_

Detailed Description

Epoch-based memory reclamation for lock-free data structures.

This class implements the epoch-based reclamation (EBR) algorithm for safe memory deallocation in lock-free data structures. It uses a three-epoch system where memory is deferred until all readers from two epochs ago have completed.

The algorithm:

1. Threads enter a critical section by pinning to the current epoch
2. Writers defer deletions to the current epoch's retire list
3. When all threads have left an epoch, its retired memory can be reclaimed

Properties:

• enter_critical/exit_critical: Lock-free
• defer_delete: Lock-free (uses mutex only for list append)
• try_gc: May reclaim memory when safe

epoch_manager& em = epoch_manager::instance();
 
// Reader thread
em.enter_critical();
// ... read from lock-free structure ...
em.exit_critical();
 
// Writer thread
em.defer_delete(old_node, [](void* p) { delete static_cast<Node*>(p); });
em.try_gc();

Definition at line 46 of file epoch_manager.h.

Constructor & Destructor Documentation

epoch_manager() [1/3]

kcenon::container::epoch_manager::epoch_manager ( const epoch_manager & )

delete

epoch_manager() [2/3]

kcenon::container::epoch_manager::epoch_manager ( epoch_manager && )

delete

epoch_manager() [3/3]

kcenon::container::epoch_manager::epoch_manager ( )

privatedefault

Private constructor for singleton.

~epoch_manager()

kcenon::container::epoch_manager::~epoch_manager ( )

inlineprivate

Destructor - clean up any remaining deferred deletions.

Definition at line 264 of file epoch_manager.h.

                         {
            force_gc();
        }

References force_gc().

Here is the call graph for this function:

Member Function Documentation

current_epoch()

uint64_t kcenon::container::epoch_manager::current_epoch ( ) const

inlinenodiscardnoexcept

Get the current global epoch.

Returns

Current epoch number

Definition at line 216 of file epoch_manager.h.

                                                              {
            return global_epoch_.load(std::memory_order_relaxed);
        }

References global_epoch_.

defer_delete() [1/2]

template<typename T >

void kcenon::container::epoch_manager::defer_delete ( T * ptr )

inline

Defer deletion of a typed pointer.

Convenience overload that automatically creates the deleter.

Template Parameters

T	Type of the pointer

Parameters

ptr	Pointer to defer deletion for

Definition at line 131 of file epoch_manager.h.

                                  {
            defer_delete(static_cast<void*>(ptr), [](void* p) {
                delete static_cast<T*>(p);
            });
        }

References defer_delete().

Here is the call graph for this function:

defer_delete() [2/2]

void kcenon::container::epoch_manager::defer_delete ( void * ptr, std::function< void(void *)> deleter )

inline

Defer deletion of a pointer.

The deleter will be called when it's safe to reclaim the memory (when all readers from the current epoch have exited).

Parameters

ptr	Pointer to defer deletion for
deleter	Function to call to delete the pointer

Thread safety: Uses mutex for list append

Definition at line 110 of file epoch_manager.h.

                                                                       {
            if (ptr == nullptr) {
                return;
            }
 
            uint64_t epoch = global_epoch_.load(std::memory_order_relaxed);
            size_t bucket = epoch % NUM_EPOCHS;
 
            std::lock_guard<std::mutex> lock(retire_mutex_[bucket]);
            retired_[bucket].emplace_back(ptr, std::move(deleter));
        }

References global_epoch_, NUM_EPOCHS, retire_mutex_, and retired_.

Referenced by defer_delete().

Here is the caller graph for this function:

enter_critical()

void kcenon::container::epoch_manager::enter_critical ( )

inlinenoexcept

Enter critical section (pin to current epoch)

Must be called before accessing any lock-free data structure. Must be paired with exit_critical().

Thread safety: Lock-free

Definition at line 76 of file epoch_manager.h.

                                       {
            thread_epoch() = global_epoch_.load(std::memory_order_acquire);
        }

References global_epoch_, and thread_epoch().

Referenced by kcenon::container::epoch_guard::epoch_guard().

Here is the call graph for this function:

Here is the caller graph for this function:

exit_critical()

void kcenon::container::epoch_manager::exit_critical ( )

inlinenoexcept

Exit critical section.

Must be called after finishing access to lock-free data structures.

Thread safety: Lock-free

Definition at line 87 of file epoch_manager.h.

                                      {
            thread_epoch() = INACTIVE;
        }

References INACTIVE, and thread_epoch().

Referenced by kcenon::container::epoch_guard::~epoch_guard().

Here is the call graph for this function:

Here is the caller graph for this function:

force_gc()

size_t kcenon::container::epoch_manager::force_gc ( )

inline

Force garbage collection of all epochs.

This should only be called when no threads are accessing lock-free data structures (e.g., during shutdown).

Returns

Number of objects reclaimed

Definition at line 188 of file epoch_manager.h.

                          {
            size_t total = 0;
            for (size_t i = 0; i < NUM_EPOCHS; ++i) {
                std::vector<std::pair<void*, std::function<void(void*)>>> to_delete;
                {
                    std::lock_guard<std::mutex> lock(retire_mutex_[i]);
                    to_delete = std::move(retired_[i]);
                    retired_[i].clear();
                }
 
                for (auto& [ptr, deleter] : to_delete) {
                    deleter(ptr);
                }
                total += to_delete.size();
            }
 
            if (total > 0) {
                gc_count_.fetch_add(1, std::memory_order_relaxed);
                reclaimed_count_.fetch_add(total, std::memory_order_relaxed);
            }
 
            return total;
        }

References gc_count_, NUM_EPOCHS, reclaimed_count_, retire_mutex_, and retired_.

Referenced by ~epoch_manager().

Here is the caller graph for this function:

gc_count()

size_t kcenon::container::epoch_manager::gc_count ( ) const

inlinenodiscardnoexcept

Get the number of GC cycles performed.

Returns

GC cycle count

Definition at line 224 of file epoch_manager.h.

                                                       {
            return gc_count_.load(std::memory_order_relaxed);
        }

References gc_count_.

in_critical_section()

bool kcenon::container::epoch_manager::in_critical_section ( ) const

inlinenodiscardnoexcept

Check if current thread is in critical section.

Returns

true if in critical section

Definition at line 95 of file epoch_manager.h.

                                                                {
            return thread_epoch() != INACTIVE;
        }

References INACTIVE, and thread_epoch().

Here is the call graph for this function:

instance()

static epoch_manager & kcenon::container::epoch_manager::instance ( )

inlinestatic

Get the singleton instance.

Returns

Reference to the global epoch manager

Definition at line 63 of file epoch_manager.h.

                                         {
            static epoch_manager instance;
            return instance;
        }

References instance().

Referenced by kcenon::container::epoch_guard::epoch_guard(), instance(), and kcenon::container::epoch_guard::~epoch_guard().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=() [1/2]

epoch_manager & kcenon::container::epoch_manager::operator= ( const epoch_manager & )

delete

operator=() [2/2]

epoch_manager & kcenon::container::epoch_manager::operator= ( epoch_manager && )

delete

pending_count()

size_t kcenon::container::epoch_manager::pending_count ( ) const

inlinenodiscard

Get the number of objects pending deletion.

Returns

Number of objects in retire lists

Definition at line 240 of file epoch_manager.h.

                                                   {
            size_t total = 0;
            for (size_t i = 0; i < NUM_EPOCHS; ++i) {
                std::lock_guard<std::mutex> lock(retire_mutex_[i]);
                total += retired_[i].size();
            }
            return total;
        }

References NUM_EPOCHS, retire_mutex_, and retired_.

reclaimed_count()

size_t kcenon::container::epoch_manager::reclaimed_count ( ) const

inlinenodiscardnoexcept

Get the total number of objects reclaimed.

Returns

Reclaimed object count

Definition at line 232 of file epoch_manager.h.

                                                              {
            return reclaimed_count_.load(std::memory_order_relaxed);
        }

References reclaimed_count_.

thread_epoch()

static std::atomic< uint64_t > & kcenon::container::epoch_manager::thread_epoch ( )

inlinestaticprivate

Get thread-local epoch reference.

Returns

Reference to this thread's epoch

Definition at line 272 of file epoch_manager.h.

                                                   {
            thread_local std::atomic<uint64_t> epoch{INACTIVE};
            return epoch;
        }

References INACTIVE.

Referenced by enter_critical(), exit_critical(), and in_critical_section().

Here is the caller graph for this function:

try_gc()

size_t kcenon::container::epoch_manager::try_gc ( )

inline

Attempt garbage collection.

Advances the global epoch and reclaims memory from epochs that are safe to collect (all threads have exited that epoch).

Returns

Number of objects reclaimed

Definition at line 145 of file epoch_manager.h.

                        {
            // Advance epoch
            uint64_t current = global_epoch_.fetch_add(1, std::memory_order_acq_rel);
 
            // Calculate which epoch is safe to collect
            // We need 2 epoch advances before an epoch is safe
            if (current < 2) {
                return 0;
            }
 
            uint64_t safe_epoch = current - 2;
            size_t bucket = safe_epoch % NUM_EPOCHS;
 
            // Check if any thread is still in the safe epoch
            // For simplicity, we just try to collect
            // In production, you'd check all registered threads
 
            std::vector<std::pair<void*, std::function<void(void*)>>> to_delete;
            {
                std::lock_guard<std::mutex> lock(retire_mutex_[bucket]);
                to_delete = std::move(retired_[bucket]);
                retired_[bucket].clear();
            }
 
            // Actually delete the objects
            for (auto& [ptr, deleter] : to_delete) {
                deleter(ptr);
            }
 
            gc_count_.fetch_add(1, std::memory_order_relaxed);
            reclaimed_count_.fetch_add(to_delete.size(), std::memory_order_relaxed);
 
            return to_delete.size();
        }

References gc_count_, global_epoch_, NUM_EPOCHS, reclaimed_count_, retire_mutex_, and retired_.

Member Data Documentation

gc_count_

std::atomic<size_t> kcenon::container::epoch_manager::gc_count_ {0}

private

Definition at line 278 of file epoch_manager.h.

{0};

Referenced by force_gc(), gc_count(), and try_gc().

global_epoch_

std::atomic<uint64_t> kcenon::container::epoch_manager::global_epoch_ {0}

private

Definition at line 277 of file epoch_manager.h.

{0};

Referenced by current_epoch(), defer_delete(), enter_critical(), and try_gc().

INACTIVE

uint64_t kcenon::container::epoch_manager::INACTIVE = UINT64_MAX

staticconstexpr

Sentinel value indicating thread is not in critical section.

Definition at line 52 of file epoch_manager.h.

Referenced by exit_critical(), in_critical_section(), and thread_epoch().

NUM_EPOCHS

size_t kcenon::container::epoch_manager::NUM_EPOCHS = 3

staticconstexpr

Number of epochs in rotation (must be at least 3 for safety)

Definition at line 57 of file epoch_manager.h.

Referenced by defer_delete(), force_gc(), pending_count(), and try_gc().

reclaimed_count_

std::atomic<size_t> kcenon::container::epoch_manager::reclaimed_count_ {0}

private

Definition at line 279 of file epoch_manager.h.

{0};

Referenced by force_gc(), reclaimed_count(), and try_gc().

retire_mutex_

std::array<std::mutex, NUM_EPOCHS> kcenon::container::epoch_manager::retire_mutex_

mutableprivate

Definition at line 281 of file epoch_manager.h.

Referenced by defer_delete(), force_gc(), pending_count(), and try_gc().

retired_

std::array<std::vector<std::pair<void*, std::function<void(void*)> > >, NUM_EPOCHS> kcenon::container::epoch_manager::retired_

private

Definition at line 282 of file epoch_manager.h.

Referenced by defer_delete(), force_gc(), pending_count(), and try_gc().

---

The documentation for this class was generated from the following file:

• internal/epoch_manager.h