cadmpeg_core/decode/
error.rs

1// SPDX-License-Identifier: Apache-2.0
2//! Resource-failure types shared by the budget and [`CodecError`].
3//!
4//! [`CodecError`]: crate::CodecError
5
6use super::space::SpaceId;
7
8/// Which resource a limit governs.
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum ResourceDimension {
11    /// Physical input bytes read at the root.
12    InputBytes,
13    /// Bytes produced by decompression.
14    DecompressedBytes,
15    /// Bytes held by scoped materializations.
16    MaterializedBytes,
17    /// Bytes retained for the decode session outside expansion output.
18    RetainedBytes,
19    /// Admitted semantic or native entities.
20    Entities,
21    /// Admitted items across decoded collections.
22    CollectionItems,
23    /// Active recursive nesting depth.
24    RecursionDepth,
25    /// Algorithm work units.
26    WorkUnits,
27    /// A codec-local resource dimension.
28    Codec(&'static str),
29}
30
31/// Why a resource request failed.
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub enum ResourceFailure {
34    /// Policy refused: the request would exceed the allowance.
35    BudgetExceeded,
36    /// The allocator refused, surfaced via `try_reserve`.
37    AllocationFailed,
38}
39
40/// The extent a limit applies to.
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum LimitScope {
43    /// The whole decode.
44    Global,
45    /// One expansion.
46    PerExpand,
47}
48
49/// An offset qualified by its address space.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51pub struct SourceLocation {
52    /// The space the offset indexes.
53    pub space: SpaceId,
54    /// The absolute offset within that space.
55    pub offset: u64,
56}
57
58/// Allocation-free context attached to a failure.
59#[derive(Debug, Clone, Copy, PartialEq, Eq)]
60pub struct ErrorContext {
61    /// The operation that failed, as a static label.
62    pub operation: &'static str,
63    /// Where it failed, when a location is known.
64    pub location: Option<SourceLocation>,
65}
66
67/// A resource refusal.
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
69pub struct ResourceLimit {
70    /// The dimension that refused the request.
71    pub dimension: ResourceDimension,
72    /// Whether policy or the allocator refused.
73    pub reason: ResourceFailure,
74    /// The extent the limit applies to.
75    pub scope: LimitScope,
76    /// The allowance in force.
77    pub limit: u64,
78    /// The amount already charged before this request.
79    pub used: u64,
80    /// The saturating size of the request that failed.
81    pub additional: u64,
82    /// Static context for the failure.
83    pub context: ErrorContext,
84}
cadmpeg_core/decode/error.rs

cadmpeg_core/decode/
error.rs
