Struct PriorityQueue 

pub struct PriorityQueue { /* private fields */ }

Priority-based download queue

Manages concurrent download slots with priority ordering. Higher priority downloads are started before lower priority ones, with FIFO ordering within the same priority level.

Implementations

impl PriorityQueue

pub fn new(max_concurrent: usize) -> Arc<Self>

Create a new priority queue with the given concurrency limit

pub async fn acquire( self: &Arc<Self>, id: DownloadId, priority: DownloadPriority, ) -> PriorityPermit

Acquire a permit for the download to proceed (blocking).

This method adds the download to the waiting queue and blocks until:

1. A slot becomes available, AND
2. This download is the highest priority in the waiting queue

The download remains in the queue until a permit is granted, ensuring fair ordering based on priority and arrival time (FIFO within same priority).

Difference from try_acquire

• acquire: Adds to queue, waits for turn, guarantees eventual permit
• try_acquire: Does NOT add to queue, immediate success or failure

Use acquire for downloads that should wait their turn. Use try_acquire for opportunistic slot acquisition (e.g., resuming paused downloads).

pub fn try_acquire( self: &Arc<Self>, id: DownloadId, priority: DownloadPriority, ) -> Option<PriorityPermit>

Try to acquire a permit immediately without waiting (non-blocking).

This method does NOT add the download to the waiting queue. It either succeeds immediately or returns None.

Returns None if:

• No slot is currently available, OR
• Higher priority downloads are already waiting in the queue

Difference from acquire

• try_acquire: Does NOT add to queue, immediate success or failure
• acquire: Adds to queue, waits for turn, guarantees eventual permit

Use Cases

• Opportunistic slot acquisition (e.g., checking if a paused download can resume)
• Avoiding queue position for downloads that shouldn’t block others
• Non-async contexts where blocking is not possible

Warning

If you call try_acquire and it fails, the download is NOT queued. You must call acquire if you want the download to wait for a slot.

pub fn set_priority( &self, id: DownloadId, new_priority: DownloadPriority, ) -> bool

Update the priority of a waiting download

If the download is already active, this has no effect on scheduling. Returns true if the priority was updated.

pub fn remove(&self, id: DownloadId)

Remove a download from the waiting queue

Call this if a download is cancelled before acquiring a permit.

pub fn get_priority(&self, id: DownloadId) -> Option<DownloadPriority>

Get the priority of a download (waiting or active)

pub fn active_count(&self) -> usize

Get the number of active downloads

pub fn waiting_count(&self) -> usize

Get the number of waiting downloads

pub fn queue_position(&self, id: DownloadId) -> Option<usize>

Get the position in queue for a waiting download (1-indexed, None if not waiting)

pub fn stats(&self) -> PriorityQueueStats

Get statistics about the queue