Skip to main content

ic_storage/adapter/
log.rs

1//! Governed log collection implementation.
2use super::{LogIter, LogWriteError, Memory, Storable};
3use crate::RuntimeMemory;
4use crate::{DefaultMemoryImpl, substrate};
5
6/// Governed upstream `Log`; initialization and failures follow upstream contracts.
7pub struct StableLog<T: Storable, M: Memory = DefaultMemoryImpl> {
8    inner: substrate::Log<T, RuntimeMemory<M>, RuntimeMemory<M>>,
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    /// Delegates to upstream `Log::first` with the governed allocation.
55    #[must_use]
56    pub fn first(&self) -> Option<T> {
57        self.inner.first()
58    }
59    /// Delegates to upstream `Log::last` with the governed allocation.
60    #[must_use]
61    pub fn last(&self) -> Option<T> {
62        self.inner.last()
63    }
64    /// Delegates to upstream `Log::get` with the governed allocation.
65    #[must_use]
66    pub fn get(&self, idx: u64) -> Option<T> {
67        self.inner.get(idx)
68    }
69    /// Delegates to upstream `Log::len` with the governed allocation.
70    #[must_use]
71    pub fn len(&self) -> u64 {
72        self.inner.len()
73    }
74    /// Delegates to upstream `Log::is_empty` with the governed allocation.
75    #[must_use]
76    pub fn is_empty(&self) -> bool {
77        self.inner.is_empty()
78    }
79    /// Delegates to upstream `Log::append` with the governed allocation.
80    /// # Errors
81    /// Returns the upstream write error if memory cannot grow.
82    pub fn append(&self, item: &T) -> Result<u64, LogWriteError> {
83        self.inner.append(item)
84    }
85    /// Delegates to upstream `Log::iter` with the governed allocation.
86    #[must_use]
87    pub fn iter(&self) -> LogIter<'_, T, M> {
88        self.inner.iter()
89    }
90}
91
92impl<'a, T: Storable, M: Memory> IntoIterator for &'a StableLog<T, M> {
93    type Item = T;
94    type IntoIter = LogIter<'a, T, M>;
95    fn into_iter(self) -> Self::IntoIter {
96        self.iter()
97    }
98}