laddu_memory/error.rs
1use thiserror::Error;
2
3use crate::budget::MemoryBudget;
4
5/// Result type for memory planning operations.
6pub type MemoryResult<T> = Result<T, MemoryError>;
7
8/// Overflow produced while composing a checked memory footprint.
9///
10/// This error is intentionally separate from [`MemoryError`]: footprint
11/// construction is a low-level arithmetic concern, while budget exhaustion is
12/// an operation-level planning result. Callers that retain the historical
13/// saturating planning behavior can use the infallible footprint helpers.
14#[doc(hidden)]
15#[derive(Clone, Copy, Debug, Error, PartialEq, Eq)]
16pub enum FootprintOverflow {
17 /// Adding fixed or per-event components exceeded `u64`.
18 #[error("memory footprint addition overflow")]
19 Addition,
20 /// Scaling fixed or per-event components exceeded `u64`.
21 #[error("memory footprint multiplication overflow")]
22 Multiplication,
23 /// Converting a platform-sized byte count exceeded `u64`.
24 #[error("memory footprint conversion overflow")]
25 Conversion,
26}
27
28/// Errors produced while discovering or reserving memory.
29#[derive(Clone, Debug, Error, PartialEq)]
30pub enum MemoryError {
31 /// A budget string or percentage is invalid.
32 #[error("invalid memory budget: {0}")]
33 InvalidBudget(String),
34 /// A percentage cannot be resolved because capacity telemetry is unavailable.
35 #[error("cannot resolve {budget} for {resource}: {basis} memory is unavailable")]
36 UnknownCapacity {
37 /// Resource label.
38 resource: String,
39 /// Requested budget.
40 budget: MemoryBudget,
41 /// Missing capacity basis.
42 basis: &'static str,
43 },
44 /// A reservation exceeds the effective pool limit.
45 #[error(
46 "memory budget exceeded for {resource}: requested {requested} bytes, \
47 {remaining} bytes remain"
48 )]
49 BudgetExceeded {
50 /// Resource label.
51 resource: String,
52 /// Requested reservation.
53 requested: u64,
54 /// Remaining reservable bytes.
55 remaining: u64,
56 },
57}