quicr::SafeQueue< T > Class Template Reference

Thread-safe FIFO queue with optional bounded, drop-oldest insertion. More...

#include <safe_queue.h>

Public Member Functions
	SafeQueue (uint32_t limit=5 '000)
	Constructs an empty queue. More...
	~SafeQueue ()
	Wakes current waiters before destroying the queue; callers must ensure no operation remains active. More...
bool	Push (T const &elem)
	Copies an element to the back of the queue. More...
bool	Push (T &&elem)
	Moves an element to the back, evicting the oldest element when at a nonzero limit. More...
std::optional< T >	Pop ()
	Remove the first object from queue (oldest object) More...
std::optional< T >	Front ()
	Get first object without removing from queue. More...
void	PopFront ()
	Removes the oldest object, or does nothing when empty. More...
std::optional< T >	BlockPop ()
	Block waiting for data in queue, then remove the first object from queue (oldest object) More...
size_t	Size ()
	Size of the queue. More...
void	Clear ()
	Removes all elements without changing the limit or stopped-waiting state. More...
bool	Empty () const
	Check if queue is empty. More...
void	StopWaiting ()
	Permanently causes current and future BlockPop() calls to return without waiting. More...
void	SetLimit (uint32_t limit)
	Changes the maximum retained element count. More...

Detailed Description

template<typename T>
class quicr::SafeQueue< T >

Thread-safe FIFO queue with optional bounded, drop-oldest insertion.

All queue mutations and value access are serialized by an internal mutex. Empty() is a lock-free atomic snapshot and may be stale immediately after it returns. Waiting can be permanently disabled with StopWaiting().

Template Parameters

T	Stored value type.

Constructor & Destructor Documentation

SafeQueue()

template<typename T >

quicr::SafeQueue< T >::SafeQueue ( uint32_t  limit = 5'000 )

inline

Constructs an empty queue.

Parameters

limit

Maximum retained element count; zero means unlimited. Insertion never blocks.

~SafeQueue()

template<typename T >

quicr::SafeQueue< T >::~SafeQueue ( )

inline

Wakes current waiters before destroying the queue; callers must ensure no operation remains active.

Member Function Documentation

BlockPop()

template<typename T >

std::optional<T> quicr::SafeQueue< T >::BlockPop ( )

inline

Block waiting for data in queue, then remove the first object from queue (oldest object)

Waits until an element is available or StopWaiting() is called. The predicate is checked while holding the queue mutex, so spurious wakeups do not produce an empty result.

Returns

std::nullopt after waiting is stopped; otherwise a copy of and removal of the oldest value.

Exceptions

Any	exception thrown while copying T.

Clear()

template<typename T >

void quicr::SafeQueue< T >::Clear ( )

inline

Removes all elements without changing the limit or stopped-waiting state.

Note

This does not wake a thread waiting in BlockPop().

Empty()

template<typename T >

bool quicr::SafeQueue< T >::Empty ( ) const

inline

Check if queue is empty.

Returns

Atomic snapshot of whether the queue is empty.

Front()

template<typename T >

std::optional<T> quicr::SafeQueue< T >::Front ( )

inline

Get first object without removing from queue.

Returns

std::nullopt if empty; otherwise a copy of the oldest value. The queue is unchanged.

Exceptions

Any	exception thrown while copying T.

Pop()

template<typename T >

std::optional<T> quicr::SafeQueue< T >::Pop ( )

inline

Remove the first object from queue (oldest object)

Returns

std::nullopt if empty; otherwise a copy of the removed value.

Exceptions

Any	exception thrown while copying T.

PopFront()

template<typename T >

void quicr::SafeQueue< T >::PopFront ( )

inline

Removes the oldest object, or does nothing when empty.

Push() [1/2]

template<typename T >

bool quicr::SafeQueue< T >::Push ( T &&  elem )

inline

Moves an element to the back, evicting the oldest element when at a nonzero limit.

Parameters

elem	Element to move into the queue.

Returns

true if no element was evicted; false if insertion evicted the oldest element.

Exceptions

Any	exception thrown while moving or allocating storage for T.

Push() [2/2]

template<typename T >

bool quicr::SafeQueue< T >::Push ( T const &  elem )

inline

Copies an element to the back of the queue.

If the configured nonzero limit has already been reached, the oldest element is discarded and the new element is still inserted. The call never waits for capacity.

Parameters

elem	The element to insert.

Returns

true if no element was evicted; false if the oldest element was evicted to make room.

Exceptions

Any	exception thrown while copying or allocating storage for T.

SetLimit()

template<typename T >

void quicr::SafeQueue< T >::SetLimit ( uint32_t  limit )

inline

Changes the maximum retained element count.

Parameters

limit

New limit; zero means unlimited.

Note

Existing elements are not removed when lowering the limit. A later insertion evicts at most one oldest element, so the queue can remain above the new limit until enough insertions or removals occur.

Size()

template<typename T >

size_t quicr::SafeQueue< T >::Size ( )

inline

Size of the queue.

Returns

Number of retained elements at the instant the mutex is held.

StopWaiting()

template<typename T >

void quicr::SafeQueue< T >::StopWaiting ( )

inline

Permanently causes current and future BlockPop() calls to return without waiting.

Wakes all current waiters. It does not clear the queue and does not prevent later insertions.

---

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

• include/quicr/containers/safe_queue.h