typed_store/
lib.rs

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

typed_store/
lib.rs
