limousine_engine/
lib.rs

1//! `limousine_engine` provides a procedural macro to automatically
2//! generate an hybrid key-value store design consisting of both
3//! classical and learned components.
4//!
5//! **As of the current version, learned components are not yet fully
6//! supported.**
7//!
8//! ```ignore
9//! use limousine_engine::prelude::*;
10//!
11//! create_kv_store! {
12//!     name: ExampleStore,
13//!     layout: [
14//!         btree_top(),
15//!         pgm(epsilon = 8),
16//!         pgm(epsilon = 8),
17//!         btree(fanout = 32),
18//!         btree(fanout = 32, persist),
19//!         btree(fanout = 64, persist)   
20//!     ]
21//! }
22//! ```
23//!
24//! To generate a design, we provide a name for the structure and a
25//! layout description which consists of a stack of components. For
26//! instance in the above example, the key-value store consists of
27//! a base layer of on-disk BTree nodes of fanout 64, underneath a  
28//! layer of on on-disk BTree nodes with fanout 32, underneath an
29//! in-memory layer of BTree nodes with fanout 32. On top of this, we
30//! have two in-memory PGM learned layers with epsilon parameters of 8,
31//! and a tiny in-memory BTree as a top layer.
32//!
33//! **Since learned components are not yet fully supported, the above example
34//! will not compile. To get a working key-value store in the current version,
35//! we should only use BTree components.**
36//!
37//! ```
38//! use limousine_engine::prelude::*;
39//!
40//! create_kv_store! {
41//!     name: ExampleStore,
42//!     layout: [
43//!         btree_top(),
44//!         btree(fanout = 8),
45//!         btree(fanout = 8),
46//!         btree(fanout = 32),
47//!         btree(fanout = 32, persist),
48//!         btree(fanout = 64, persist)   
49//!     ]
50//! }
51//! ```
52//!
53//! We can then use these generated data structures to perform queries:
54//!
55//! ```ignore
56//! // Load the first two layer of the index from memory
57//! let index: ExampleStore<u128, u128> = ExampleStore::open("data/index")?;
58//!
59//! index.insert(10, 50)?;
60//! index.insert(20, 60)?;
61//! index.insert(30, 70)?;
62//! index.insert(40, 80)?;
63//!
64//! assert_eq!(index.search(10)?, Some(50));
65//! ```
66#![deny(missing_docs)]
67
68/// Include this at the top of the file when materializing a hybrid index or using a hybrid index.
69pub mod prelude {
70    pub use limousine_derive::create_kv_store;
71
72    pub use limousine_core::KVStore;
73    pub use limousine_core::PersistedKVStore;
74}
75
76pub use limousine_core::Result;
77
78#[doc(hidden)]
79pub use limousine_core as private;