pub struct Snapshot<'a, S: Storage> { /* private fields */ }Expand description
A transactional snapshot of a store at a particular point in time that caches all reads and buffers all writes in memory.
A transaction is a snapshot of the store at the point in time when the
transaction was started. New values can be added inside the transaction, but
writes from other transactions are isolated from the current transaction.
Reads are cached for each transaction, so that multiple reads of the same
key (and version) only have to access storage once. Writes are only
persisted at the end of a successful transaction, until then all writes
simply mutate an in-memory HashMap.
Transactions provide some basic ACID guarantees and must be
serializable, meaning that
a transaction can only be committed if it does not conflict with a
previously committed transaction. If a transaction t1 reads any key-value
pair (even a version with an older timestamp) that is modified and committed
in a later transaction t2 before t1 is comitted, t1 will fail with an
Error::TransactionConflict and must be explicitly rerun by user of the
store. In other words, the following transaction behaviour will lead to a
conflict:
+- t1: -------+
| read key1 | +- t2 --------+
| | | write key1 |
| | | commit: ok |
| write key1 | +-------------+
| commit: err |
+-------------+Implementations§
Source§impl<'a, S: Storage> Snapshot<'a, S>
impl<'a, S: Storage> Snapshot<'a, S>
Sourcepub async fn get<K, V>(&self, slot: u8, k: &K) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
pub async fn get<K, V>(&self, slot: u8, k: &K) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
Returns the latest value associated with a slot and key from the store.
Returns None if the key is not found in the store or if the value
associated with the key has been removed and was thus “moved to trash”.
Sourcepub async fn get_unremoved<K, V>(&self, slot: u8, k: &K) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
pub async fn get_unremoved<K, V>(&self, slot: u8, k: &K) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
Returns the latest non-removed value associated with a slot and key from the store (even if the value was moved to the trash).
Returns None only if the key is not found in the store and there is
no old version of it in the store. If the value associated with the key
has been removed from the store but is still “in the trash”, the value
in the trash will be returned. In other words, some value will always
be returned unless the key has never been written to the store (since
the last merge).
Sourcepub async fn get_version<K, V>(
&self,
slot: u8,
k: &K,
version: Version,
) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
pub async fn get_version<K, V>(
&self,
slot: u8,
k: &K,
version: Version,
) -> Result<Option<V>>where
K: Serialize,
V: DeserializeOwned,
Returns the specified version of the value with the given slot and key.
Sourcepub async fn versions<K>(&self, slot: u8, k: &K) -> Result<Vec<Version>>where
K: Serialize,
pub async fn versions<K>(&self, slot: u8, k: &K) -> Result<Vec<Version>>where
K: Serialize,
Returns all the versions contained in the store for the given slot and key, ordered from earliest to latest version.
Since all keys are stored in memory, this operation is quite fast as it does not need to access the persistent storage.
Sourcepub async fn last_updated(&self) -> Result<Option<u64>>
pub async fn last_updated(&self) -> Result<Option<u64>>
Returns the timestamp of the last write to the store (in milliseconds since the Unix epoch).
Sourcepub async fn keys<K: DeserializeOwned>(&self, slot: u8) -> Result<Vec<K>>
pub async fn keys<K: DeserializeOwned>(&self, slot: u8) -> Result<Vec<K>>
Returns all non-removed keys of the specified index in the store.
Since all keys are stored in memory, this operation is quite fast as it does not need to access the persistent storage.
Sourcepub fn insert<K, V>(&mut self, slot: u8, k: K, v: V) -> Result<()>
pub fn insert<K, V>(&mut self, slot: u8, k: K, v: V) -> Result<()>
Inserts a key-value pair in the store, superseding older versions.
All inserts are buffered in memory and only persisted at the end of a transaction. If an insert is later followed by another insert with the same key in the same transaction, only the second insert is written to storage, as from the point of view of the transaction both inserts happen at the same time and thus only the last one for each key must be stored as a new version in the store.
Sourcepub fn remove<K>(&mut self, slot: u8, k: K) -> Result<()>where
K: Serialize,
pub fn remove<K>(&mut self, slot: u8, k: K) -> Result<()>where
K: Serialize,
Removes the value associated with the given slot and key from the store (and moves it to the trash).
All removes are buffered in memory and only persisted at the end of the transaction. Removing a key does not purge the associated value from the store, instead it simply adds a new version that marks the key as removed, while keeping the old versions of the key accessible. As a result, this acts like a “move to trash” operation and allows the value to be restored from the trash if desired. The trash will be emptied when the store is merged, at which point the removed value will be purged from the store.