Lock-free circular buffer for single-producer single-consumer (SPSC). More...

#include <circular_buffer.h>

Collaboration diagram for kcenon::common::utils::SPSCCircularBuffer< T, Capacity >:

Public Member Functions
	SPSCCircularBuffer ()=default

bool	push (const T &value)
	Push a value (producer thread only).

bool	push (T &&value)

std::optional< T >	pop ()
	Pop a value (consumer thread only).

bool	empty () const noexcept

bool	full () const noexcept

std::size_t	size () const noexcept

constexpr std::size_t	capacity () const noexcept

Static Private Member Functions
static std::size_t	advance (std::size_t index) noexcept

Private Attributes
std::array< T, Capacity+1 >	buffer_ {}

std::atomic< std::size_t >	head_ {0}

std::atomic< std::size_t >	tail_ {0}

Detailed Description

template<typename T, std::size_t Capacity>
class kcenon::common::utils::SPSCCircularBuffer< T, Capacity >

Lock-free circular buffer for single-producer single-consumer (SPSC).

Uses std::atomic head/tail with acquire/release ordering. No mutex is needed because only the producer modifies tail_ and only the consumer modifies head_. Capacity must be > 0. One slot is reserved to distinguish full from empty, so the usable capacity is exactly Capacity elements.

Examples: utility_containers_example.cpp.

Definition at line 118 of file circular_buffer.h.

Constructor & Destructor Documentation

◆ SPSCCircularBuffer()

template<typename T , std::size_t Capacity>

kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::SPSCCircularBuffer ( )

default

Member Function Documentation

◆ advance()

template<typename T , std::size_t Capacity>

static std::size_t kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::advance ( std::size_t index )

inlinestaticprivatenoexcept

Definition at line 188 of file circular_buffer.h.

                                                       {
        return (index + 1) % (Capacity + 1);
    }

Referenced by kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::full(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::pop(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push().

Here is the caller graph for this function:

◆ capacity()

template<typename T , std::size_t Capacity>

std::size_t kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::capacity ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 183 of file circular_buffer.h.

                                                                {
        return Capacity;
    }

◆ empty()

template<typename T , std::size_t Capacity>

bool kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::empty ( ) const

inlinenodiscardnoexcept

Definition at line 164 of file circular_buffer.h.

                                              {
        return head_.load(std::memory_order_acquire)
            == tail_.load(std::memory_order_acquire);
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

◆ full()

template<typename T , std::size_t Capacity>

bool kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::full ( ) const

inlinenodiscardnoexcept

Definition at line 169 of file circular_buffer.h.

                                             {
        return advance(tail_.load(std::memory_order_acquire))
            == head_.load(std::memory_order_acquire);
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::advance(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

Here is the call graph for this function:

◆ pop()

template<typename T , std::size_t Capacity>

std::optional< T > kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::pop ( )

inlinenodiscard

Pop a value (consumer thread only).

Returns: The value if available, std::nullopt if empty.

Examples: utility_containers_example.cpp.

Definition at line 154 of file circular_buffer.h.

                                       {
        const auto head = head_.load(std::memory_order_relaxed);
        if (head == tail_.load(std::memory_order_acquire)) {
            return std::nullopt; // empty
        }
        auto value = std::move(buffer_[head]);
        head_.store(advance(head), std::memory_order_release);
        return value;
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::advance(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::buffer_, kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ push() [1/2]

template<typename T , std::size_t Capacity>

bool kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push ( const T & value )

inline

Push a value (producer thread only).

Returns: true if pushed, false if full.

Examples: utility_containers_example.cpp.

Definition at line 128 of file circular_buffer.h.

                              {
        const auto tail = tail_.load(std::memory_order_relaxed);
        const auto next_tail = advance(tail);
        if (next_tail == head_.load(std::memory_order_acquire)) {
            return false; // full
        }
        buffer_[tail] = value;
        tail_.store(next_tail, std::memory_order_release);
        return true;
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::advance(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::buffer_, kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ push() [2/2]

template<typename T , std::size_t Capacity>

bool kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push ( T && value )

inline

Definition at line 139 of file circular_buffer.h.

                         {
        const auto tail = tail_.load(std::memory_order_relaxed);
        const auto next_tail = advance(tail);
        if (next_tail == head_.load(std::memory_order_acquire)) {
            return false; // full
        }
        buffer_[tail] = std::move(value);
        tail_.store(next_tail, std::memory_order_release);
        return true;
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::advance(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::buffer_, kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

Here is the call graph for this function:

◆ size()

template<typename T , std::size_t Capacity>

std::size_t kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::size ( ) const

inlinenodiscardnoexcept

Examples: utility_containers_example.cpp.

Definition at line 174 of file circular_buffer.h.

                                                  {
        const auto head = head_.load(std::memory_order_acquire);
        const auto tail = tail_.load(std::memory_order_acquire);
        if (tail >= head) {
            return tail - head;
        }
        return (Capacity + 1) - head + tail;
    }

References kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_, and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_.

Referenced by main().

Here is the caller graph for this function:

Member Data Documentation

◆ buffer_

template<typename T , std::size_t Capacity>

std::array<T, Capacity + 1> kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::buffer_ {}

private

Definition at line 193 of file circular_buffer.h.

193{};

Referenced by kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::pop(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push().

◆ head_

template<typename T , std::size_t Capacity>

std::atomic<std::size_t> kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::head_ {0}

private

Definition at line 194 of file circular_buffer.h.

194{0};

Referenced by kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::empty(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::full(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::pop(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::size().

◆ tail_

template<typename T , std::size_t Capacity>

std::atomic<std::size_t> kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::tail_ {0}

private

Definition at line 195 of file circular_buffer.h.

195{0};

Referenced by kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::empty(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::full(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::pop(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::push(), and kcenon::common::utils::SPSCCircularBuffer< T, Capacity >::size().

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

include/kcenon/common/utils/circular_buffer.h

Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SPSCCircularBuffer()

Member Function Documentation

◆ advance()

◆ capacity()

◆ empty()

◆ full()

◆ pop()

◆ push() [1/2]

◆ push() [2/2]

◆ size()

Member Data Documentation

◆ buffer_

◆ head_

◆ tail_