Struct CancellableQueue 

pub struct CancellableQueue<T> { /* private fields */ }

A lock-free queue that supports active cancellation via sweeping.

Unlike mpsc channels where cancellation can only be checked at dequeue time, this queue allows a dedicated sweeper task to iterate through queued items and remove those belonging to cancelled transfers. This ensures that ImmutableBlock guards are dropped promptly when a transfer is cancelled.

Architecture

Producer ──► [SegQueue] ◄── Consumer
                 ▲
                 │
            [Sweeper Task]
                 │
           (removes cancelled items)

Implementations

impl<T> CancellableQueue<T>

pub fn new() -> Self

Create a new cancellable queue.

pub fn push(&self, transfer_id: TransferId, data: T) -> bool

Push an item onto the queue.

If the transfer has already been cancelled, the item is dropped immediately. Returns true if the item was queued, false if it was dropped due to cancellation.

pub async fn notified(&self)

Wait until a producer pushes new work or cancellation changes.

pub fn pop(&self) -> Option<QueueItem<T>>

Pop an item from the queue.

Returns None if the queue is empty. Items from cancelled transfers may still be returned - use pop_valid() if you want to skip cancelled items automatically.

pub fn pop_valid(&self) -> Option<QueueItem<T>>

Pop a valid (non-cancelled) item from the queue.

Skips and drops items belonging to cancelled transfers. Returns None if no valid items are available.

pub fn mark_cancelled(&self, transfer_id: TransferId)

Mark a transfer as cancelled.

Items belonging to this transfer will be:

• Dropped immediately if pushed after this call
• Removed by the sweeper task if already in the queue
• Skipped by pop_valid() if dequeued

pub fn is_cancelled(&self, transfer_id: TransferId) -> bool

Check if a transfer has been cancelled.

pub fn sweep(&self) -> usize

Remove cancelled items from the queue.

This is called by the sweeper task to actively remove items from cancelled transfers, ensuring their resources (like ImmutableBlock guards) are released promptly.

Returns the number of items removed.

Implementation Note

This performs a full drain-and-requeue operation. While not ideal for very large queues, it ensures correctness with the lock-free SegQueue. For typical offload workloads (batches of 64-256 blocks), this is efficient.

pub fn clear_cancelled(&self, transfer_id: TransferId)

Clear the cancelled set for a specific transfer.

Called when a transfer is fully complete to clean up the cancelled set.

pub fn len_approx(&self) -> usize

Get the approximate queue length.

This is not exact due to concurrent modifications but useful for monitoring.

pub fn is_empty_approx(&self) -> bool

Check if the queue is approximately empty.

pub fn cancelled_count(&self) -> usize

Get the number of cancelled transfers being tracked.

Trait Implementations

impl<T> Default for CancellableQueue<T>

fn default() -> Self

Returns the “default value” for a type.