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
62/// The definition of the batches for writing in the database.
63pub mod batch;
64
65/// The `KeyValueStore` trait and related definitions.
66pub mod store;
67
68/// The `Context` trait and related definitions.
69pub mod context;
70
71/// Common definitions used for views and backends.
72pub mod common;
73
74/// Elementary data-structures implementing the [`views::View`] trait.
75pub mod views;
76
77/// Backend implementing the [`crate::store::KeyValueStore`] trait.
78pub mod backends;
79
80/// Support for metrics.
81#[cfg(with_metrics)]
82pub mod metrics;
83
84/// GraphQL implementations.
85mod graphql;
86
87/// Functions for random generation
88#[cfg(with_testing)]
89pub mod random;
90
91/// Helper types for tests.
92#[cfg(with_testing)]
93pub mod test_utils;
94
95#[cfg(with_dynamodb)]
96pub use backends::dynamo_db;
97#[cfg(with_indexeddb)]
98pub use backends::indexed_db;
99#[cfg(with_metrics)]
100pub use backends::metering;
101#[cfg(with_rocksdb)]
102pub use backends::rocks_db;
103#[cfg(with_scylladb)]
104pub use backends::scylla_db;
105pub use backends::{journaling, lru_caching, memory, value_splitting};
106pub use views::{
107    bucket_queue_view, collection_view, hashable_wrapper, key_value_store_view, log_view, map_view,
108    queue_view, reentrant_collection_view, register_view, set_view,
109};
110/// Re-exports used by the derive macros of this library.
111#[doc(hidden)]
112pub use {
113    async_lock, async_trait::async_trait, futures, generic_array, linera_base::crypto, serde, sha3,
114};
linera_views/lib.rs

linera_views/
lib.rs
