A thread-safe, priority-based queue that maintains insertion order for equal priorities.
More...
#include <dfx-utilities/sync-queues/PriorityStableQueue.hpp>
|
|
using | value_type = T |
|
using | size_type = std::size_t |
|
using | difference_type = std::ptrdiff_t |
|
using | reference = value_type & |
|
using | const_reference = value_type const & |
|
using | pointer = value_type * |
|
using | const_pointer = value_type const * |
|
| | PriorityStableQueue ()=default |
| | Default constructor.
|
|
| DFX_DISABLE_COPY_AND_MOVE (PriorityStableQueue) |
| void | push (T item, int priority=0) |
| | Pushes a single value into the queue.
|
| void | pushRange (std::span< T > items, int priority=0) |
| | Pushes a range of values into the queue with a shared priority.
|
template<typename Mapper>
requires PriorityMapper<Mapper, T> |
| void | pushRange (std::span< T > items, Mapper &&priorityMapper) |
| | Pushes a range of values where each has a calculated priority.
|
| std::optional< T > | pop (std::stop_token stopToken={}) |
| | Removes and returns the highest priority element (blocking).
|
| std::optional< T > | tryPop () |
| | Attempts to remove and return the highest priority element (non-blocking).
|
| std::vector< T > | drain () |
| | Removes all elements from the queue and returns them in priority order.
|
| void | clear () |
| | Removes all elements from the queue.
|
| bool | empty () const |
| | Checks if the queue is empty.
|
| size_type | size () const |
| | Returns the current number of elements in the queue.
|
template<typename T>
class dfx::Utils::PriorityStableQueue< T >
A thread-safe, priority-based queue that maintains insertion order for equal priorities.
The PriorityStableQueue provides a concurrent container where elements are ordered primarily by an integer priority (higher values first) and secondarily by their insertion order (FIFO) for items sharing the same priority level.
- Template Parameters
-
| T | The type of elements stored in the queue. |
- Note
- This class is thread-safe. All public member functions lock an internal mutex.
-
As this is a concurrent container intended for producer-consumer patterns, it does not expose iterators to prevent data races during traversal.
◆ PriorityStableQueue()
◆ clear()
Removes all elements from the queue.
◆ drain()
Removes all elements from the queue and returns them in priority order.
This operation is atomic and thread-safe. The returned vector contains all items sorted by priority.
- Returns
- std::vector<T> All elements previously in the queue.
◆ empty()
Checks if the queue is empty.
- Returns
- true if the queue contains no elements, false otherwise.
- Note
- In a concurrent environment, the result may be outdated by the time it is returned.
◆ pop()
Removes and returns the highest priority element (blocking).
This operation blocks the calling thread if the queue is empty. The wait can be interrupted by the provided stopToken.
- Parameters
-
| stopToken | A token used to interrupt the waiting process (e.g., during shutdown). |
- Returns
- std::optional<T> The highest priority element, or std::nullopt if the stopToken was triggered before an item could be retrieved.
◆ push()
Pushes a single value into the queue.
- Parameters
-
| item | The item to move into the queue. |
| priority | The priority level. Higher values are dequeued first. Defaults to 0. |
◆ pushRange() [1/2]
Pushes a range of values into the queue with a shared priority.
This is the most efficient way to enqueue multiple items. It acquires the lock once and notifies waiting threads once.
- Parameters
-
| items | Span of items to move into the queue. |
| priority | The priority assigned to every item in this batch. |
◆ pushRange() [2/2]
template<typename T>
requires PriorityMapper<Mapper, T>
template<typename Mapper>
requires PriorityMapper<Mapper, T>
Pushes a range of values where each has a calculated priority.
This is useful when the priority is a member of the task or calculated via a logic-specific rule.
- Template Parameters
-
| Mapper | A callable type with signature int(const T&) or int(T). |
- Parameters
-
| items | A span of values to move into the queue. |
| priorityMapper | A function/lambda to determine the priority of each item. |
◆ size()
Returns the current number of elements in the queue.
- Returns
- std::size_t The number of elements.
◆ tryPop()
Attempts to remove and return the highest priority element (non-blocking).
- Returns
- std::optional<T> Contains the element if the queue was not empty; otherwise, returns std::nullopt immediately.
The documentation for this class was generated from the following file:
1.14.0