linera_views/
lib.rs

1// Copyright (c) Zefchain Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4/*!
5This module is used in the Linera protocol to map complex data structures onto a
6key-value store. The central notion is a [`views::View`](https://docs.rs/linera-views/latest/linera_views/views/trait.View.html)
7which can be loaded from storage, modified in memory, and then committed (i.e. the changes are atomically persisted in storage).
8
9The package provides essentially two functionalities:
10* An abstraction to access databases.
11* Several containers named views for storing data modeled on classical ones.
12
13See `DESIGN.md` for more details.
14
15## The supported databases.
16
17The databases supported are of the NoSQL variety and they are key-value stores.
18
19We provide support for the following databases:
20* `MemoryDatabase` is using the memory
21* `RocksDbDatabase` is a disk-based key-value store
22* `DynamoDbDatabase` is the AWS-based DynamoDB service.
23* `ScyllaDbDatabase` is a cloud-based Cassandra-compatible database.
24* `StorageServiceDatabase` is a gRPC-based storage that uses either memory or RocksDB. It is available in `linera-storage-service`.
25
26The corresponding trait in the code is the [`crate::store::KeyValueDatabase`](https://docs.rs/linera-views/latest/linera_views/store/trait.KeyValueDatabase.html).
27as well as [`crate::store::KeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.KeyValueStore.html).
28
29The latter trait decomposes into a [`store::ReadableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.ReadableKeyValueStore.html)
30and a [`store::WritableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.WritableKeyValueStore.html).
31
32A context is the combination of a client and a base key (of type `Vec<u8>`).
33
34## Views.
35
36A view is a container whose data lies in one of the above-mentioned databases.
37
38When the container is modified the modification lies first in the view before
39being committed to the database. In technical terms, a view implements the trait `View`.
40
41The specific functionalities of the trait `View` are the following:
42* `context` for obtaining a reference to the storage context of the view.
43* `load` for loading the view from a specific context.
44* `rollback` for canceling all modifications that were not committed thus far.
45* `clear` for clearing the view, in other words for reverting it to its default state.
46* `flush` for persisting the changes to storage.
47
48The following views implement the `View` trait:
49* `RegisterView` implements the storing of a single data.
50* `LogView` implements a log, which is a list of entries that can be expanded.
51* `QueueView` implements a queue, which is a list of entries that can be expanded and reduced.
52* `MapView` implements a map with keys and values.
53* `SetView` implements a set with keys.
54* `CollectionView` implements a map whose values are views themselves.
55* `ReentrantCollectionView` implements a map for which different keys can be accessed independently.
56* `ViewContainer<C>` implements a `KeyValueStore` and is used internally.
57
58The `LogView` can be seen as an analog of `VecDeque` while `MapView` is an analog of `BTreeMap`.
59*/
60
61#![deny(missing_docs)]
62#![deny(clippy::large_futures)]
63// These traits have `Send` variants where possible.
64#![allow(async_fn_in_trait)]
65
66/// The definition of the batches for writing in the database.
67pub mod batch;
68
69/// The `KeyValueDatabase` and `KeyValueStore` traits and related definitions.
70pub mod store;
71
72/// The `Context` trait and related definitions.
73pub mod context;
74
75/// Common definitions used for views and backends.
76pub mod common;
77
78mod error;
79pub use error::ViewError;
80
81mod future_sync_ext;
82#[doc(hidden)]
83pub use future_sync_ext::FutureSyncExt;
84
85/// Elementary data-structures implementing the [`views::View`] trait.
86pub mod views;
87
88/// Backend implementing the [`crate::store::KeyValueStore`] trait.
89pub mod backends;
90
91/// Support for metrics.
92#[cfg(with_metrics)]
93pub mod metrics;
94
95/// GraphQL implementations.
96#[cfg(with_graphql)]
97mod graphql;
98
99/// Functions for random generation
100#[cfg(with_testing)]
101pub mod random;
102
103/// Helper types for tests.
104#[cfg(with_testing)]
105pub mod test_utils;
106
107#[cfg(with_dynamodb)]
108pub use backends::dynamo_db;
109#[cfg(with_indexeddb)]
110pub use backends::indexed_db;
111#[cfg(with_metrics)]
112pub use backends::metering;
113#[cfg(with_rocksdb)]
114pub use backends::rocks_db;
115#[cfg(with_scylladb)]
116pub use backends::scylla_db;
117pub use backends::{journaling, lru_caching, memory, value_splitting};
118pub use views::{
119    bucket_queue_view, collection_view, hashable_wrapper, key_value_store_view, log_view, map_view,
120    queue_view, reentrant_collection_view, register_view, set_view,
121};
122/// Re-exports used by the derive macros of this library.
123#[doc(hidden)]
124pub use {generic_array, sha3};
linera_views/lib.rs

linera_views/
lib.rs
