True lock-free reader using RCU (Read-Copy-Update) pattern. More...

#include <thread_safe_container.h>

Collaboration diagram for kcenon::container::lockfree_container_reader:

Public Types
using	snapshot_type = std::unordered_map<std::string, value>

using	snapshot_ptr = std::shared_ptr<const snapshot_type>

Public Member Functions
	lockfree_container_reader (std::shared_ptr< thread_safe_container > container)
	Construct reader from container.

	lockfree_container_reader (const lockfree_container_reader &other)
	Copy constructor.

	lockfree_container_reader (lockfree_container_reader &&other) noexcept
	Move constructor.

lockfree_container_reader &	operator= (const lockfree_container_reader &other)
	Copy assignment.

lockfree_container_reader &	operator= (lockfree_container_reader &&other) noexcept
	Move assignment.

	~lockfree_container_reader ()=default
	Destructor.

template<concepts::ValueVariantType T>
std::optional< T >	get (std::string_view key) const noexcept
	Lock-free typed value read.

bool	contains (std::string_view key) const noexcept
	Lock-free value existence check.

size_t	size () const noexcept
	Lock-free snapshot size check.

bool	empty () const noexcept
	Lock-free empty check.

std::vector< std::string >	keys () const
	Get all keys from snapshot (lock-free)

template<typename Func >
void	for_each (Func &&func) const
	Iterate over snapshot (lock-free for snapshot access)

void	refresh ()
	Refresh snapshot from source container.

size_t	refresh_count () const noexcept
	Get the number of refreshes performed.

std::shared_ptr< thread_safe_container >	source () const noexcept
	Get the source container.

Private Attributes
std::shared_ptr< thread_safe_container >	container_

snapshot_ptr	snapshot_

std::atomic< size_t >	refresh_count_ {0}

Detailed Description

True lock-free reader using RCU (Read-Copy-Update) pattern.

Unlike snapshot_reader which still uses a shared_mutex for snapshot access, this class provides genuinely lock-free reads using atomic shared_ptr operations. The trade-off is that reads may return slightly stale data between refreshes.

Properties:

Read: Wait-free O(1) - no locks, no blocking, no spinning
Refresh: Blocking (acquires source container lock)
Memory: Automatic reclamation via shared_ptr reference counting

Use this when:

You need true lock-free reads (e.g., signal handlers, real-time systems)
Read performance is critical and slight staleness is acceptable
You have many concurrent readers

// Create lock-free reader
auto container = std::make_shared<thread_safe_container>();
lockfree_container_reader reader(container);
 
// Lock-free reads from any thread
auto value = reader.get<int>("counter");  // No locks!
 
// Periodic refresh (e.g., from background thread)
reader.refresh();

Definition at line 383 of file thread_safe_container.h.

Member Typedef Documentation

◆ snapshot_ptr

using kcenon::container::lockfree_container_reader::snapshot_ptr = std::shared_ptr<const snapshot_type>

Definition at line 386 of file thread_safe_container.h.

◆ snapshot_type

using kcenon::container::lockfree_container_reader::snapshot_type = std::unordered_map<std::string, value>

Definition at line 385 of file thread_safe_container.h.

Constructor & Destructor Documentation

◆ lockfree_container_reader() [1/3]

kcenon::container::lockfree_container_reader::lockfree_container_reader ( std::shared_ptr< thread_safe_container > container )

inlineexplicit

Construct reader from container.

Parameters

container The thread-safe container to read from

Definition at line 392 of file thread_safe_container.h.

            : container_(std::move(container))
            , snapshot_(std::make_shared<const snapshot_type>())
        {
            refresh();
        }

References refresh().

Here is the call graph for this function:

◆ lockfree_container_reader() [2/3]

kcenon::container::lockfree_container_reader::lockfree_container_reader ( const lockfree_container_reader & other )

inline

Copy constructor.

Definition at line 402 of file thread_safe_container.h.

            : container_(other.container_)
            , snapshot_(std::atomic_load_explicit(&other.snapshot_, std::memory_order_acquire))
        {}

◆ lockfree_container_reader() [3/3]

kcenon::container::lockfree_container_reader::lockfree_container_reader ( lockfree_container_reader && other )

inlinenoexcept

Move constructor.

Definition at line 410 of file thread_safe_container.h.

            : container_(std::move(other.container_))
            , snapshot_(std::atomic_load_explicit(&other.snapshot_, std::memory_order_acquire))
        {}

◆ ~lockfree_container_reader()

kcenon::container::lockfree_container_reader::~lockfree_container_reader ( )

default

Destructor.

Member Function Documentation

◆ contains()

bool kcenon::container::lockfree_container_reader::contains ( std::string_view key ) const

inlinenodiscardnoexcept

Lock-free value existence check.

Parameters

key	The key to check

Returns: true if key exists in snapshot, false otherwise

Thread safety: Safe to call concurrently with any operation

Definition at line 479 of file thread_safe_container.h.

                                                                       {
            auto snap = std::atomic_load_explicit(&snapshot_, std::memory_order_acquire);
            if (!snap) {
                return false;
            }
            return snap->find(std::string(key)) != snap->end();
        }

References snapshot_.

◆ empty()

bool kcenon::container::lockfree_container_reader::empty ( ) const

inlinenodiscardnoexcept

Lock-free empty check.

Returns: true if snapshot is empty, false otherwise

Thread safety: Safe to call concurrently with any operation

Definition at line 506 of file thread_safe_container.h.

                                                  {
            return size() == 0;
        }

References size().

Here is the call graph for this function:

◆ for_each()

template<typename Func >

void kcenon::container::lockfree_container_reader::for_each ( Func && func ) const

inline

Iterate over snapshot (lock-free for snapshot access)

The callback is called for each key-value pair in the snapshot. The iteration itself is lock-free, but the callback may perform locking operations.

Template Parameters

Func	Callback function type: void(const std::string&, const value&)

Parameters

func	Callback to apply to each key-value pair

Thread safety: Safe to call concurrently with any operation

Definition at line 542 of file thread_safe_container.h.

                                         {
            auto snap = std::atomic_load_explicit(&snapshot_, std::memory_order_acquire);
            if (snap) {
                for (const auto& [key, val] : *snap) {
                    func(key, val);
                }
            }
        }

References snapshot_.

◆ get()

template<concepts::ValueVariantType T>

std::optional< T > kcenon::container::lockfree_container_reader::get ( std::string_view key ) const

inlinenodiscardnoexcept

Lock-free typed value read.

This operation is wait-free: it completes in O(1) time regardless of what other threads are doing. The snapshot may be stale; call refresh() to update.

Template Parameters

T	The expected value type (must satisfy ValueVariantType)

Parameters

key	The key to look up

Returns: Optional containing value if found and type matches

Thread safety: Safe to call concurrently with any operation including refresh()

Definition at line 458 of file thread_safe_container.h.

                                                                            {
            auto snap = std::atomic_load_explicit(&snapshot_, std::memory_order_acquire);
            if (!snap) {
                return std::nullopt;
            }
 
            auto it = snap->find(std::string(key));
            if (it != snap->end()) {
                return it->second.get<T>();
            }
            return std::nullopt;
        }

References snapshot_.

◆ keys()

std::vector< std::string > kcenon::container::lockfree_container_reader::keys ( ) const

inlinenodiscard

Get all keys from snapshot (lock-free)

Returns: Vector of keys in the current snapshot

Thread safety: Safe to call concurrently with any operation

Definition at line 517 of file thread_safe_container.h.

                                                        {
            auto snap = std::atomic_load_explicit(&snapshot_, std::memory_order_acquire);
            std::vector<std::string> result;
            if (snap) {
                result.reserve(snap->size());
                for (const auto& [key, val] : *snap) {
                    result.push_back(key);
                }
            }
            return result;
        }

References snapshot_.

◆ operator=() [1/2]

lockfree_container_reader & kcenon::container::lockfree_container_reader::operator= ( const lockfree_container_reader & other )

inline

Copy assignment.

Definition at line 418 of file thread_safe_container.h.

                                                                                     {
            if (this != &other) {
                container_ = other.container_;
                auto new_snapshot = std::atomic_load_explicit(&other.snapshot_, std::memory_order_acquire);
                std::atomic_store_explicit(&snapshot_, new_snapshot, std::memory_order_release);
            }
            return *this;
        }

References container_, and snapshot_.

◆ operator=() [2/2]

lockfree_container_reader & kcenon::container::lockfree_container_reader::operator= ( lockfree_container_reader && other )

inlinenoexcept

Move assignment.

Definition at line 430 of file thread_safe_container.h.

                                                                                         {
            if (this != &other) {
                container_ = std::move(other.container_);
                auto new_snapshot = std::atomic_load_explicit(&other.snapshot_, std::memory_order_acquire);
                std::atomic_store_explicit(&snapshot_, new_snapshot, std::memory_order_release);
            }
            return *this;
        }

References container_, and snapshot_.

◆ refresh()

void kcenon::container::lockfree_container_reader::refresh ( )

inline

Refresh snapshot from source container.

This operation acquires the container's read lock to create a new snapshot. After this call returns, subsequent lock-free reads will see the updated data.

Thread safety: Safe to call concurrently with reads, but multiple concurrent refreshes may waste work (only one will "win").

Definition at line 560 of file thread_safe_container.h.

                       {
            auto new_snapshot = std::make_shared<snapshot_type>();
            container_->for_each([&new_snapshot](const std::string& key, const value& val) {
                new_snapshot->emplace(key, val);
            });
            std::atomic_store_explicit(&snapshot_,
                                      snapshot_ptr(new_snapshot),
                                      std::memory_order_release);
            refresh_count_.fetch_add(1, std::memory_order_relaxed);
        }

References container_, refresh_count_, and snapshot_.

Referenced by lockfree_container_reader().

Here is the caller graph for this function:

◆ refresh_count()

size_t kcenon::container::lockfree_container_reader::refresh_count ( ) const

inlinenodiscardnoexcept

Get the number of refreshes performed.

Returns: Refresh count since construction

Definition at line 575 of file thread_safe_container.h.

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

References refresh_count_.

◆ size()

size_t kcenon::container::lockfree_container_reader::size ( ) const

inlinenodiscardnoexcept

Lock-free snapshot size check.

Returns: Number of values in the current snapshot

Thread safety: Safe to call concurrently with any operation

Definition at line 494 of file thread_safe_container.h.

                                                   {
            auto snap = std::atomic_load_explicit(&snapshot_, std::memory_order_acquire);
            return snap ? snap->size() : 0;
        }

References snapshot_.

Referenced by empty().

Here is the caller graph for this function:

◆ source()

std::shared_ptr< thread_safe_container > kcenon::container::lockfree_container_reader::source ( ) const

inlinenodiscardnoexcept

Get the source container.

Returns: Shared pointer to the source container

Definition at line 583 of file thread_safe_container.h.

                                                                                   {
            return container_;
        }

References container_.

Member Data Documentation

◆ container_

std::shared_ptr<thread_safe_container> kcenon::container::lockfree_container_reader::container_

private

Definition at line 588 of file thread_safe_container.h.

Referenced by operator=(), operator=(), refresh(), and source().

◆ refresh_count_

std::atomic<size_t> kcenon::container::lockfree_container_reader::refresh_count_ {0}

private

Definition at line 590 of file thread_safe_container.h.

590{0};

Referenced by refresh(), and refresh_count().

◆ snapshot_

snapshot_ptr kcenon::container::lockfree_container_reader::snapshot_

private

Definition at line 589 of file thread_safe_container.h.

Referenced by contains(), for_each(), get(), keys(), operator=(), operator=(), refresh(), and size().

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

internal/thread_safe_container.h

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ snapshot_ptr

◆ snapshot_type

Constructor & Destructor Documentation

◆ lockfree_container_reader() [1/3]

◆ lockfree_container_reader() [2/3]

◆ lockfree_container_reader() [3/3]

◆ ~lockfree_container_reader()

Member Function Documentation

◆ contains()

◆ empty()

◆ for_each()

◆ get()

◆ keys()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ refresh()

◆ refresh_count()

◆ size()

◆ source()

Member Data Documentation

◆ container_

◆ refresh_count_

◆ snapshot_