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

linera_views/
lib.rs
