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

typed_store/
traits.rs
