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

typed_store/
lib.rs
