linera-views 0.15.22

A library mapping complex data structures onto a key-value store, used by the Linera protocol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

// Copyright (c) Zefchain Labs, Inc.
// SPDX-License-Identifier: Apache-2.0

/*!
This module is used in the Linera protocol to map complex data structures onto a
key-value store. The central notion is a [`views::View`](https://docs.rs/linera-views/latest/linera_views/views/trait.View.html)
which can be loaded from storage, modified in memory, and then committed (i.e. the changes are atomically persisted in storage).

The package provides essentially two functionalities:
* An abstraction to access databases.
* Several containers named views for storing data modeled on classical ones.

See `DESIGN.md` for more details.

## The supported databases.

The databases supported are of the NoSQL variety and they are key-value stores.

We provide support for the following databases:
* `MemoryDatabase` is using the memory
* `RocksDbDatabase` is a disk-based key-value store
* `ScyllaDbDatabase` is a cloud-based Cassandra-compatible database.
* `StorageServiceDatabase` is a gRPC-based storage that uses either memory or RocksDB. It is available in `linera-storage-service`.

The corresponding trait in the code is the [`crate::store::KeyValueDatabase`](https://docs.rs/linera-views/latest/linera_views/store/trait.KeyValueDatabase.html).
as well as [`crate::store::KeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.KeyValueStore.html).

The latter trait decomposes into a [`store::ReadableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.ReadableKeyValueStore.html)
and a [`store::WritableKeyValueStore`](https://docs.rs/linera-views/latest/linera_views/store/trait.WritableKeyValueStore.html).

A context is the combination of a client and a base key (of type `Vec<u8>`).

## Views.

A view is a container whose data lies in one of the above-mentioned databases.

When the container is modified the modification lies first in the view before
being committed to the database. In technical terms, a view implements the trait `View`.

The specific functionalities of the trait `View` are the following:
* `context` for obtaining a reference to the storage context of the view.
* `load` for loading the view from a specific context.
* `rollback` for canceling all modifications that were not committed thus far.
* `clear` for clearing the view, in other words for reverting it to its default state.
* `flush` for persisting the changes to storage.

The following views implement the `View` trait:
* `RegisterView` implements the storing of a single data.
* `LogView` implements a log, which is a list of entries that can be expanded.
* `QueueView` implements a queue, which is a list of entries that can be expanded and reduced.
* `MapView` implements a map with keys and values.
* `SetView` implements a set with keys.
* `CollectionView` implements a map whose values are views themselves.
* `ReentrantCollectionView` implements a map for which different keys can be accessed independently.
* `ViewContainer<C>` implements a `KeyValueStore` and is used internally.

The `LogView` can be seen as an analog of `VecDeque` while `MapView` is an analog of `BTreeMap`.
*/

#![deny(missing_docs)]
// These traits have `Send` variants where possible.
#![allow(async_fn_in_trait)]

/// The definition of the batches for writing in the database.
pub mod batch;

/// The `KeyValueDatabase` and `KeyValueStore` traits and related definitions.
pub mod store;

/// The `Context` trait and related definitions.
pub mod context;

/// Common definitions used for views and backends.
pub mod common;

/// Definitions for the LRU cache.
pub mod lru_prefix_cache;

mod error;
pub use error::ViewError;

/// Elementary data-structures implementing the [`views::View`] trait.
pub mod views;

/// Backend implementing the [`crate::store::KeyValueStore`] trait.
pub mod backends;

/// Support for metrics.
#[cfg(with_metrics)]
pub mod metrics;

/// GraphQL implementations.
#[cfg(with_graphql)]
mod graphql;

/// Functions for random generation
#[cfg(with_testing)]
pub mod random;

/// Helper types for tests.
#[cfg(with_testing)]
pub mod test_utils;

#[cfg(with_indexeddb)]
pub use backends::indexed_db;
#[cfg(with_metrics)]
pub use backends::metering;
#[cfg(with_rocksdb)]
pub use backends::rocks_db;
#[cfg(with_scylladb)]
pub use backends::scylla_db;
pub use backends::{journaling, lru_caching, memory, value_splitting};
/// Re-exports used by the derive macros of this library.
#[doc(hidden)]
#[allow(deprecated)]
pub use generic_array;
#[doc(hidden)]
pub use sha3;
/// Expose the created views.
pub use views::{
    bucket_queue_view, collection_view, hashable_wrapper, historical_hash_wrapper,
    key_value_store_view, lazy_register_view, log_view, map_view, queue_view,
    reentrant_collection_view, register_view, set_view,
};

/// Registers every metric this crate declares.
///
/// Without this, a metric is only exported after the code path that observes it has run, so a
/// rarely-taken path leaves its panels blank and makes a routine restart look like the metric
/// was removed.
#[cfg(with_metrics)]
pub fn init_metrics() {
    linera_base::init_metrics();
    metrics::init_metrics();
    backends::journaling::metrics::init_metrics();
    backends::lru_caching::metrics::init_metrics();
    backends::value_splitting::metrics::init_metrics();
    views::bucket_queue_view::metrics::init_metrics();
    views::collection_view::metrics::init_metrics();
    views::historical_hash_wrapper::metrics::init_metrics();
    views::key_value_store_view::metrics::init_metrics();
    views::lazy_register_view::metrics::init_metrics();
    views::log_view::metrics::init_metrics();
    views::map_view::metrics::init_metrics();
    views::queue_view::metrics::init_metrics();
    views::reentrant_collection_view::metrics::init_metrics();
    views::register_view::metrics::init_metrics();
    views::set_view::metrics::init_metrics();
}