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

1. Heap Architecture: Utilizes a binary heap stored in a flat list to achieve O(log n) efficiency for both add and removeFirst.
2. Metabolic Ingestion: The add method uses "Bubble Up" logic to move new elements to their correct rank in the hierarchy.
3. Metabolic Extraction: The removeFirst method extracts the root, replaces it with the last leaf, and "Bubbles Down" to restore order.
4. 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.

See Also:

• AsyncPriorityQueue: For thread-safe, locked access to this structure.
• QueueList: For standard FIFO/LIFO arrival-based sequencing.
• Receptor: The primary consumer of prioritized signal buffers.