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 SafeIterator: Iterator<Item = Result<(K, V), TypedStoreError>>;
18
19    /// Returns true if the map contains a value for the specified key.
20    fn contains_key(&self, key: &K) -> Result<bool, Self::Error>;
21
22    /// Returns true if the map contains a value for the specified key.
23    fn multi_contains_keys<J>(
24        &self,
25        keys: impl IntoIterator<Item = J>,
26    ) -> Result<Vec<bool>, Self::Error>
27    where
28        J: Borrow<K>,
29    {
30        keys.into_iter()
31            .map(|key| self.contains_key(key.borrow()))
32            .collect()
33    }
34
35    /// Returns the value for the given key from the map, if it exists.
36    fn get(&self, key: &K) -> Result<Option<V>, Self::Error>;
37
38    /// Inserts the given key-value pair into the map.
39    fn insert(&self, key: &K, value: &V) -> Result<(), Self::Error>;
40
41    /// Removes the entry for the given key from the map.
42    fn remove(&self, key: &K) -> Result<(), Self::Error>;
43
44    /// Removes every key-value pair from the map.
45    fn unsafe_clear(&self) -> Result<(), Self::Error>;
46
47    /// Uses delete range on the entire key range
48    fn schedule_delete_all(&self) -> Result<(), TypedStoreError>;
49
50    /// Returns true if the map is empty, otherwise false.
51    fn is_empty(&self) -> bool;
52
53    /// Same as `iter` but performs status check.
54    fn safe_iter(&'a self) -> Self::SafeIterator;
55
56    // Same as `iter_with_bounds` but performs status check.
57    fn safe_iter_with_bounds(
58        &'a self,
59        lower_bound: Option<K>,
60        upper_bound: Option<K>,
61    ) -> Self::SafeIterator;
62
63    // Same as `range_iter` but performs status check.
64    fn safe_range_iter(&'a self, range: impl RangeBounds<K>) -> Self::SafeIterator;
65
66    /// Returns a vector of values corresponding to the keys provided,
67    /// non-atomically.
68    fn multi_get<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<Vec<Option<V>>, Self::Error>
69    where
70        J: Borrow<K>,
71    {
72        keys.into_iter().map(|key| self.get(key.borrow())).collect()
73    }
74
75    /// Inserts key-value pairs, non-atomically.
76    fn multi_insert<J, U>(
77        &self,
78        key_val_pairs: impl IntoIterator<Item = (J, U)>,
79    ) -> Result<(), Self::Error>
80    where
81        J: Borrow<K>,
82        U: Borrow<V>,
83    {
84        key_val_pairs
85            .into_iter()
86            .try_for_each(|(key, value)| self.insert(key.borrow(), value.borrow()))
87    }
88
89    /// Removes keys, non-atomically.
90    fn multi_remove<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<(), Self::Error>
91    where
92        J: Borrow<K>,
93    {
94        keys.into_iter()
95            .try_for_each(|key| self.remove(key.borrow()))
96    }
97
98    /// Try to catch up with primary when running as secondary
99    fn try_catch_up_with_primary(&self) -> Result<(), Self::Error>;
100}
101
102pub struct TableSummary {
103    pub num_keys: u64,
104    pub key_bytes_total: usize,
105    pub value_bytes_total: usize,
106    pub key_hist: hdrhistogram::Histogram<u64>,
107    pub value_hist: hdrhistogram::Histogram<u64>,
108}
109
110pub trait TypedStoreDebug {
111    /// Dump a DB table with pagination
112    fn dump_table(
113        &self,
114        table_name: String,
115        page_size: u16,
116        page_number: usize,
117    ) -> eyre::Result<BTreeMap<String, String>>;
118
119    /// Get the name of the DB. This is simply the name of the struct
120    fn primary_db_name(&self) -> String;
121
122    /// Get a map of table names to key-value types
123    fn describe_all_tables(&self) -> BTreeMap<String, (String, String)>;
124
125    /// Count the entries in the table
126    fn count_table_keys(&self, table_name: String) -> eyre::Result<usize>;
127
128    /// Return table summary of the input table
129    fn table_summary(&self, table_name: String) -> eyre::Result<TableSummary>;
130}
typed_store/traits.rs

typed_store/
traits.rs
