use crate::operation::download::body::BodySlot;
use crate::operation::download::checksum::DownloadIntegrity;
use crate::runtime::buffer_pool::ReserveFuture;
use crate::transfer::{PendingCategory, PendingCause};
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum DownloadPendingReason {
Discovery,
ReadAhead,
MemoryAdmission,
RangeCompletion,
DrainCompletion,
}
impl From<DownloadPendingReason> for PendingCause {
fn from(reason: DownloadPendingReason) -> Self {
match reason {
DownloadPendingReason::Discovery => Self::in_flight_work("discovery"),
DownloadPendingReason::ReadAhead => Self::new(PendingCategory::Consumer, "read_ahead"),
DownloadPendingReason::MemoryAdmission => {
Self::new(PendingCategory::Memory, "memory_admission")
}
DownloadPendingReason::RangeCompletion => Self::in_flight_work("range_completion"),
DownloadPendingReason::DrainCompletion => Self::in_flight_work("drain_completion"),
}
}
}
pub(crate) struct PendingClaim {
pub(crate) slot: BodySlot,
pub(crate) reservation: ReserveFuture,
}
impl std::fmt::Debug for PendingClaim {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("PendingClaim")
.field("slot", &self.slot)
.finish_non_exhaustive()
}
}
#[derive(Debug)]
pub(crate) enum DownloadState {
PendingDiscovery,
DiscoveryInFlight,
Transferring {
remaining: Option<std::ops::RangeInclusive<u64>>,
ranges_in_flight: usize,
drains_in_flight: u32,
etag: Option<std::sync::Arc<str>>,
part_size: u64,
gate: OccupancyGate,
pending: Option<PendingClaim>,
integrity: Box<DownloadIntegrity>,
},
Terminal,
}
impl DownloadState {
pub(crate) fn new() -> Self {
DownloadState::PendingDiscovery
}
#[must_use = "drop the returned PendingClaim only after releasing the state lock"]
pub(crate) fn enter_terminal(&mut self) -> Option<PendingClaim> {
let pending = match self {
DownloadState::Transferring { pending, .. } => pending.take(),
_ => None,
};
*self = DownloadState::Terminal;
pending
}
pub(crate) fn try_claim_completion(&mut self) -> Option<CompletionClaim> {
let DownloadState::Transferring {
remaining: None,
ranges_in_flight: 0,
drains_in_flight: 0,
pending: None,
..
} = self
else {
return None;
};
let DownloadState::Transferring { integrity, .. } =
std::mem::replace(self, DownloadState::Terminal)
else {
unreachable!("the state matched Transferring above");
};
Some(CompletionClaim(integrity))
}
}
#[must_use = "a completion claimed while active must be finalized after releasing the state lock"]
#[derive(Debug)]
pub(crate) struct CompletionClaim(Box<DownloadIntegrity>);
impl CompletionClaim {
pub(super) fn finish_integrity(
self,
) -> Result<crate::types::IntegrityChecks, crate::error::Error> {
self.0.finish()
}
}
#[derive(Debug, Default)]
pub(crate) struct OccupancyGate {
issued: u64,
released: u64,
}
impl OccupancyGate {
pub(crate) fn with_issued(issued: u64) -> Self {
Self {
issued,
released: 0,
}
}
pub(crate) fn try_issue(&mut self, window: u64) -> bool {
if self.issued - self.released >= window {
false
} else {
self.issued += 1;
true
}
}
pub(crate) fn release(&mut self, n: u64) {
self.released += n;
}
pub(crate) fn resident(&self) -> u64 {
self.issued - self.released
}
pub(crate) fn issued(&self) -> u64 {
self.issued
}
pub(crate) fn released(&self) -> u64 {
self.released
}
}
#[cfg(test)]
mod tests {
use super::{DownloadPendingReason, DownloadState, OccupancyGate};
use crate::transfer::PendingCategory;
fn transferring(
remaining: Option<std::ops::RangeInclusive<u64>>,
ranges_in_flight: usize,
drains_in_flight: u32,
) -> DownloadState {
DownloadState::Transferring {
remaining,
ranges_in_flight,
drains_in_flight,
etag: None,
part_size: 8,
gate: OccupancyGate::default(),
pending: None,
integrity: Box::default(),
}
}
#[test]
fn completion_is_not_claimed_with_work_outstanding() {
let outstanding = [
("a range remaining", transferring(Some(0..=7), 0, 0)),
("a range in flight", transferring(None, 1, 0)),
("a drain in flight", transferring(None, 0, 1)),
];
for (what, mut state) in outstanding {
assert!(
state.try_claim_completion().is_none(),
"completion claimed with {what}"
);
assert!(
matches!(state, DownloadState::Transferring { .. }),
"state changed with {what}: {state:?}"
);
}
for mut state in [
DownloadState::PendingDiscovery,
DownloadState::DiscoveryInFlight,
DownloadState::Terminal,
] {
let before = format!("{state:?}");
assert!(
state.try_claim_completion().is_none(),
"claimed from {before}"
);
assert_eq!(format!("{state:?}"), before);
}
}
#[test]
fn completion_is_claimed_exactly_once() {
let mut state = transferring(None, 0, 0);
assert!(state.try_claim_completion().is_some());
assert!(matches!(state, DownloadState::Terminal));
assert!(state.try_claim_completion().is_none(), "claimed twice");
}
#[test]
fn gate_closes_at_window() {
let mut g = OccupancyGate::default();
assert!(g.try_issue(2));
assert!(g.try_issue(2));
assert!(!g.try_issue(2), "gate must close once resident == window");
assert_eq!(g.resident(), 2);
assert_eq!(g.issued(), 2, "a gated try_issue must not bump issued");
}
#[test]
fn release_lowers_resident_and_reopens_the_gate() {
let mut g = OccupancyGate::default();
g.try_issue(2);
g.try_issue(2); assert!(!g.try_issue(2), "closed at the window");
g.release(1); assert_eq!(g.resident(), 1, "release lowers resident occupancy");
assert!(
g.try_issue(2),
"the freed part reopened the gate for one more"
);
}
#[test]
fn window_one_admits_exactly_one_resident_part() {
let mut g = OccupancyGate::default();
assert!(g.try_issue(1));
assert!(!g.try_issue(1), "window 1 admits exactly one resident part");
g.release(1);
assert!(g.try_issue(1), "gate reopened, next part may issue");
}
#[test]
fn pending_reasons_map_to_common_transfer_categories() {
let cases = [
(
DownloadPendingReason::Discovery,
PendingCategory::InFlightWork,
"discovery",
),
(
DownloadPendingReason::ReadAhead,
PendingCategory::Consumer,
"read_ahead",
),
(
DownloadPendingReason::MemoryAdmission,
PendingCategory::Memory,
"memory_admission",
),
(
DownloadPendingReason::RangeCompletion,
PendingCategory::InFlightWork,
"range_completion",
),
(
DownloadPendingReason::DrainCompletion,
PendingCategory::InFlightWork,
"drain_completion",
),
];
for (reason, category, detail) in cases {
let cause = crate::transfer::PendingCause::from(reason);
assert_eq!(cause.category, category);
assert_eq!(cause.reason, detail);
}
}
}