transact/state/
reader.rs

1/*
2 * Copyright 2022 Cargill Incorporated
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 * -----------------------------------------------------------------------------
16 */
17
18use std::collections::HashMap;
19
20use super::{State, StateError};
21
22pub type ValueIterResult<T> = Result<T, StateError>;
23pub type ValueIter<T> = Box<dyn Iterator<Item = ValueIterResult<T>>>;
24
25/// Provides a way to retrieve state values from a particular storage system.
26///
27/// This trait provides similar behaviour to the [`Read`](super::Read) trait, without the
28/// explicit requirements about thread safety.
29///
30/// Available with the feature `"state-in-transaction"` enabled.
31pub trait Reader: State {
32    /// The filter used for the iterating over state values.
33    type Filter: ?Sized;
34
35    /// At a given `StateId`, attempt to retrieve the given slice of keys.
36    ///
37    /// The results of the get will be returned in a `HashMap`.  Only keys that were found will be
38    /// in this map. Keys missing from the map can be assumed to be missing from the underlying
39    /// storage system as well.
40    ///
41    /// # Errors
42    ///
43    /// [`StateError`] is returned if any issues occur while trying to fetch the values.
44    fn get(
45        &self,
46        state_id: &Self::StateId,
47        keys: &[Self::Key],
48    ) -> Result<HashMap<Self::Key, Self::Value>, StateError>;
49
50    /// Returns an iterator over the values of state.
51    ///
52    /// By providing an optional filter, the caller can limit the iteration over a subset of the
53    /// values.
54    ///
55    /// The values are returned in their natural order.
56    ///
57    /// # Errors
58    ///
59    /// [`StateError`] is returned if any issues occur while trying to query the values.
60    /// Additionally, a [`StateError`] may be returned on each call to `next` on the resulting
61    /// iteration.
62    fn filter_iter(
63        &self,
64        state_id: &Self::StateId,
65        filter: Option<&Self::Filter>,
66    ) -> ValueIterResult<ValueIter<(Self::Key, Self::Value)>>;
67}
transact/state/reader.rs

transact/state/
reader.rs
