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    fn is_empty(&self) -> bool;
53
54    /// Iterates over all entries in key order.
55    fn safe_iter(&'a self) -> DbIterator<'a, (K, V)>;
56
57    /// Iterates over the half-open key range `[lower_bound, upper_bound)` —
58    /// the lower bound is inclusive, the upper bound exclusive, and a `None`
59    /// bound leaves that side unbounded. Equivalent to
60    /// `safe_range_iter(lower_bound..upper_bound)`.
61    fn safe_iter_with_bounds(
62        &'a self,
63        lower_bound: Option<K>,
64        upper_bound: Option<K>,
65    ) -> DbIterator<'a, (K, V)>;
66
67    /// Iterates over the keys within `range`, honoring the range's own bound
68    /// inclusivity (e.g. `lo..hi` excludes `hi`, `lo..=hi` includes it).
69    fn safe_range_iter(&'a self, range: impl RangeBounds<K>) -> DbIterator<'a, (K, V)>;
70
71    /// Reverse counterpart of [`Self::safe_range_iter`]: yields exactly the
72    /// keys of `safe_range_iter(range)` in descending order.
73    fn safe_range_iter_reversed(&'a self, range: impl RangeBounds<K>) -> DbIterator<'a, (K, V)>;
74
75    /// Returns a vector of values corresponding to the keys provided,
76    /// non-atomically.
77    fn multi_get<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<Vec<Option<V>>, Self::Error>
78    where
79        J: Borrow<K>,
80    {
81        keys.into_iter().map(|key| self.get(key.borrow())).collect()
82    }
83
84    /// Inserts key-value pairs, non-atomically.
85    fn multi_insert<J, U>(
86        &self,
87        key_val_pairs: impl IntoIterator<Item = (J, U)>,
88    ) -> Result<(), Self::Error>
89    where
90        J: Borrow<K>,
91        U: Borrow<V>,
92    {
93        key_val_pairs
94            .into_iter()
95            .try_for_each(|(key, value)| self.insert(key.borrow(), value.borrow()))
96    }
97
98    /// Removes keys, non-atomically.
99    fn multi_remove<J>(&self, keys: impl IntoIterator<Item = J>) -> Result<(), Self::Error>
100    where
101        J: Borrow<K>,
102    {
103        keys.into_iter()
104            .try_for_each(|key| self.remove(key.borrow()))
105    }
106
107    /// Try to catch up with primary when running as secondary
108    fn try_catch_up_with_primary(&self) -> Result<(), Self::Error>;
109}
110
111pub struct TableSummary {
112    pub num_keys: u64,
113    pub key_bytes_total: usize,
114    pub value_bytes_total: usize,
115    pub key_hist: hdrhistogram::Histogram<u64>,
116    pub value_hist: hdrhistogram::Histogram<u64>,
117}
typed_store/traits.rs

typed_store/
traits.rs
