smolheed/
lib.rs

1//! Crate `heed` is a high-level wrapper of [LMDB], high-level doesn't mean heavy (think about Rust).
2//!
3//! It provides you a way to store types in LMDB without any limit and with a minimal overhead as possible.
4//!
5//! The Lightning Memory-Mapped Database (LMDB) directly maps files parts into main memory, combined
6//! with the zerocopy library allows us to safely zero-copy parse and serialize Rust types into LMDB.
7//!
8//! [LMDB]: https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database
9//!
10//! # Examples
11//!
12//! Discern let you open a database, that will support some typed key/data
13//! and ensures, at compile time, that you'll write those types and not others.
14//!
15//! ```
16//! use std::fs;
17//! use std::path::Path;
18//! use smolheed::{EnvOpenOptions, Database};
19//!
20//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
21//! fs::create_dir_all(Path::new("target").join("zerocopy.mdb"))?;
22//! let env = EnvOpenOptions::new().open(Path::new("target").join("zerocopy.mdb"))?;
23//!
24//! // we will open the default unamed database
25//! let db = env.create_database(None)?;
26//!
27//! // opening a write transaction
28//! let mut wtxn = env.write_txn()?;
29//! db.put(&mut wtxn, "seven", 7_i32.to_be_bytes())?;
30//! db.put(&mut wtxn, "zero", 0_i32.to_be_bytes())?;
31//! db.put(&mut wtxn, "five", 5_i32.to_be_bytes())?;
32//! db.put(&mut wtxn, "three", 3_i32.to_be_bytes())?;
33//! wtxn.commit()?;
34//!
35//! // opening a read transaction
36//! // to check if those values are now available
37//! let mut rtxn = env.read_txn()?;
38//!
39//! let ret = db.get(&rtxn, "zero")?;
40//! assert_eq!(ret, Some(&0_i32.to_be_bytes()[..]));
41//!
42//! let ret = db.get(&rtxn, "five")?;
43//! assert_eq!(ret, Some(&5_i32.to_be_bytes()[..]));
44//! # Ok(()) }
45//! ```
46
47mod cursor;
48mod database;
49mod env;
50mod iter;
51mod mdb;
52mod txn;
53
54use self::cursor::{RoCursor, RwCursor};
55pub use self::database::Database;
56pub use self::env::{env_closing_event, CompactionOption, Env, EnvClosingEvent, EnvOpenOptions};
57pub use self::iter::{RoIter, RoRevIter, RwIter, RwRevIter};
58pub use self::iter::{RoPrefix, RoRevPrefix, RwPrefix, RwRevPrefix};
59pub use self::iter::{RoRange, RoRevRange, RwRange, RwRevRange};
60pub use self::mdb::error::Error as MdbError;
61use self::mdb::ffi::{from_val, into_val};
62pub use self::mdb::flags;
63pub use self::txn::{RoTxn, RwTxn};
64
65use std::{error, fmt, io, result};
66
67/// An error that encapsulates all possible errors in this crate.
68#[derive(Debug)]
69pub enum Error {
70    Io(io::Error),
71    Mdb(MdbError),
72    DatabaseClosing,
73}
74
75impl fmt::Display for Error {
76    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
77        match self {
78            Error::Io(error) => write!(f, "{}", error),
79            Error::Mdb(error) => write!(f, "{}", error),
80            Error::DatabaseClosing => {
81                f.write_str("database is in a closing phase, you can't open it at the same time")
82            }
83        }
84    }
85}
86
87impl error::Error for Error {}
88
89impl From<MdbError> for Error {
90    fn from(error: MdbError) -> Error {
91        match error {
92            MdbError::Other(e) => Error::Io(io::Error::from_raw_os_error(e)),
93            _ => Error::Mdb(error),
94        }
95    }
96}
97
98impl From<io::Error> for Error {
99    fn from(error: io::Error) -> Error {
100        Error::Io(error)
101    }
102}
103
104pub type Result<T> = result::Result<T, Error>;
smolheed/lib.rs

smolheed/
lib.rs
