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

typed_store/
lib.rs
