Global Hazard Pointer Domain Manager. More...

#include <safe_hazard_pointer.h>

Collaboration diagram for kcenon::thread::safe_hazard_pointer_domain:

Public Types
using	retire_callback = std::function<void(void*)>

Public Member Functions
safe_hazard_pointer_record *	acquire ()
	Acquire a hazard pointer record for current thread.

void	release (safe_hazard_pointer_record *record) noexcept
	Release a hazard pointer record.

void	retire (void *p, retire_callback deleter)
	Retire a pointer for later reclamation.

void	collect ()
	Collect reclaimable objects.

size_t	retired_count () const noexcept
	Get current retired count.

size_t	active_count () const noexcept
	Get active thread count.

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

Private Member Functions
	safe_hazard_pointer_domain ()=default

	~safe_hazard_pointer_domain ()

	safe_hazard_pointer_domain (const safe_hazard_pointer_domain &)=delete

safe_hazard_pointer_domain &	operator= (const safe_hazard_pointer_domain &)=delete

void	collect_internal ()
	Collect reclaimable objects (internal, lock held)

size_t	get_adaptive_threshold () const noexcept
	Get adaptive threshold based on active thread count.

Private Attributes
std::atomic< safe_hazard_pointer_record * >	head_ {nullptr}

std::atomic< size_t >	active_count_ {0}

std::atomic< size_t >	retired_count_ {0}

std::mutex	retire_mutex_

std::vector< std::pair< void *, retire_callback > >	retired_list_

Detailed Description

Global Hazard Pointer Domain Manager.

Manages all thread-local hazard pointer records centrally. Provides safe memory reclamation with explicit memory ordering guarantees.

Thread-safe and lock-free for acquire/release operations.

Definition at line 114 of file safe_hazard_pointer.h.

Member Typedef Documentation

◆ retire_callback

using kcenon::thread::safe_hazard_pointer_domain::retire_callback = std::function<void(void*)>

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 116 of file safe_hazard_pointer.h.

Constructor & Destructor Documentation

◆ safe_hazard_pointer_domain() [1/2]

kcenon::thread::safe_hazard_pointer_domain::safe_hazard_pointer_domain ( )

privatedefault

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

◆ ~safe_hazard_pointer_domain()

kcenon::thread::safe_hazard_pointer_domain::~safe_hazard_pointer_domain ( )

inlineprivate

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 257 of file safe_hazard_pointer.h.

                                  {
        // Delete all records
        auto* p = head_.load(std::memory_order_relaxed);
        while (p != nullptr) {
            auto* next = p->next.load(std::memory_order_relaxed);
            delete p;
            p = next;
        }
 
        // Force delete remaining retired objects
        for (auto& [ptr, deleter] : retired_list_) {
            if (deleter && ptr) {
                deleter(ptr);
            }
        }
    }

References head_, and retired_list_.

◆ safe_hazard_pointer_domain() [2/2]

kcenon::thread::safe_hazard_pointer_domain::safe_hazard_pointer_domain ( const safe_hazard_pointer_domain & )

privatedelete

Member Function Documentation

◆ acquire()

safe_hazard_pointer_record * kcenon::thread::safe_hazard_pointer_domain::acquire ( )

inline

Acquire a hazard pointer record for current thread.

Returns: Pointer to acquired record

Lock-free acquisition with proper memory ordering.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 132 of file safe_hazard_pointer.h.

                                          {
        // 1. Try to reuse an inactive record first
        safe_hazard_pointer_record* p = head_.load(std::memory_order_acquire);
        while (p != nullptr) {
            bool expected = false;
            if (p->active.compare_exchange_strong(
                    expected, true,
                    std::memory_order_acq_rel,
                    std::memory_order_relaxed)) {
                // Clear hazard pointers immediately after acquiring to avoid
                // stale pointers from previous use affecting collect()
                p->clear(0);
                p->clear(1);
                active_count_.fetch_add(1, std::memory_order_relaxed);
                return p;
            }
            p = p->next.load(std::memory_order_acquire);
        }
 
        // 2. Create new record (constructor already clears hazard pointers)
        auto* new_record = new safe_hazard_pointer_record();
        new_record->active.store(true, std::memory_order_relaxed);
 
        // 3. Add to list (lock-free)
        safe_hazard_pointer_record* old_head;
        do {
            old_head = head_.load(std::memory_order_relaxed);
            new_record->next.store(old_head, std::memory_order_relaxed);
        } while (!head_.compare_exchange_weak(
            old_head, new_record,
            std::memory_order_release,
            std::memory_order_relaxed));
 
        active_count_.fetch_add(1, std::memory_order_relaxed);
        return new_record;
    }

References kcenon::thread::safe_hazard_pointer_record::active, active_count_, kcenon::thread::safe_hazard_pointer_record::clear(), head_, and kcenon::thread::safe_hazard_pointer_record::next.

Here is the call graph for this function:

◆ active_count()

size_t kcenon::thread::safe_hazard_pointer_domain::active_count ( ) const

inlinenodiscardnoexcept

Get active thread count.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 250 of file safe_hazard_pointer.h.

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

References active_count_.

◆ collect()

void kcenon::thread::safe_hazard_pointer_domain::collect ( )

inline

Collect reclaimable objects.

Scans all hazard pointers and deletes objects that are not protected.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 235 of file safe_hazard_pointer.h.

                   {
        std::lock_guard<std::mutex> lock(retire_mutex_);
        collect_internal();
    }

References collect_internal(), and retire_mutex_.

Referenced by kcenon::thread::typed_safe_hazard_domain< T >::collect(), and retire().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ collect_internal()

void kcenon::thread::safe_hazard_pointer_domain::collect_internal ( )

inlineprivate

Collect reclaimable objects (internal, lock held)

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 281 of file safe_hazard_pointer.h.

                            {
        if (retired_list_.empty()) {
            return;
        }
 
        // Gather all currently protected pointers
        // IMPORTANT: Check ALL records, not just active ones, to avoid race condition
        // where a record is being reused while we're scanning.
        // The hazard pointer value is set before active=true, so we must check
        // the pointer value itself, not the active flag.
        std::unordered_set<void*> hazards;
        hazards.reserve(active_count_.load(std::memory_order_relaxed) *
                        safe_hazard_pointer_record::MAX_HAZARD_POINTERS);
 
        safe_hazard_pointer_record* p = head_.load(std::memory_order_acquire);
        while (p != nullptr) {
            // Check all records regardless of active status to avoid race condition
            for (size_t i = 0; i < safe_hazard_pointer_record::MAX_HAZARD_POINTERS; ++i) {
                void* hp = p->get(i);
                if (hp != nullptr) {
                    hazards.insert(hp);
                }
            }
            p = p->next.load(std::memory_order_acquire);
        }
 
        // Delete objects not in hazard set
        size_t reclaimed = 0;
        auto it = retired_list_.begin();
        while (it != retired_list_.end()) {
            if (hazards.find(it->first) == hazards.end()) {
                // Safe to delete
                if (it->second && it->first) {
                    it->second(it->first);
                }
                it = retired_list_.erase(it);
                ++reclaimed;
            } else {
                ++it;
            }
        }
 
        retired_count_.fetch_sub(reclaimed, std::memory_order_relaxed);
    }

References active_count_, kcenon::thread::safe_hazard_pointer_record::get(), head_, kcenon::thread::safe_hazard_pointer_record::MAX_HAZARD_POINTERS, kcenon::thread::safe_hazard_pointer_record::next, retired_count_, and retired_list_.

Referenced by collect().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_adaptive_threshold()

size_t kcenon::thread::safe_hazard_pointer_domain::get_adaptive_threshold ( ) const

inlinenodiscardprivatenoexcept

Get adaptive threshold based on active thread count.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 329 of file safe_hazard_pointer.h.

                                                                 {
        static constexpr size_t BASE_THRESHOLD = 64;
        static constexpr size_t PER_THREAD_THRESHOLD = 16;
        static constexpr size_t MAX_THRESHOLD = 512;
 
        size_t active = active_count_.load(std::memory_order_relaxed);
        return std::min(MAX_THRESHOLD, BASE_THRESHOLD + active * PER_THREAD_THRESHOLD);
    }

References kcenon::thread::active, and active_count_.

Referenced by retire().

Here is the caller graph for this function:

◆ instance()

static safe_hazard_pointer_domain & kcenon::thread::safe_hazard_pointer_domain::instance ( )

inlinestatic

Get singleton instance.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 121 of file safe_hazard_pointer.h.

                                                  {
        static safe_hazard_pointer_domain domain;
        return domain;
    }

Referenced by kcenon::thread::typed_safe_hazard_domain< T >::collect(), kcenon::thread::safe_hazard_guard::operator=(), kcenon::thread::detail::lockfree_job_queue::retire_node(), kcenon::thread::safe_retire_hazard(), and kcenon::thread::safe_hazard_guard::~safe_hazard_guard().

Here is the caller graph for this function:

◆ operator=()

safe_hazard_pointer_domain & kcenon::thread::safe_hazard_pointer_domain::operator= ( const safe_hazard_pointer_domain & )

privatedelete

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

◆ release()

void kcenon::thread::safe_hazard_pointer_domain::release ( safe_hazard_pointer_record * record )

inlinenoexcept

Release a hazard pointer record.

Parameters

record Record to release

Clears all hazard pointers and marks record as inactive.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 175 of file safe_hazard_pointer.h.

                                                              {
        if (record == nullptr) {
            return;
        }
 
        record->clear(0);
        record->clear(1);
        record->active.store(false, std::memory_order_release);
        active_count_.fetch_sub(1, std::memory_order_relaxed);
    }

References active_count_.

Referenced by kcenon::thread::safe_hazard_guard::operator=(), and kcenon::thread::safe_hazard_guard::~safe_hazard_guard().

Here is the caller graph for this function:

◆ retire()

void kcenon::thread::safe_hazard_pointer_domain::retire	(	void *	p,
		retire_callback	deleter )

inline

Retire a pointer for later reclamation.

Parameters

p	Pointer to retire
deleter	Deletion callback

Thread-safe. Triggers collection when threshold is reached. Handles duplicate addresses by removing old entries (memory reuse scenario).

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 194 of file safe_hazard_pointer.h.

                                                  {
        if (p == nullptr) {
            return;
        }
 
        bool should_collect = false;
        {
            std::lock_guard<std::mutex> lock(retire_mutex_);
 
            // Remove any existing entry with the same address to handle memory reuse.
            // This can happen when memory is freed and reallocated to the same address.
            // In this case, the old entry's deleter must NOT be called since the memory
            // is now occupied by a new valid object.
            auto it = std::remove_if(retired_list_.begin(), retired_list_.end(),
                [p](const auto& entry) { return entry.first == p; });
            if (it != retired_list_.end()) {
                size_t removed = std::distance(it, retired_list_.end());
                retired_list_.erase(it, retired_list_.end());
                retired_count_.fetch_sub(removed, std::memory_order_relaxed);
            }
 
            retired_list_.emplace_back(p, std::move(deleter));
            retired_count_.fetch_add(1, std::memory_order_relaxed);
 
            // Check threshold inside lock to avoid race
            size_t threshold = get_adaptive_threshold();
            should_collect = (retired_count_.load(std::memory_order_relaxed) >= threshold);
        }
 
        // Trigger collection after releasing lock to avoid deadlock
        if (should_collect) {
            collect();
        }
    }

References collect(), get_adaptive_threshold(), retire_mutex_, retired_count_, and retired_list_.

Referenced by kcenon::thread::detail::lockfree_job_queue::retire_node(), and kcenon::thread::safe_retire_hazard().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ retired_count()

size_t kcenon::thread::safe_hazard_pointer_domain::retired_count ( ) const

inlinenodiscardnoexcept

Get current retired count.

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 243 of file safe_hazard_pointer.h.

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

References retired_count_.

Member Data Documentation

◆ active_count_

std::atomic<size_t> kcenon::thread::safe_hazard_pointer_domain::active_count_ {0}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 339 of file safe_hazard_pointer.h.

339{0};

Referenced by acquire(), active_count(), collect_internal(), get_adaptive_threshold(), and release().

◆ head_

std::atomic<safe_hazard_pointer_record*> kcenon::thread::safe_hazard_pointer_domain::head_ {nullptr}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 338 of file safe_hazard_pointer.h.

338{nullptr};

Referenced by acquire(), collect_internal(), and ~safe_hazard_pointer_domain().

◆ retire_mutex_

std::mutex kcenon::thread::safe_hazard_pointer_domain::retire_mutex_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 341 of file safe_hazard_pointer.h.

Referenced by collect(), and retire().

◆ retired_count_

std::atomic<size_t> kcenon::thread::safe_hazard_pointer_domain::retired_count_ {0}

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 340 of file safe_hazard_pointer.h.

340{0};

Referenced by collect_internal(), retire(), and retired_count().

◆ retired_list_

std::vector<std::pair<void*, retire_callback> > kcenon::thread::safe_hazard_pointer_domain::retired_list_

private

Examples: /home/runner/work/thread_system/thread_system/include/kcenon/thread/core/safe_hazard_pointer.h.

Definition at line 342 of file safe_hazard_pointer.h.

Referenced by collect_internal(), retire(), and ~safe_hazard_pointer_domain().

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

include/kcenon/thread/core/safe_hazard_pointer.h

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ retire_callback

Constructor & Destructor Documentation

◆ safe_hazard_pointer_domain() [1/2]

◆ ~safe_hazard_pointer_domain()

◆ safe_hazard_pointer_domain() [2/2]

Member Function Documentation

◆ acquire()

◆ active_count()

◆ collect()

◆ collect_internal()

◆ get_adaptive_threshold()

◆ instance()

◆ operator=()

◆ release()

◆ retire()

◆ retired_count()

Member Data Documentation

◆ active_count_

◆ head_

◆ retire_mutex_

◆ retired_count_

◆ retired_list_