Fixed-capacity lock-free MPMC ring buffer over T. More...

#include <mpmc_queue.h>

Inheritance diagram for vlink::MpmcQueue< T >:

Collaboration diagram for vlink::MpmcQueue< T >:

Public Member Functions
	MpmcQueue (size_t capacity) VLINK_NO_INSTRUMENT
	Constructs a queue with the given fixed capacity. More...

	~MpmcQueue () noexcept VLINK_NO_INSTRUMENT
	Destructor; destroys still-occupied slots and releases the chunk array. More...

template<Behavior BehaviorT = kNoBehavior, typename... Args>
void	emplace (Args &&... args) noexcept VLINK_NO_INSTRUMENT
	In-place constructs an element and blocks until a slot is available. More...

template<Behavior BehaviorT = kNoBehavior, typename... Args>
bool	try_emplace (Args &&... args) noexcept VLINK_NO_INSTRUMENT
	Non-blocking in-place construction. More...

template<Behavior BehaviorT = kNoBehavior, typename P >
void	push (P &&v) noexcept VLINK_NO_INSTRUMENT
	Pushes a perfect-forwarded value, blocking until a slot is available. More...

template<Behavior BehaviorT = kNoBehavior, typename P >
bool	try_push (P &&v) noexcept VLINK_NO_INSTRUMENT
	Non-blocking push wrapper around `try_emplace`. More...

template<Behavior BehaviorT = kNoBehavior>
void	pop (T &v) noexcept VLINK_NO_INSTRUMENT
	Pops a value by move; blocks until an element is available. More...

template<Behavior BehaviorT = kNoBehavior>
bool	try_pop (T &v) noexcept VLINK_NO_INSTRUMENT
	Non-blocking pop; returns `false` when the queue is empty. More...

Public Member Functions inherited from vlink::MpmcQueueBase
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...

Additional Inherited Members
Public Types inherited from vlink::MpmcQueueBase
enum	Behavior : uint8_t { kNoBehavior = 0 , kConditionBehavior = 1 }
	Per-call notification behaviour selector. More...

Protected Member Functions inherited from vlink::MpmcQueueBase
	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 inherited from vlink::MpmcQueueBase
static void	throw_mpmc_invalid_capacity ()

static void	throw_mpmc_alignment_failure ()

Protected Attributes inherited from vlink::MpmcQueueBase
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 inherited from vlink::MpmcQueueBase
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

template<typename T>
class vlink::MpmcQueue< T >

Fixed-capacity lock-free MPMC ring buffer over T.

Allocates capacity + 1 cache-line-aligned slots, validates alignment, and provides per-slot turn counters for non-blocking enqueue / dequeue. Element type must be movable.

Template Parameters

T	Element type stored in each slot.

Constructor & Destructor Documentation

◆ MpmcQueue()

template<typename T >

vlink::MpmcQueue< T >::MpmcQueue ( size_t capacity )

inlineexplicit

Constructs a queue with the given fixed capacity.

Details.

Allocates capacity + 1 slots via the aligned allocator (extra trailing guard slot keeps index arithmetic simple). Validates that the allocation is aligned to kInterferenceSize bytes; misaligned allocations throw std::bad_alloc. Each slot's turn counter is default-initialised to zero.

Parameters

capacity Maximum number of elements; must be >= 1.

Exceptions

std::invalid_argument	when `capacity` is below `1`.
std::bad_alloc	when allocation fails or returns a misaligned pointer.

Here is the call graph for this function:

◆ ~MpmcQueue()

template<typename T >

vlink::MpmcQueue< T >::~MpmcQueue

inlinenoexcept

Destructor; destroys still-occupied slots and releases the chunk array.

Not thread-safe with concurrent producers or consumers; the caller must quiesce the queue before destruction.

Member Function Documentation

◆ emplace()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT, typename... Args>

void vlink::MpmcQueue< T >::emplace ( Args &&... args )

inlinenoexcept

In-place constructs an element and blocks until a slot is available.

Claims the next slot via head_.fetch_add and spins on the turn counter until the slot is empty. When BehaviorT is kConditionBehavior the producer first awaits free space via wait_not_full and notifies one wait_not_empty waiter after publishing. Returns silently when notify_to_quit is observed.

Template Parameters

BehaviorT	Notification behaviour. Default: `kNoBehavior`.
Args	Constructor argument types forwarded to `T`.

Parameters

args	Arguments forwarded to `T` 's constructor.

Here is the call graph for this function:

◆ pop()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT>

void vlink::MpmcQueue< T >::pop ( T & v )

inlinenoexcept

Pops a value by move; blocks until an element is available.

Claims the next slot via tail_.fetch_add, spins until the slot is full, moves the value into v and republishes the slot as empty. When BehaviorT is kConditionBehavior a wait_not_full waiter is notified. Returns without altering v when notify_to_quit is observed mid-wait.

Template Parameters

BehaviorT Notification behaviour. Default: kNoBehavior.

Parameters

v	Destination assigned via `std::move`.

Here is the call graph for this function:

◆ push()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT, typename P >

void vlink::MpmcQueue< T >::push ( P && v )

inlinenoexcept

Pushes a perfect-forwarded value, blocking until a slot is available.

Wrapper around emplace<BehaviorT>(std::forward<P>(v)).

Template Parameters

BehaviorT	Notification behaviour. Default: `kNoBehavior`.
P	Value type accepted by `T` 's constructor.

Parameters

v	Value to push.

◆ try_emplace()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT, typename... Args>

bool vlink::MpmcQueue< T >::try_emplace ( Args &&... args )

inlinenoexcept

Non-blocking in-place construction.

Reads head_, attempts a CAS to claim the slot and retries when the head moves; returns false when the queue is full or notify_to_quit has been observed. On success publishes the slot and, when BehaviorT is kConditionBehavior, notifies a waiter.

Template Parameters

BehaviorT	Notification behaviour. Default: `kNoBehavior`.
Args	Constructor argument types forwarded to `T`.

Parameters

args	Arguments forwarded to `T` 's constructor.

Returns: true on successful enqueue; false on full queue or quit.

◆ try_pop()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT>

bool vlink::MpmcQueue< T >::try_pop ( T & v )

inlinenoexcept

Non-blocking pop; returns false when the queue is empty.

Uses CAS retry on tail_; v is untouched on failure.

Template Parameters

BehaviorT Notification behaviour. Default: kNoBehavior.

Parameters

v	Destination assigned via `std::move` on success.

Returns: true on successful pop; false on empty or quit.

◆ try_push()

template<typename T >

template<typename MpmcQueue< T >::Behavior BehaviorT, typename P >

bool vlink::MpmcQueue< T >::try_push ( P && v )

inlinenoexcept

Non-blocking push wrapper around try_emplace.

Template Parameters

BehaviorT	Notification behaviour. Default: `kNoBehavior`.
P	Value type accepted by `T` 's constructor.

Parameters

v	Value to push.

Returns: true on successful enqueue; false on full queue or quit.

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

include/vlink/base/mpmc_queue.h

Public Member Functions

Additional Inherited Members

Detailed Description

template<typename T> class vlink::MpmcQueue< T >

Constructor & Destructor Documentation

◆ MpmcQueue()

◆ ~MpmcQueue()

Member Function Documentation

◆ emplace()

◆ pop()

◆ push()

◆ try_emplace()

◆ try_pop()

◆ try_push()

template<typename T>
class vlink::MpmcQueue< T >