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* `MemoryStore` is using the memory
21* `RocksDbStore` is a disk-based key-value store
22* `DynamoDbStore` is the AWS-based DynamoDB service.
23* `ScyllaDbStore` is a cloud-based Cassandra-compatible database.
24* `ServiceStoreClient` 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::KeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.KeyValueStore.html).
27The trait decomposes into a [`store::ReadableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.ReadableKeyValueStore.html)
28and a [`store::WritableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.WritableKeyValueStore.html).
29In addition, there is a [`store::AdminKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.AdminKeyValueStore.html)
30which gives some functionalities for working with stores.
31A context is the combination of a client and a base key (of type `Vec<u8>`).
32
33## Views.
34
35A view is a container whose data lies in one of the above-mentioned databases.
36When the container is modified the modification lies first in the view before
37being committed to the database. In technical terms, a view implements the trait `View`.
38
39The specific functionalities of the trait `View` are the following:
40* `context` for obtaining a reference to the storage context of the view.
41* `load` for loading the view from a specific context.
42* `rollback` for canceling all modifications that were not committed thus far.
43* `clear` for clearing the view, in other words for reverting it to its default state.
44* `flush` for persisting the changes to storage.
45
46The following views implement the `View` trait:
47* `RegisterView` implements the storing of a single data.
48* `LogView` implements a log, which is a list of entries that can be expanded.
49* `QueueView` implements a queue, which is a list of entries that can be expanded and reduced.
50* `MapView` implements a map with keys and values.
51* `SetView` implements a set with keys.
52* `CollectionView` implements a map whose values are views themselves.
53* `ReentrantCollectionView` implements a map for which different keys can be accessed independently.
54* `ViewContainer<C>` implements a `KeyValueStore` and is used internally.
55
56The `LogView` can be seen as an analog of `VecDeque` while `MapView` is an analog of `BTreeMap`.
57*/
58
59#![deny(missing_docs)]
60#![deny(clippy::large_futures)]
61// These traits have `Send` variants where possible.
62#![allow(async_fn_in_trait)]
63
64/// The definition of the batches for writing in the database.
65pub mod batch;
66
67/// The `KeyValueStore` trait and related definitions.
68pub mod store;
69
70/// The `Context` trait and related definitions.
71pub mod context;
72
73/// Common definitions used for views and backends.
74pub mod common;
75
76mod error;
77pub use error::ViewError;
78
79mod future_sync_ext;
80#[doc(hidden)]
81pub use future_sync_ext::FutureSyncExt;
82
83/// Elementary data-structures implementing the [`views::View`] trait.
84pub mod views;
85
86/// Backend implementing the [`crate::store::KeyValueStore`] trait.
87pub mod backends;
88
89/// Support for metrics.
90#[cfg(with_metrics)]
91pub mod metrics;
92
93/// GraphQL implementations.
94#[cfg(with_graphql)]
95mod graphql;
96
97/// Functions for random generation
98#[cfg(with_testing)]
99pub mod random;
100
101/// Helper types for tests.
102#[cfg(with_testing)]
103pub mod test_utils;
104
105#[cfg(with_dynamodb)]
106pub use backends::dynamo_db;
107#[cfg(with_indexeddb)]
108pub use backends::indexed_db;
109#[cfg(with_metrics)]
110pub use backends::metering;
111#[cfg(with_rocksdb)]
112pub use backends::rocks_db;
113#[cfg(with_scylladb)]
114pub use backends::scylla_db;
115pub use backends::{journaling, lru_caching, memory, value_splitting};
116pub use views::{
117    bucket_queue_view, collection_view, hashable_wrapper, key_value_store_view, log_view, map_view,
118    queue_view, reentrant_collection_view, register_view, set_view,
119};
120/// Re-exports used by the derive macros of this library.
121#[doc(hidden)]
122pub use {generic_array, sha3};
linera_views/lib.rs

linera_views/
lib.rs
