PriorityQueue<E> class

A collection of elements that maintains a Deterministic Priority Order, serving as a specialized Ranked Execution Buffer for the reactive fabric.

Unlike standard FIFO queues, the PriorityQueue prioritizes Operational Precedence over arrival sequence. It ensures that elements with the highest priority (defined by a comparator or Comparable implementation) are always positioned for immediate extraction, facilitating efficient handling of weighted signals.

When to use

Signal Prioritization: Ensuring administrative pulses or system commands jump the queue ahead of standard state updates.
Task Scheduling: Orchestrating reactive waves where "urgency" (e.g., security validation) outranks "arrival time".
Resource Management: Processing high-contention elements first to minimize graph stabilization latency.

How it works

Heap Architecture: Utilizes a binary heap stored in a flat list to achieve O(log n) efficiency for both add and removeFirst.
Metabolic Ingestion: The add method uses "Bubble Up" logic to move new elements to their correct rank in the hierarchy.
Metabolic Extraction: The removeFirst method extracts the root, replaces it with the last leaf, and "Bubbles Down" to restore order.
Structural Reconstruction: Methods like removeWhere perform a full O(n) Re-heapification to maintain integrity after bulk changes.

Non‑obvious

Traversal Order: The iterator and forEach methods traverse the internal heap list, which does not guarantee priority order. Use removeFirst sequentially if ranked traversal is required.
Removal Penalty: Removing arbitrary elements via remove or removeWhere is significantly more expensive than removeFirst due to the required structural repair.
Comparison Strategy: If no custom comparator is provided, elements must implement Comparable<E>, or a TypeError will occur during insertion.
Non-Thread Safety: This class is a "somatic" (synchronous) component. For cross-thread synchronization, wrap it in AsyncPriorityQueue.

Example

// Create a queue where lower numbers have higher priority
final taskBuffer = PriorityQueue<int>((a, b) => a.compareTo(b));

taskBuffer.addAll([50, 10, 100, 5]);

// Extraction always yields the highest priority (lowest number)
print(taskBuffer.removeFirst()); // Output: 5
print(taskBuffer.removeFirst()); // Output: 10

Type Parameters:

E: The type of elements held in the buffer. Must be Comparable if no comparator is provided.

Constructors

PriorityQueue([int comparison(E, E)?]): Creates a PriorityQueue with an optional custom comparison logic.

Properties

first → E: Retrieves the highest-priority element without removing it.
no setteroverride
firstOrNull → T?: Available on Iterable<T>, provided by the IterableExtensions extension
The first element of this iterator, or null if the iterable is empty.
no setter
hashCode → int: The hash code for this object.
no setterinherited
indexed → Iterable<(int, T)>: Available on Iterable<T>, provided by the IterableExtensions extension
Pairs of elements of the indices and elements of this iterable.
no setter
isEmpty → bool: Whether this collection has no elements.
no setteroverride
isNotEmpty → bool: Whether this collection has at least one element.
no setteroverride
iterator → Iterator<E>: A new Iterator that allows iterating the elements of this Iterable.
no setteroverride
last → E: The last element.
no setteroverride
lastOrNull → T?: Available on Iterable<T>, provided by the IterableExtensions extension
The last element of this iterable, or null if the iterable is empty.
no setter
length → int: The number of elements in this Iterable.
no setteroverride
nonNulls → Iterable<T>: Available on Iterable<T?>, provided by the NullableIterableExtensions extension
The non-null elements of this iterable.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
single → E: Checks that this iterable has only one element, and returns that element.
no setterinherited
singleOrNull → T?: Available on Iterable<T>, provided by the IterableExtensions extension
The single element of this iterator, or null.
no setter
toJSIterable → JSIterable<T>: Available on Iterable<T>, provided by the IterableToJSIterable extension
A JSIterable wrapper that proxies to the Dart iterable API.
no setter
wait → Future<List<T>>: Available on Iterable<Future<T>>, provided by the FutureIterable extension
Waits for futures in parallel.
no setter

Methods

add(E element) → void: Ingests a new element into the metabolic hierarchy.
addAll(Iterable<E> iterable) → void
addFirst(E value) → void
addLast(E value) → void
any(bool test(E element)) → bool: Checks whether any element of this iterable satisfies test.
inherited
asNameMap() → Map<String, T>: Available on Iterable<T>, provided by the EnumByName extension
Creates a map from the names of enum values to the values.
attach(dynamic context) → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Returns a new collection of pulses, each with the provided context metadata attached.
batch() → Pulse: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Aggregates multiple signals into a single, flat CollectivePulse.
byName(String name) → T: Available on Iterable<T>, provided by the EnumByName extension
Finds the enum value in this list with name name.
cast<R>() → Iterable<T>: A view of this iterable as an iterable of R instances.
inherited
clear() → void
contains(Object? element) → bool: Whether the collection contains an element equal to element.
inherited
elementAt(int index) → E: Returns the indexth element.
inherited
elementAtOrNull(int index) → T?: Available on Iterable<T>, provided by the IterableExtensions extension
The element at position index of this iterable, or null.
every(bool test(E element)) → bool: Checks whether every element of this iterable satisfies test.
inherited
expand<T>(Iterable<T> toElements(E element)) → Iterable<T>: Expands each element of this Iterable into zero or more elements.
inherited
firstWhere(bool test(E element), {E orElse()?}) → E: The first element that satisfies the given predicate test.
inherited
flatten() → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Recursively flattens any nested CollectivePulse structures into a sequence of simple pulses.
fold<T>(T initialValue, T combine(T previousValue, E element)) → T: Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
inherited
followedBy(Iterable<E> other) → Iterable<E>: Creates the lazy concatenation of this iterable and other.
inherited
forEach(void action(E element)) → void: Invokes action on each element of this iterable in iteration order.
inherited
join([String separator = ""]) → String: Converts each element to a String and concatenates the strings.
inherited
lastWhere(bool test(E element), {E orElse()?}) → E: The last element that satisfies the given predicate test.
inherited
map<T>(T toElement(E e)) → Iterable<T>: The current elements of this iterable modified by toElement.
inherited
mapEach<T>(T mapper(dynamic payload)) → Iterable<Pulse<T>>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Transforms the payload of every pulse in the collection while preserving their individual causal traces.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
reduce(E combine(E value, E element)) → E: Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
inherited
remove(Object? value) → bool
removeFirst() → E: Extracts the element with the highest genotypic precedence.
removeLast() → E
removeWhere(bool test(E element)) → void: Removes all elements from the hierarchy that satisfy the test predicate.
retainWhere(bool test(E element)) → void: Removes all elements from the hierarchy that fail to satisfy the test predicate.
singleWhere(bool test(E element), {E orElse()?}) → E: The single element that satisfies test.
inherited
skip(int count) → Iterable<E>: Creates an Iterable that provides all but the first count elements.
inherited
skipWhile(bool test(E element)) → Iterable<E>: Creates an Iterable that skips leading elements while test is satisfied.
inherited
take(int count) → Iterable<E>: Creates a lazy iterable of the count first elements of this iterable.
inherited
takeWhile(bool test(E element)) → Iterable<E>: Creates a lazy iterable of the leading elements satisfying test.
inherited
toList({bool growable = true}) → List<E>: Creates a List containing the elements of this Iterable.
inherited
toSet() → Set<E>: Creates a Set containing the same elements as this iterable.
inherited
toString() → String: Returns a string representation of (some of) the elements of this.
inherited
where(bool test(E element)) → Iterable<E>: Creates a new lazy Iterable with all elements that satisfy the predicate test.
inherited
whereType<T>() → Iterable<T>: Creates a new lazy Iterable with all elements that have type T.
inherited
withStep(String step) → Iterable<Pulse>: Available on Iterable<Pulse>, provided by the PulseIterableExtension extension
Appends a diagnostic stage to the causal trace of every pulse in this collection.

Operators

operator ==(Object other) → bool: The equality operator.
inherited