use std::collections::HashSet;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Instant;
use tokio::sync::{Notify, mpsc};
#[cfg(all(feature = "metalink", feature = "bittorrent"))]
use crate::engine::metalink::request_graph::MetalinkRequestGraph;
use crate::error::Aria2Error;
use crate::network::ConnectionContext;
use crate::request::request_group::{GroupId, HaltReason, RequestGroup};
pub const ENGINE_COMMAND_CAPACITY: usize = 1024;
pub const ENGINE_CONTROL_CAPACITY: usize = 512;
pub const ENGINE_TOTAL_COMMAND_CAPACITY: usize = ENGINE_COMMAND_CAPACITY + ENGINE_CONTROL_CAPACITY;
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct EngineCommandQueueSnapshot {
pub depth: usize,
pub max_depth: usize,
pub wakeups: u64,
pub dispatch_samples: u64,
pub dispatch_latency_us_total: u64,
pub dispatch_latency_us_max: u64,
}
#[derive(Debug, Default)]
struct EngineCommandQueueMetrics {
depth: AtomicUsize,
max_depth: AtomicUsize,
wakeups: AtomicU64,
dispatch_samples: AtomicU64,
dispatch_latency_us_total: AtomicU64,
dispatch_latency_us_max: AtomicU64,
}
impl EngineCommandQueueMetrics {
fn enqueued(&self) {
let previous_depth = self.depth.fetch_add(1, Ordering::Relaxed);
if previous_depth == 0 {
self.wakeups.fetch_add(1, Ordering::Relaxed);
}
let depth = previous_depth + 1;
let mut max_depth = self.max_depth.load(Ordering::Relaxed);
while depth > max_depth {
match self.max_depth.compare_exchange_weak(
max_depth,
depth,
Ordering::Relaxed,
Ordering::Relaxed,
) {
Ok(_) => break,
Err(observed) => max_depth = observed,
}
}
}
fn dequeued(&self, queued_at: Instant) {
self.depth.fetch_sub(1, Ordering::Relaxed);
let latency_us = queued_at.elapsed().as_micros().min(u64::MAX as u128) as u64;
self.dispatch_samples.fetch_add(1, Ordering::Relaxed);
self.dispatch_latency_us_total
.fetch_add(latency_us, Ordering::Relaxed);
let mut max_latency = self.dispatch_latency_us_max.load(Ordering::Relaxed);
while latency_us > max_latency {
match self.dispatch_latency_us_max.compare_exchange_weak(
max_latency,
latency_us,
Ordering::Relaxed,
Ordering::Relaxed,
) {
Ok(_) => break,
Err(observed) => max_latency = observed,
}
}
}
fn snapshot(&self) -> EngineCommandQueueSnapshot {
EngineCommandQueueSnapshot {
depth: self.depth.load(Ordering::Relaxed),
max_depth: self.max_depth.load(Ordering::Relaxed),
wakeups: self.wakeups.load(Ordering::Relaxed),
dispatch_samples: self.dispatch_samples.load(Ordering::Relaxed),
dispatch_latency_us_total: self.dispatch_latency_us_total.load(Ordering::Relaxed),
dispatch_latency_us_max: self.dispatch_latency_us_max.load(Ordering::Relaxed),
}
}
}
struct QueuedEngineCommand {
queued_at: Instant,
command: EngineCommand,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EngineCommandSendError {
Full,
Closed,
}
impl std::fmt::Display for EngineCommandSendError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Full => f.write_str("engine command queue is full"),
Self::Closed => f.write_str("engine command queue is closed"),
}
}
}
impl std::error::Error for EngineCommandSendError {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EngineCommandTryRecvError {
Empty,
Closed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum EngineCommandCoalesceKey {
Remove(GroupId),
ForceRemove(GroupId),
Pause(GroupId),
ForcePause(GroupId),
Unpause(GroupId),
PauseAll,
ForcePauseAll,
UnpauseAll,
HaltAll(HaltReason),
ForceHaltAll(HaltReason),
}
enum EngineCommandSenderBackend {
Bounded {
control_tx: mpsc::Sender<QueuedEngineCommand>,
normal_tx: mpsc::Sender<QueuedEngineCommand>,
metrics: Arc<EngineCommandQueueMetrics>,
pending_keys: Arc<Mutex<HashSet<EngineCommandCoalesceKey>>>,
wake: Arc<Notify>,
},
}
pub struct EngineCommandSender {
backend: Arc<EngineCommandSenderBackend>,
}
impl Clone for EngineCommandSender {
fn clone(&self) -> Self {
Self {
backend: Arc::clone(&self.backend),
}
}
}
pub struct EngineCommandReceiver {
backend: EngineCommandReceiverBackend,
}
enum EngineCommandReceiverBackend {
Bounded {
control_rx: mpsc::Receiver<QueuedEngineCommand>,
normal_rx: mpsc::Receiver<QueuedEngineCommand>,
metrics: Arc<EngineCommandQueueMetrics>,
pending_keys: Arc<Mutex<HashSet<EngineCommandCoalesceKey>>>,
wake: Arc<Notify>,
control_closed: bool,
normal_closed: bool,
},
}
pub fn channel() -> (EngineCommandSender, EngineCommandReceiver) {
let (control_tx, control_rx) = mpsc::channel(ENGINE_CONTROL_CAPACITY);
let (normal_tx, normal_rx) = mpsc::channel(ENGINE_COMMAND_CAPACITY);
let metrics = Arc::new(EngineCommandQueueMetrics::default());
let pending_keys = Arc::new(Mutex::new(HashSet::new()));
let wake = Arc::new(Notify::new());
(
EngineCommandSender {
backend: Arc::new(EngineCommandSenderBackend::Bounded {
control_tx,
normal_tx,
metrics: Arc::clone(&metrics),
pending_keys: Arc::clone(&pending_keys),
wake: Arc::clone(&wake),
}),
},
EngineCommandReceiver {
backend: EngineCommandReceiverBackend::Bounded {
control_rx,
normal_rx,
metrics,
pending_keys,
wake,
control_closed: false,
normal_closed: false,
},
},
)
}
impl EngineCommandSender {
pub fn send(&self, command: EngineCommand) -> Result<(), EngineCommandSendError> {
match self.backend.as_ref() {
EngineCommandSenderBackend::Bounded {
control_tx,
normal_tx,
metrics,
pending_keys,
wake,
} => {
let target = if command.is_control() {
control_tx
} else {
normal_tx
};
let coalesce_key = command.coalesce_key();
if let Some(key) = coalesce_key {
if target.is_closed() {
return Err(EngineCommandSendError::Closed);
}
let mut pending = pending_keys
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner());
if !pending.insert(key) {
return Ok(());
}
let permit = match target.try_reserve() {
Ok(permit) => permit,
Err(mpsc::error::TrySendError::Full(())) => {
pending.remove(&key);
return Err(EngineCommandSendError::Full);
}
Err(mpsc::error::TrySendError::Closed(())) => {
pending.remove(&key);
return Err(EngineCommandSendError::Closed);
}
};
metrics.enqueued();
permit.send(QueuedEngineCommand {
queued_at: Instant::now(),
command,
});
wake.notify_one();
return Ok(());
}
let permit = match target.try_reserve() {
Ok(permit) => permit,
Err(mpsc::error::TrySendError::Full(())) => {
return Err(EngineCommandSendError::Full);
}
Err(mpsc::error::TrySendError::Closed(())) => {
return Err(EngineCommandSendError::Closed);
}
};
metrics.enqueued();
permit.send(QueuedEngineCommand {
queued_at: Instant::now(),
command,
});
wake.notify_one();
Ok(())
}
}
}
pub async fn closed(&self) {
match self.backend.as_ref() {
EngineCommandSenderBackend::Bounded { normal_tx, .. } => normal_tx.closed().await,
}
}
pub fn snapshot(&self) -> EngineCommandQueueSnapshot {
match self.backend.as_ref() {
EngineCommandSenderBackend::Bounded { metrics, .. } => metrics.snapshot(),
}
}
}
impl EngineCommandReceiver {
pub fn try_recv(&mut self) -> Result<EngineCommand, EngineCommandTryRecvError> {
match &mut self.backend {
EngineCommandReceiverBackend::Bounded {
control_rx,
normal_rx,
metrics,
pending_keys,
control_closed,
normal_closed,
..
} => {
let queued = if !*control_closed {
match control_rx.try_recv() {
Ok(command) => Some(command),
Err(mpsc::error::TryRecvError::Empty) => None,
Err(mpsc::error::TryRecvError::Disconnected) => {
*control_closed = true;
None
}
}
} else {
None
};
let queued = queued.or_else(|| {
if *normal_closed {
return None;
}
match normal_rx.try_recv() {
Ok(command) => Some(command),
Err(mpsc::error::TryRecvError::Empty) => None,
Err(mpsc::error::TryRecvError::Disconnected) => {
*normal_closed = true;
None
}
}
});
if let Some(queued) = queued {
metrics.dequeued(queued.queued_at);
let command = queued.command;
if let Some(key) = command.coalesce_key() {
pending_keys
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.remove(&key);
}
Ok(command)
} else if *control_closed && *normal_closed {
Err(EngineCommandTryRecvError::Closed)
} else {
Err(EngineCommandTryRecvError::Empty)
}
}
}
}
pub async fn recv(&mut self) -> Result<EngineCommand, EngineCommandTryRecvError> {
let wake = match &self.backend {
EngineCommandReceiverBackend::Bounded { wake, .. } => Arc::clone(wake),
};
loop {
match self.try_recv() {
Ok(command) => return Ok(command),
Err(EngineCommandTryRecvError::Closed) => {
return Err(EngineCommandTryRecvError::Closed);
}
Err(EngineCommandTryRecvError::Empty) => wake.notified().await,
}
}
}
}
pub enum EngineCommand {
AddDownload {
group: Arc<std::sync::RwLock<RequestGroup>>,
},
#[cfg(all(feature = "metalink", feature = "bittorrent"))]
AddMetalinkGraph { graph: MetalinkRequestGraph },
RemoveDownload { gid: GroupId },
ForceRemoveDownload { gid: GroupId },
Pause { gid: GroupId },
ForcePause { gid: GroupId },
Unpause { gid: GroupId },
TaskCompleted { gid: GroupId, result: TaskResult },
PauseAll,
ForcePauseAll,
UnpauseAll,
HaltAll { reason: HaltReason },
ForceHaltAll { reason: HaltReason },
SetMaxConcurrent { max: u32 },
SetGlobalRateLimit {
download_limit: Option<u64>,
upload_limit: Option<u64>,
},
#[cfg(feature = "bittorrent")]
SetPublicTrackerSources { sources: String },
#[cfg(feature = "bittorrent")]
SetPublicTrackerUpdateInterval { seconds: u64 },
#[cfg(feature = "bittorrent")]
SetPublicTrackersEnabled { enabled: bool },
}
impl EngineCommand {
fn coalesce_key(&self) -> Option<EngineCommandCoalesceKey> {
match self {
Self::RemoveDownload { gid } => Some(EngineCommandCoalesceKey::Remove(*gid)),
Self::ForceRemoveDownload { gid } => Some(EngineCommandCoalesceKey::ForceRemove(*gid)),
Self::Pause { gid } => Some(EngineCommandCoalesceKey::Pause(*gid)),
Self::ForcePause { gid } => Some(EngineCommandCoalesceKey::ForcePause(*gid)),
Self::Unpause { gid } => Some(EngineCommandCoalesceKey::Unpause(*gid)),
Self::PauseAll => Some(EngineCommandCoalesceKey::PauseAll),
Self::ForcePauseAll => Some(EngineCommandCoalesceKey::ForcePauseAll),
Self::UnpauseAll => Some(EngineCommandCoalesceKey::UnpauseAll),
Self::HaltAll { reason } => Some(EngineCommandCoalesceKey::HaltAll(*reason)),
Self::ForceHaltAll { reason } => Some(EngineCommandCoalesceKey::ForceHaltAll(*reason)),
_ => None,
}
}
fn is_control(&self) -> bool {
let common = matches!(
self,
Self::RemoveDownload { .. }
| Self::ForceRemoveDownload { .. }
| Self::Pause { .. }
| Self::ForcePause { .. }
| Self::Unpause { .. }
| Self::PauseAll
| Self::ForcePauseAll
| Self::UnpauseAll
| Self::HaltAll { .. }
| Self::ForceHaltAll { .. }
| Self::SetMaxConcurrent { .. }
| Self::SetGlobalRateLimit { .. }
);
#[cfg(feature = "bittorrent")]
let common = common
|| matches!(
self,
Self::SetPublicTrackerSources { .. }
| Self::SetPublicTrackerUpdateInterval { .. }
| Self::SetPublicTrackersEnabled { .. }
);
common
}
}
#[derive(Debug)]
pub enum TaskResult {
Success,
Failed(Aria2Error),
FailedWithContext {
error: Aria2Error,
connection_context: ConnectionContext,
},
Cancelled,
}
#[cfg(test)]
mod tests {
use super::*;
use crate::request::request_group::{DownloadOptions, GroupId};
fn add_command(gid: u64) -> EngineCommand {
EngineCommand::AddDownload {
group: Arc::new(std::sync::RwLock::new(RequestGroup::new(
GroupId::new(gid),
vec![format!("http://example.com/{gid}.bin")],
DownloadOptions::default(),
))),
}
}
#[test]
fn control_commands_are_drained_before_normal_commands() {
let (sender, mut receiver) = channel();
sender.send(add_command(1)).unwrap();
sender
.send(EngineCommand::Pause {
gid: GroupId::new(1),
})
.unwrap();
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::Pause { .. })
));
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::AddDownload { .. })
));
}
#[test]
fn duplicate_gid_controls_are_coalesced_until_dequeue() {
let (sender, mut receiver) = channel();
let pause = || EngineCommand::Pause {
gid: GroupId::new(7),
};
sender.send(pause()).unwrap();
sender.send(pause()).unwrap();
let snapshot = sender.snapshot();
assert_eq!(snapshot.depth, 1);
assert_eq!(snapshot.max_depth, 1);
assert_eq!(snapshot.wakeups, 1);
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::Pause { .. })
));
assert!(matches!(
receiver.try_recv(),
Err(EngineCommandTryRecvError::Empty)
));
sender.send(pause()).unwrap();
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::Pause { .. })
));
}
#[test]
fn concurrent_duplicate_controls_have_one_committed_queue_entry() {
let (sender, mut receiver) = channel();
let mut producers = Vec::new();
for _ in 0..32 {
let sender = sender.clone();
producers.push(std::thread::spawn(move || {
sender
.send(EngineCommand::Pause {
gid: GroupId::new(8),
})
.unwrap();
}));
}
for producer in producers {
producer.join().unwrap();
}
assert_eq!(sender.snapshot().depth, 1);
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::Pause { .. })
));
assert!(matches!(
receiver.try_recv(),
Err(EngineCommandTryRecvError::Empty)
));
}
#[test]
fn full_normal_queue_rejects_without_growing_metrics() {
let (sender, mut receiver) = channel();
for gid in 1..=ENGINE_COMMAND_CAPACITY as u64 {
sender.send(add_command(gid)).unwrap();
}
let before = sender.snapshot();
assert_eq!(before.depth, ENGINE_COMMAND_CAPACITY);
assert_eq!(before.max_depth, ENGINE_COMMAND_CAPACITY);
assert_eq!(before.wakeups, 1);
assert_eq!(
sender.send(add_command(ENGINE_COMMAND_CAPACITY as u64 + 1)),
Err(EngineCommandSendError::Full)
);
assert_eq!(sender.snapshot().depth, ENGINE_COMMAND_CAPACITY);
assert_eq!(sender.snapshot().max_depth, ENGINE_COMMAND_CAPACITY);
assert_eq!(sender.snapshot().wakeups, 1);
sender
.send(EngineCommand::ForceHaltAll {
reason: HaltReason::ShutdownSignal,
})
.unwrap();
assert!(matches!(
receiver.try_recv(),
Ok(EngineCommand::ForceHaltAll { .. })
));
}
#[test]
fn closed_queue_rejects_and_receiver_reports_closed() {
let (sender, receiver) = channel();
drop(receiver);
assert_eq!(
sender.send(EngineCommand::PauseAll),
Err(EngineCommandSendError::Closed)
);
assert_eq!(sender.snapshot(), EngineCommandQueueSnapshot::default());
let (sender, mut receiver) = channel();
drop(sender);
assert!(matches!(
receiver.try_recv(),
Err(EngineCommandTryRecvError::Closed)
));
}
}