Helper class to add wait/notify functionality to std::atomic. More...

#include <atomic_wait.h>

Collaboration diagram for kcenon::thread::atomic_wait_helper< T >:

Public Member Functions
void	wait (std::atomic< T > &atomic, T old) noexcept
	Blocks until the atomic value differs from the expected value.

void	notify_one () noexcept
	Unblocks one thread waiting on this atomic.

void	notify_all () noexcept
	Unblocks all threads waiting on this atomic.

Private Attributes
std::mutex	mutex_

std::condition_variable	cv_

Detailed Description

template<typename T>
class kcenon::thread::atomic_wait_helper< T >

Helper class to add wait/notify functionality to std::atomic.

This class provides atomic waiting primitives similar to C++20's std::atomic::wait/notify. It uses an efficient implementation with:

Short spin-wait to avoid syscalls for quickly-changing values
Mutex + condition_variable for blocking wait
Proper memory ordering to ensure correctness

Template Parameters

T	The atomic value type (must be trivially copyable)

Usage:

std::atomic<int> value{0};
atomic_wait_helper<int> waiter;
 
// Thread 1: Wait until value changes from 0
waiter.wait(value, 0);
 
// Thread 2: Change value and notify
value.store(1, std::memory_order_release);
waiter.notify_one();

Definition at line 63 of file atomic_wait.h.

Member Function Documentation

◆ notify_all()

template<typename T >

void kcenon::thread::atomic_wait_helper< T >::notify_all ( )

inlinenoexcept

Unblocks all threads waiting on this atomic.

All waiting threads will wake up and re-check their condition.

Definition at line 138 of file atomic_wait.h.

                               {
        std::lock_guard<std::mutex> lock(mutex_);
        cv_.notify_all();
    }

References kcenon::thread::atomic_wait_helper< T >::cv_, and kcenon::thread::atomic_wait_helper< T >::mutex_.

◆ notify_one()

template<typename T >

void kcenon::thread::atomic_wait_helper< T >::notify_one ( )

inlinenoexcept

Unblocks one thread waiting on this atomic.

If multiple threads are waiting, exactly one will be woken up. Which thread is unspecified (depends on scheduler).

Definition at line 126 of file atomic_wait.h.

                               {
        // Lock-free fast path: if no waiters, skip mutex
        // Note: This is an optimization, correctness doesn't depend on it
        std::lock_guard<std::mutex> lock(mutex_);
        cv_.notify_one();
    }

References kcenon::thread::atomic_wait_helper< T >::cv_, and kcenon::thread::atomic_wait_helper< T >::mutex_.

◆ wait()

template<typename T >

void kcenon::thread::atomic_wait_helper< T >::wait	(	std::atomic< T > &	atomic,
		T	old )

inlinenoexcept

Blocks until the atomic value differs from the expected value.

This function implements an efficient wait with:

Short spin-wait (SPIN_COUNT iterations)
Exponential backoff
Blocking wait on condition variable if still unchanged

Memory ordering: Uses acquire semantics to ensure proper synchronization

Parameters

atomic	The atomic variable to monitor
old	The expected value to wait for change

Definition at line 81 of file atomic_wait.h.

                                                    {
        // Phase 1: Short spin-wait
        // Rationale: Many atomic operations complete quickly, avoiding syscall overhead
        constexpr int SPIN_COUNT = 40;
        for (int i = 0; i < SPIN_COUNT; ++i) {
            if (atomic.load(std::memory_order_acquire) != old) {
                return;
            }
            // Hint to CPU: this is a spin-wait loop
            #if defined(__x86_64__) || defined(_M_X64) || defined(__i386__) || defined(_M_IX86)
                __builtin_ia32_pause();
            #elif defined(__aarch64__) || defined(_M_ARM64)
                __asm__ __volatile__("yield" ::: "memory");
            #else
                std::this_thread::yield();
            #endif
        }
 
        // Phase 2: Exponential backoff with brief sleeps
        // Rationale: Longer operations benefit from yielding CPU
        constexpr int BACKOFF_COUNT = 5;
        auto backoff_time = std::chrono::microseconds(1);
 
        for (int i = 0; i < BACKOFF_COUNT; ++i) {
            if (atomic.load(std::memory_order_acquire) != old) {
                return;
            }
            std::this_thread::sleep_for(backoff_time);
            backoff_time *= 2; // Exponential backoff
        }
 
        // Phase 3: Blocking wait
        // Rationale: Value hasn't changed after spin+backoff, use efficient blocking
        std::unique_lock<std::mutex> lock(mutex_);
        cv_.wait(lock, [&] {
            return atomic.load(std::memory_order_acquire) != old;
        });
    }