API referenceC++ APIHoloscanClasses

holoscan::OrderedQueue

Beta
View as Markdown
template <typename T>
class OrderedQueue

Ordered queue implementation using mutex-protected std::queue.

This queue uses a mutex to serialize all operations, ensuring both thread-safety and strict global FIFO ordering across all producers and the single consumer.

Thread Safety:

  • Fully thread-safe for concurrent enqueue and dequeue operations
  • Uses a mutex to serialize access (blocking if contended)
  • Safe to call from multiple producer threads and a single consumer thread simultaneously

Ordering Guarantees:

  • Maintains strict global FIFO order across ALL producers
  • Items are dequeued in the exact order they were enqueued
  • Guaranteed temporal ordering regardless of which thread enqueued the item

Performance Characteristics:

  • Lower throughput than lock-free queues under high contention
  • Predictable latency (no worst-case scenarios from lock-free algorithms)
  • size_approx() returns the exact size (not approximate, despite the name)
  • Capacity is a strict limit (will reject enqueue when full)
  • Mutex is held during the entire move operation: if T has expensive move semantics (beyond simple pointer swaps), this may increase contention under heavy load
  • Best suited for scenarios where ordering is critical and producer contention is moderate
#include <holoscan/data_logger_queue.hpp>

Template parameters

T
typename

The type of elements stored in the queue

Inherits from: holoscan::DataLoggerQueue< T > (public)

Constructors

OrderedQueue

holoscan::OrderedQueue<T>::OrderedQueue(
    size_t capacity
)

Construct an ordered queue with the specified capacity.

Parameters

capacity
size_t

The maximum capacity (strict limit, unlike ConcurrentQueue)

Methods

try_enqueue

bool holoscan::OrderedQueue<T>::try_enqueue(
    T &&item
) override

Attempt to enqueue an item (thread-safe).

Returns: true if successfully enqueued, false if queue is full

Parameters

item
T &&

The item to enqueue (will be moved)

try_dequeue

bool holoscan::OrderedQueue<T>::try_dequeue(
    T &item
) override

Dequeue an item from the queue.

Without this pattern, the naive item = std::move(queue_.front()) would destroy the old item value inside the mutex, causing deadlock: [Queue Mutex] → [GIL] → [Thread Join].

Trade-off: One extra move for movable types, one extra copy for copy-only types.

Uses std::optional to defer destruction of the output parameter’s previous value until after the mutex is released. This prevents deadlock when T’s destructor acquires other locks (e.g., GILGuardedPyObject acquiring the Python GIL).

Returns: true if an item was dequeued, false if queue was empty

Parameters

item
T &

Output parameter. Its destructor runs outside the critical section.

size_approx

size_t holoscan::OrderedQueue<T>::size_approx() const override

Get size of the queue (thread-safe).

Note: The accuracy of this value depends on the implementation:

  • LockFreeQueue: Returns an approximation that may be stale by the time it’s returned
  • OrderedQueue: Returns the exact size at the moment the mutex was acquired

Returns: Number of items in the queue (approximation or exact, depending on implementation)

Member variables

NameTypeDescription
queue_std::queue< T >
mutex_std::mutex
capacity_const size_t