typed_store/
lib.rs

1// Copyright (c) 2021, Facebook, Inc. and its affiliates
2// Copyright (c) Mysten Labs, Inc.
3// Modifications Copyright (c) 2024 IOTA Stiftung
4// SPDX-License-Identifier: Apache-2.0
5
6#![warn(
7    future_incompatible,
8    nonstandard_style,
9    rust_2018_idioms,
10    rust_2021_compatibility
11)]
12
13// Re-export rocksdb so that consumers can use the version of rocksdb via
14// typed-store
15pub use rocksdb;
16
17pub mod database;
18pub mod traits;
19pub use traits::{DbIterator, Map};
20pub mod memstore;
21pub mod metrics;
22pub mod rocks;
23pub mod test_db;
24mod util;
25pub use metrics::DBMetrics;
26pub use typed_store_error::TypedStoreError;
27pub use util::be_fix_int_ser;
28
29pub type StoreError = typed_store_error::TypedStoreError;
30
31/// A helper macro to simplify common operations for opening and debugging
32/// TypedStore (currently internally structs of DBMaps) It operates on a struct
33/// where all the members are DBMap<K, V> The main features are:
34/// 1. Flexible configuration of each table (column family) via defaults and
35///    overrides
36/// 2. Auto-generated `open` routine
37/// 3. Auto-generated `read_only_mode` handle
38/// 4. Auto-generated memory stats method
39/// 5. Other convenience features
40///
41/// 1. Flexible configuration: a. Static options specified at struct definition
42///
43/// The definer of the struct can specify the default options for each table
44/// using annotations We can also supply column family options on the default
45/// ones A user defined function of signature () -> Options can be provided for
46/// each table If a an override function is not specified, the default in
47/// `typed_store::rocks::default_db_options` is used
48/// ```
49/// use core::fmt::Error;
50///
51/// use typed_store::{
52///     DBMapUtils,
53///     rocks::{DBMap, DBOptions, MetricConf},
54/// };
55/// /// Define a struct with all members having type DBMap<K, V>
56///
57/// fn custom_fn_name1() -> DBOptions {
58///     DBOptions::default()
59/// }
60/// fn custom_fn_name2() -> DBOptions {
61///     let mut op = custom_fn_name1();
62///     op.options.set_write_buffer_size(123456);
63///     op
64/// }
65/// #[derive(DBMapUtils)]
66/// struct Tables {
67///     /// Specify custom options function `custom_fn_name1`
68///     #[default_options_override_fn = "custom_fn_name1"]
69///     table1: DBMap<String, String>,
70///     #[default_options_override_fn = "custom_fn_name2"]
71///     table2: DBMap<i32, String>,
72///     // Nothing specified so `typed_store::rocks::default_db_options` is used
73///     table3: DBMap<i32, String>,
74///     #[default_options_override_fn = "custom_fn_name1"]
75///     table4: DBMap<i32, String>,
76/// }
77/// ```
78///
79/// 2. Auto-generated `open` routine The function `open_tables_read_write` is
80///    generated which allows for specifying DB wide options and custom table
81///    configs as mentioned above
82///
83/// 3. Auto-generated `read_only_mode` handle This mode provides handle struct
84///    which opens the DB in read only mode and has certain features like
85///    dumping and counting the keys in the tables
86///
87/// Use the function `Tables::get_read_only_handle` which returns a handle that
88/// only allows read only features
89/// ```
90/// use core::fmt::Error;
91///
92/// use typed_store::{
93///     DBMapUtils,
94///     rocks::{DBMap, DBOptions},
95/// };
96/// /// Define a struct with all members having type DBMap<K, V>
97///
98/// fn custom_fn_name1() -> DBOptions {
99///     DBOptions::default()
100/// }
101/// fn custom_fn_name2() -> DBOptions {
102///     let mut op = custom_fn_name1();
103///     op.options.set_write_buffer_size(123456);
104///     op
105/// }
106/// #[derive(DBMapUtils)]
107/// struct Tables {
108///     /// Specify custom options function `custom_fn_name1`
109///     #[default_options_override_fn = "custom_fn_name1"]
110///     table1: DBMap<String, String>,
111///     #[default_options_override_fn = "custom_fn_name2"]
112///     table2: DBMap<i32, String>,
113///     // Nothing specified so `typed_store::rocks::default_db_options` is used
114///     table3: DBMap<i32, String>,
115///     #[default_options_override_fn = "custom_fn_name1"]
116///     table4: DBMap<i32, String>,
117/// }
118/// #[tokio::main]
119/// async fn main() -> Result<(), Error> {
120///     use typed_store::rocks::MetricConf;
121///     let primary_path = tempfile::tempdir()
122///         .expect("Failed to open temporary directory")
123///         .keep();
124///     let _ = Tables::open_tables_read_write(
125///         primary_path.clone(),
126///         typed_store::rocks::MetricConf::default(),
127///         None,
128///         None,
129///     );
130///
131///     // Get the read only handle
132///     let read_only_handle =
133///         Tables::get_read_only_handle(primary_path, None, None, MetricConf::default());
134///     // Use this handle for dumping
135///     let ret = read_only_handle.dump("table2", 100, 0).unwrap();
136///     Ok(())
137/// }
138/// ```
139/// 4. Auto-generated memory stats method `self.get_memory_usage` is derived to
140///    provide memory and cache usage
141///
142/// 5. Other convenience features `Tables::describe_tables` is used to get a
143///    list of the table names and key-value types as string in a BTreeMap
144///
145/// // Bad usage example
146/// // Structs fields most only be of type Store<K, V> or DMBap<K, V>
147/// // This will fail to compile with error `All struct members must be of type
148/// Store<K, V> or DMBap<K, V>` // #[derive(DBMapUtils)]
149/// // struct BadTables {
150/// //     table1: Store<String, String>,
151/// //     bad_field: u32,
152/// // #}
153pub use typed_store_derive::DBMapUtils;
typed_store/lib.rs

typed_store/
lib.rs
