vlink::MpmcQueueBase Class Reference

Non-template base class that owns every element-type-independent piece of state. More...

#include <mpmc_queue.h>

Inheritance diagram for vlink::MpmcQueueBase:

Collaboration diagram for vlink::MpmcQueueBase:

Classes
struct	QuitFlag

Public Types
enum	Behavior : uint8_t { kNoBehavior = 0 , kConditionBehavior = 1 }
	Per-call notification behaviour selector. More...

Public Member Functions
size_t	capacity () const noexcept VLINK_NO_INSTRUMENT
	Returns the fixed capacity chosen at construction. More...
size_t	size (bool real=false) const noexcept VLINK_NO_INSTRUMENT
	Returns an approximate count of currently enqueued elements. More...
bool	empty (bool real=false) const noexcept VLINK_NO_INSTRUMENT
	Returns true when the queue appears empty. More...
bool	is_full (bool real=false) const noexcept VLINK_NO_INSTRUMENT
	Returns true when the queue appears full. More...
bool	wait_not_empty (std::chrono::milliseconds timeout=std::chrono::milliseconds(0)) noexcept VLINK_NO_INSTRUMENT
	Blocks until the queue is non-empty or timeout elapses. More...
bool	wait_not_full (std::chrono::milliseconds timeout=std::chrono::milliseconds(0)) noexcept VLINK_NO_INSTRUMENT
	Blocks until the queue has free space or timeout elapses. More...
void	notify_to_quit () noexcept VLINK_NO_INSTRUMENT
	Signals graceful shutdown to every waiter and rejects further pushes. More...

Protected Member Functions
	MpmcQueueBase (size_t capacity)
	~MpmcQueueBase () noexcept=default
constexpr size_t	idx (size_t i) const noexcept
constexpr size_t	turn (size_t i) const noexcept

Static Protected Member Functions
static void	throw_mpmc_invalid_capacity ()
static void	throw_mpmc_alignment_failure ()

Protected Attributes
std::atomic< size_t >	head_ {0U}
void *	chunk_storage_ {nullptr}
size_t	capacity_ {0}
std::mutex	cv_mtx_
std::atomic< size_t >	tail_ {0U}
ConditionVariable	cv_not_empty_
ConditionVariable	cv_not_full_
struct vlink::MpmcQueueBase::QuitFlag	quit_flag_

Static Protected Attributes
static constexpr std::memory_order	kMemoryOrderAcquire = std::memory_order_acquire
static constexpr std::memory_order	kMemoryOrderRelease = std::memory_order_release
static constexpr std::memory_order	kMemoryOrderRelaxed = std::memory_order_relaxed
static constexpr size_t	kInterferenceSize = 64U
static constexpr size_t	kFirstSpinTimes = 32U

Detailed Description

Non-template base class that owns every element-type-independent piece of state.

Hosts the cache-line aligned head_ / tail_ cursors, the optional condition variables, the quit flag, the shared capacity and the void* slot for the Chunk array storage. The element type T – including the Chunk struct and the move / destroy plumbing – lives in MpmcQueue<T>, which accesses slots via a typed cast of chunk_storage_.

Member Enumeration Documentation

Behavior

enum vlink::MpmcQueueBase::Behavior : uint8_t

Per-call notification behaviour selector.

Selected via the BehaviorT template argument to emplace / push / pop and the try_* variants. Use kConditionBehavior whenever consumers or producers may block on wait_not_empty / wait_not_full; otherwise the cv notifications are pure overhead.

Enumerator
kNoBehavior
kConditionBehavior

Constructor & Destructor Documentation

MpmcQueueBase()

vlink::MpmcQueueBase::MpmcQueueBase ( size_t  capacity )

explicitprotected

~MpmcQueueBase()

vlink::MpmcQueueBase::~MpmcQueueBase ( )

protecteddefaultnoexcept

Member Function Documentation

capacity()

size_t vlink::MpmcQueueBase::capacity ( ) const

noexcept

Returns the fixed capacity chosen at construction.

Returns

Slot count (always >= 1).

empty()

bool vlink::MpmcQueueBase::empty ( bool  real = false ) const

noexcept

Returns true when the queue appears empty.

Parameters

real	Pass true to use the retrying size variant.

Returns

true when no elements are currently enqueued (approximately).

idx()

constexpr size_t vlink::MpmcQueueBase::idx ( size_t  i ) const

inlineconstexprprotectednoexcept

is_full()

bool vlink::MpmcQueueBase::is_full ( bool  real = false ) const

noexcept

Returns true when the queue appears full.

Parameters

real	Pass true to use the retrying size variant.

Returns

true when the queue is at or above capacity.

notify_to_quit()

void vlink::MpmcQueueBase::notify_to_quit ( )

noexcept

Signals graceful shutdown to every waiter and rejects further pushes.

Sets the internal quit flag with release ordering and broadcasts both condition variables. Existing wait_not_empty / wait_not_full calls return false; subsequent emplace / push silently drop their payload; try_pop returns false without touching the output. Safe to call multiple times.

size()

size_t vlink::MpmcQueueBase::size ( bool  real = false ) const

noexcept

Returns an approximate count of currently enqueued elements.

Computes head_ - tail_ using acquire loads of both cursors; concurrent updates may produce a slightly stale value. real == true retries up to 50 times until the tail_ reading is stable, at the cost of latency. The result is clamped at 0 to suppress transient head_ < tail_ wrap-arounds.

Parameters

real	When true, retries for a stable snapshot. Default: false.

Returns

Approximate number of enqueued elements.

throw_mpmc_alignment_failure()

static void vlink::MpmcQueueBase::throw_mpmc_alignment_failure ( )

staticprotected

Here is the caller graph for this function:

throw_mpmc_invalid_capacity()

static void vlink::MpmcQueueBase::throw_mpmc_invalid_capacity ( )

staticprotected

turn()

constexpr size_t vlink::MpmcQueueBase::turn ( size_t  i ) const

inlineconstexprprotectednoexcept

wait_not_empty()

bool vlink::MpmcQueueBase::wait_not_empty ( std::chrono::milliseconds  timeout = std::chrono::milliseconds(0) )

noexcept

Blocks until the queue is non-empty or timeout elapses.

Fast path: returns immediately when empty(true) is false. Slow path: waits on cv_not_empty until a producer publishes under kConditionBehavior or notify_to_quit fires.

Parameters

timeout

Maximum wait; 0 means wait forever. Default: 0.

Returns

true when the queue became non-empty; false on timeout or quit.

wait_not_full()

bool vlink::MpmcQueueBase::wait_not_full ( std::chrono::milliseconds  timeout = std::chrono::milliseconds(0) )

noexcept

Blocks until the queue has free space or timeout elapses.

Mirror of wait_not_empty for producers; waits on cv_not_full.

Parameters

timeout

Maximum wait; 0 means wait forever. Default: 0.

Returns

true when space became available; false on timeout or quit.

Member Data Documentation

capacity_

size_t vlink::MpmcQueueBase::capacity_ {0}

protected

chunk_storage_

void* vlink::MpmcQueueBase::chunk_storage_ {nullptr}

protected

cv_mtx_

std::mutex vlink::MpmcQueueBase::cv_mtx_

mutableprotected

cv_not_empty_

ConditionVariable vlink::MpmcQueueBase::cv_not_empty_

protected

cv_not_full_

ConditionVariable vlink::MpmcQueueBase::cv_not_full_

protected

head_

std::atomic<size_t> vlink::MpmcQueueBase::head_ {0U}

protected

kFirstSpinTimes

constexpr size_t vlink::MpmcQueueBase::kFirstSpinTimes = 32U

staticconstexprprotected

kInterferenceSize

constexpr size_t vlink::MpmcQueueBase::kInterferenceSize = 64U

staticconstexprprotected

kMemoryOrderAcquire

constexpr std::memory_order vlink::MpmcQueueBase::kMemoryOrderAcquire = std::memory_order_acquire

staticconstexprprotected

kMemoryOrderRelaxed

constexpr std::memory_order vlink::MpmcQueueBase::kMemoryOrderRelaxed = std::memory_order_relaxed

staticconstexprprotected

kMemoryOrderRelease

constexpr std::memory_order vlink::MpmcQueueBase::kMemoryOrderRelease = std::memory_order_release

staticconstexprprotected

quit_flag_

struct vlink::MpmcQueueBase::QuitFlag vlink::MpmcQueueBase::quit_flag_

protected

tail_

std::atomic<size_t> vlink::MpmcQueueBase::tail_ {0U}

protected

---

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

• include/vlink/base/mpmc_queue.h