typed_store/
traits.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::{borrow::Borrow, collections::BTreeMap, error::Error, ops::RangeBounds};
6
7use serde::{Serialize, de::DeserializeOwned};
8
9use crate::TypedStoreError;
10
11pub trait Map<'a, K, V>
12where
13    K: Serialize + DeserializeOwned,
14    V: Serialize + DeserializeOwned,
15{
16    type Error: Error;
17    type Iterator: Iterator<Item = (K, V)>;
18    type SafeIterator: Iterator<Item = Result<(K, V), TypedStoreError>>;
19
20    /// Returns true if the map contains a value for the specified key.
21    fn contains_key(&self, key: &K) -> Result<bool, Self::Error>;
22
23    /// Returns true if the map contains a value for the specified key.
24    fn multi_contains_keys<J>(
25        &self,
26        keys: impl IntoIterator<Item = J>,
27    ) -> Result<Vec<bool>, Self::Error>
28    where
29        J: Borrow<K>,
30    {
31        keys.into_iter()
32            .map(|key| self.contains_key(key.borrow()))
33            .collect()
34    }
35
36    /// Returns the value for the given key from the map, if it exists.
37    fn get(&self, key: &K) -> Result<Option<V>, Self::Error>;
38
39    /// Inserts the given key-value pair into the map.
40    fn insert(&self, key: &K, value: &V) -> Result<(), Self::Error>;
41
42    /// Removes the entry for the given key from the map.
43    fn remove(&self, key: &K) -> Result<(), Self::Error>;
44
45    /// Removes every key-value pair from the map.
46    fn unsafe_clear(&self) -> Result<(), Self::Error>;
47
48    /// Uses delete range on the entire key range
49    fn schedule_delete_all(&self) -> Result<(), TypedStoreError>;
50
51    /// Returns true if the map is empty, otherwise false.
52    fn is_empty(&self) -> bool;
53
54    /// Returns an unbounded iterator visiting each key-value pair in the map.
55    /// This is potentially unsafe as it can perform a full table scan
56    fn unbounded_iter(&'a self) -> Self::Iterator;
57
58    /// Returns an iterator visiting each key-value pair within the specified
59    /// bounds in the map.
60    fn iter_with_bounds(&'a self, lower_bound: Option<K>, upper_bound: Option<K>)
61    -> Self::Iterator;
62
63    /// Similar to `iter_with_bounds` but allows specifying
64    /// inclusivity/exclusivity of ranges explicitly. TODO: find better name
65    fn range_iter(&'a self, range: impl RangeBounds<K>) -> Self::Iterator;
66
67    /// Same as `iter` but performs status check.
68    fn safe_iter(&'a self) -> Self::SafeIterator;
69
70    // Same as `iter_with_bounds` but performs status check.
71    fn safe_iter_with_bounds(
72        &'a self,
73        lower_bound: Option<K>,
74        upper_bound: Option<K>,
75    ) -> Self::SafeIterator;
76
77    // Same as `range_iter` but performs status check.
78    fn safe_range_iter(&'a self, range: impl RangeBounds<K>) -> Self::SafeIterator;
79
80    /// Returns a vector of values corresponding to the keys provided,
81    /// non-atomically.
82    fn multi_get<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<Vec<Option<V>>, Self::Error>
83    where
84        J: Borrow<K>,
85    {
86        keys.into_iter().map(|key| self.get(key.borrow())).collect()
87    }
88
89    /// Inserts key-value pairs, non-atomically.
90    fn multi_insert<J, U>(
91        &self,
92        key_val_pairs: impl IntoIterator<Item = (J, U)>,
93    ) -> Result<(), Self::Error>
94    where
95        J: Borrow<K>,
96        U: Borrow<V>,
97    {
98        key_val_pairs
99            .into_iter()
100            .try_for_each(|(key, value)| self.insert(key.borrow(), value.borrow()))
101    }
102
103    /// Removes keys, non-atomically.
104    fn multi_remove<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<(), Self::Error>
105    where
106        J: Borrow<K>,
107    {
108        keys.into_iter()
109            .try_for_each(|key| self.remove(key.borrow()))
110    }
111
112    /// Try to catch up with primary when running as secondary
113    fn try_catch_up_with_primary(&self) -> Result<(), Self::Error>;
114}
115
116pub struct TableSummary {
117    pub num_keys: u64,
118    pub key_bytes_total: usize,
119    pub value_bytes_total: usize,
120    pub key_hist: hdrhistogram::Histogram<u64>,
121    pub value_hist: hdrhistogram::Histogram<u64>,
122}
123
124pub trait TypedStoreDebug {
125    /// Dump a DB table with pagination
126    fn dump_table(
127        &self,
128        table_name: String,
129        page_size: u16,
130        page_number: usize,
131    ) -> eyre::Result<BTreeMap<String, String>>;
132
133    /// Get the name of the DB. This is simply the name of the struct
134    fn primary_db_name(&self) -> String;
135
136    /// Get a map of table names to key-value types
137    fn describe_all_tables(&self) -> BTreeMap<String, (String, String)>;
138
139    /// Count the entries in the table
140    fn count_table_keys(&self, table_name: String) -> eyre::Result<usize>;
141
142    /// Return table summary of the input table
143    fn table_summary(&self, table_name: String) -> eyre::Result<TableSummary>;
144}
typed_store/traits.rs

typed_store/
traits.rs
