ic-memory 0.44.0

Durable stable-memory allocation governance for Internet Computer canisters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

use crate::{key::StableKey, physical::CommitRecoveryError, slot::MemoryManagerSlot};

///
/// LedgerIntegrityError
///
/// Decoded ledger violates current ownership invariants.
///

#[non_exhaustive]
#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
pub enum LedgerIntegrityError {
    /// Current structural recovery ceiling exceeded.
    #[error("ledger exceeds {resource} limit {limit}")]
    LimitExceeded {
        resource: &'static str,
        limit: usize,
    },
    /// Stable key appears in more than one retained allocation record.
    #[error("stable key '{stable_key}' appears in more than one allocation record")]
    DuplicateStableKey { stable_key: StableKey },
    /// Memory ID appears in more than one retained allocation record.
    #[error("allocation slot '{slot:?}' appears in more than one allocation record")]
    DuplicateSlot { slot: MemoryManagerSlot },
    /// Commit counter zero is reserved for empty genesis.
    #[error("genesis ledger contains allocation records")]
    NonemptyGenesis,
}

///
/// LedgerCommitError
///
/// Failure to recover or commit a logical allocation ledger.
#[non_exhaustive]
#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
pub enum LedgerCommitError {
    /// Protected physical commit recovery failed.
    #[error(transparent)]
    Recovery(CommitRecoveryError),
    /// Physical slot generation and decoded logical ledger generation disagree.
    #[error(
        "physical generation {physical_generation} does not match logical ledger generation {logical_generation}"
    )]
    PhysicalLogicalGenerationMismatch {
        /// Generation encoded in the physical snapshot.
        physical_generation: u64,
        /// Generation decoded from the logical allocation ledger.
        logical_generation: u64,
    },
    /// Built-in ledger decoding failed.
    #[error("allocation ledger codec failed: {0}")]
    Codec(String),
    /// Decoded ledger violates current ownership invariants.
    #[error(transparent)]
    Integrity(LedgerIntegrityError),
}

///
/// AllocationStageError
///
/// Failure to stage a validated allocation generation.
///

#[non_exhaustive]
#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
pub enum AllocationStageError {
    /// The commit counter cannot advance without overflow.
    #[error("ledger generation {generation} cannot be advanced without overflow")]
    GenerationOverflow { generation: u64 },
    #[error(transparent)]
    Integrity(#[from] LedgerIntegrityError),
}