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, error::Error, ops::RangeBounds};
6
7use serde::{Serialize, de::DeserializeOwned};
8
9use crate::TypedStoreError;
10
11pub type DbIterator<'a, T> = Box<dyn Iterator<Item = Result<T, TypedStoreError>> + 'a>;
12
13pub trait Map<'a, K, V>
14where
15    K: Serialize + DeserializeOwned,
16    V: Serialize + DeserializeOwned,
17{
18    type Error: Error;
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 entry from the map.
46    ///
47    /// Not atomic with respect to concurrent writers: an entry inserted while
48    /// the call is in flight may survive it.
49    fn schedule_delete_all(&self) -> Result<(), TypedStoreError>;
50
51    /// Returns true if the map is empty, otherwise false.
52    ///
53    /// Has no error channel, so a map whose scan cannot be constructed reads
54    /// as non-empty, see [`Self::safe_iter`].
55    fn is_empty(&self) -> bool;
56
57    /// Iterates over all entries in key order.
58    ///
59    /// A scan the backend cannot construct, e.g. over a dropped column
60    /// family, yields that error as its single item, so it counts as one
61    /// entry rather than none.
62    fn safe_iter(&'a self) -> DbIterator<'a, (K, V)>;
63
64    /// Iterates over the half-open key range `[lower_bound, upper_bound)` —
65    /// the lower bound is inclusive, the upper bound exclusive, and a `None`
66    /// bound leaves that side unbounded. Equivalent to
67    /// `safe_range_iter(lower_bound..upper_bound)`.
68    fn safe_iter_with_bounds(
69        &'a self,
70        lower_bound: Option<K>,
71        upper_bound: Option<K>,
72    ) -> DbIterator<'a, (K, V)>;
73
74    /// Iterates over the keys within `range`, honoring the range's own bound
75    /// inclusivity (e.g. `lo..hi` excludes `hi`, `lo..=hi` includes it).
76    fn safe_range_iter(&'a self, range: impl RangeBounds<K>) -> DbIterator<'a, (K, V)>;
77
78    /// Reverse counterpart of [`Self::safe_range_iter`]: yields exactly the
79    /// keys of `safe_range_iter(range)` in descending order.
80    fn safe_range_iter_reversed(&'a self, range: impl RangeBounds<K>) -> DbIterator<'a, (K, V)>;
81
82    /// Returns a vector of values corresponding to the keys provided,
83    /// non-atomically.
84    fn multi_get<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<Vec<Option<V>>, Self::Error>
85    where
86        J: Borrow<K>,
87    {
88        keys.into_iter().map(|key| self.get(key.borrow())).collect()
89    }
90
91    /// Inserts key-value pairs, non-atomically.
92    fn multi_insert<J, U>(
93        &self,
94        key_val_pairs: impl IntoIterator<Item = (J, U)>,
95    ) -> Result<(), Self::Error>
96    where
97        J: Borrow<K>,
98        U: Borrow<V>,
99    {
100        key_val_pairs
101            .into_iter()
102            .try_for_each(|(key, value)| self.insert(key.borrow(), value.borrow()))
103    }
104
105    /// Removes keys, non-atomically.
106    fn multi_remove<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<(), Self::Error>
107    where
108        J: Borrow<K>,
109    {
110        keys.into_iter()
111            .try_for_each(|key| self.remove(key.borrow()))
112    }
113
114    /// Try to catch up with primary when running as secondary
115    fn try_catch_up_with_primary(&self) -> Result<(), Self::Error>;
116}
117
118pub struct TableSummary {
119    pub num_keys: u64,
120    pub key_bytes_total: usize,
121    pub value_bytes_total: usize,
122    pub key_hist: hdrhistogram::Histogram<u64>,
123    pub value_hist: hdrhistogram::Histogram<u64>,
124}
typed_store/traits.rs

typed_store/
traits.rs
