Skip to main content

ic_storage/adapter/
log.rs

1//! Governed log collection implementation.
2use super::{LogIter, LogWriteError, Memory, Storable};
3use crate::{DefaultMemoryImpl, RuntimeMemory, substrate};
4
5/// Governed upstream `Log`; initialization and failures follow upstream contracts.
6pub struct StableLog<T: Storable, M: Memory = DefaultMemoryImpl> {
7    inner: substrate::Log<T, RuntimeMemory<M>, RuntimeMemory<M>>,
8}
9
10impl<T: Storable, M: Memory> StableLog<T, M> {
11    /// Create a log only when both admitted memories have zero pages.
12    ///
13    /// # Panics
14    /// Refuses either nonempty memory before writing. Growth failures retain
15    /// upstream behavior.
16    #[must_use]
17    pub fn create(index_memory: RuntimeMemory<M>, data_memory: RuntimeMemory<M>) -> Self {
18        assert_eq!(index_memory.size(), 0, "log index is not empty");
19        assert_eq!(data_memory.size(), 0, "log data is not empty");
20        Self::reset(index_memory, data_memory)
21    }
22
23    /// Deliberately replace both admitted log allocations.
24    ///
25    /// # Panics
26    /// Growth and backing failures retain upstream behavior.
27    #[must_use]
28    pub fn reset(index_memory: RuntimeMemory<M>, data_memory: RuntimeMemory<M>) -> Self {
29        Self {
30            inner: substrate::Log::new(index_memory, data_memory),
31        }
32    }
33
34    /// Load a retained log without initializing either allocation.
35    ///
36    /// # Panics
37    /// Refuses empty/foreign memory and incompatible layouts without writing.
38    /// Backing and collection corruption failures retain upstream behavior.
39    #[must_use]
40    pub fn load(index_memory: RuntimeMemory<M>, data_memory: RuntimeMemory<M>) -> Self {
41        assert!(
42            index_memory.size() > 0 && data_memory.size() > 0,
43            "log memory is empty"
44        );
45        let mut magic = [0; 3];
46        data_memory.read(0, &mut magic);
47        assert_eq!(&magic, b"GLD", "foreign log data");
48        // With recognized data magic upstream refuses every other incompatible
49        // header before writes, including invalid/missing index magic.
50        Self {
51            inner: substrate::Log::init(index_memory, data_memory),
52        }
53    }
54
55    /// Delegates to upstream `Log::first` with the governed allocation.
56    #[must_use]
57    pub fn first(&self) -> Option<T> {
58        self.inner.first()
59    }
60
61    /// Delegates to upstream `Log::last` with the governed allocation.
62    #[must_use]
63    pub fn last(&self) -> Option<T> {
64        self.inner.last()
65    }
66
67    /// Delegates to upstream `Log::get` with the governed allocation.
68    #[must_use]
69    pub fn get(&self, idx: u64) -> Option<T> {
70        self.inner.get(idx)
71    }
72
73    /// Delegates to upstream `Log::len` with the governed allocation.
74    #[must_use]
75    pub fn len(&self) -> u64 {
76        self.inner.len()
77    }
78
79    /// Delegates to upstream `Log::is_empty` with the governed allocation.
80    #[must_use]
81    pub fn is_empty(&self) -> bool {
82        self.inner.is_empty()
83    }
84
85    /// Delegates to upstream `Log::append` with the governed allocation.
86    /// # Errors
87    /// Returns the upstream write error if memory cannot grow.
88    pub fn append(&self, item: &T) -> Result<u64, LogWriteError> {
89        self.inner.append(item)
90    }
91
92    /// Delegates to upstream `Log::iter` with the governed allocation.
93    #[must_use]
94    pub fn iter(&self) -> LogIter<'_, T, M> {
95        self.inner.iter()
96    }
97}
98
99impl<'a, T: Storable, M: Memory> IntoIterator for &'a StableLog<T, M> {
100    type Item = T;
101    type IntoIter = LogIter<'a, T, M>;
102    fn into_iter(self) -> Self::IntoIter {
103        self.iter()
104    }
105}