1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
// Copyright 2016 FullContact, Inc // // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your // option. This file may not be copied, modified, or distributed // except according to those terms. //! Near-zero-cost, mostly-safe idiomatic bindings to LMDB. //! //! This crate provides an interface to LMDB which as much as possible is not //! abstracted from the model LMDB itself provides, except as necessary to //! integrate with the borrow checker. This means that you don't get easy //! iterators, but also that you can do almost anything with LMDB through these //! bindings as you can through C. //! //! # Example //! //! ``` //! extern crate lmdb_zero as lmdb; //! extern crate tempdir; //! //! # fn main() { //! # let tmp = tempdir::TempDir::new_in(".", "lmdbzero").unwrap(); //! # example(tmp.path().to_str().unwrap()); //! # } //! # //! fn example(path: &str) { //! // Create the environment, that is, the file containing the database(s). //! // This is unsafe because you need to ensure certain things about the //! // host environment that these bindings can't help you with. //! let env = unsafe { //! lmdb::EnvBuilder::new().unwrap().open( //! path, lmdb::open::Flags::empty(), 0o600).unwrap() //! }; //! // Open the default database. //! let db = lmdb::Database::open( //! &env, None, &lmdb::DatabaseOptions::defaults()) //! .unwrap(); //! { //! // Write some data in a transaction //! let txn = lmdb::WriteTransaction::new(&env).unwrap(); //! // An accessor is used to control memory access. //! // NB You can only get the accessor from the transaction once. //! { //! let mut access = txn.access(); //! access.put(&db, "Germany", "Berlin", lmdb::put::Flags::empty()).unwrap(); //! access.put(&db, "France", "Paris", lmdb::put::Flags::empty()).unwrap(); //! access.put(&db, "Latvia", "Rīga", lmdb::put::Flags::empty()).unwrap(); //! } //! // Commit the changes so they are visible to later transactions //! txn.commit().unwrap(); //! } //! //! { //! // Now let's read the data back //! let txn = lmdb::ReadTransaction::new(&env).unwrap(); //! let access = txn.access(); //! //! // Get the capital of Latvia. Note that the string is *not* copied; the //! // reference actually points into the database memory, and is valid //! // until the transaction is dropped or the accessor is mutated. //! let capital_of_latvia: &str = access.get(&db, "Latvia").unwrap(); //! assert_eq!("Rīga", capital_of_latvia); //! //! // We can also use cursors to move over the contents of the database. //! let mut cursor = txn.cursor(&db).unwrap(); //! assert_eq!(("France", "Paris"), cursor.first(&access).unwrap()); //! assert_eq!(("Germany", "Berlin"), cursor.next(&access).unwrap()); //! assert_eq!(("Latvia", "Rīga"), cursor.next(&access).unwrap()); //! assert!(cursor.next::<str,str>(&access).is_err()); //! } //! } //! ``` //! //! # Anatomy of this crate //! //! `Environment` is the top-level structure. It is created with an //! `EnvBuilder`. An `Environment` is a single file (by default in a //! subdirectory) which stores the actual data of all the databases it //! contains. It corresponds to an `MDB_env` in the C API. //! //! A `Database` is a single table of key/value pairs within an environment. //! Each environment has a single anonymous database, and may contain a number //! of named databases. Note that if you want to use named databases, you need //! to use `EnvBuilder::set_maxdbs` before creating the `Environment` to make //! room for the handles. A database can only have one `Database` handle per //! environment at a time. //! //! All accesses to the data within an environment are done through //! transactions. For this, there are the `ReadTransaction` and //! `WriteTransaction` structs. Both of these deref to a `ConstTransaction`, //! which provides most of the read-only functionality and can be used for //! writing code that can run within either type of transaction. Note that read //! transactions are far cheaper than write transactions. //! //! `ReadTransaction`s can be reused by using `reset()` to turn them into //! `ResetTransaction`s and then `refresh()` to turn them into fresh //! `ReadTransaction`s. //! //! One unusual property of this crate are the `ConstAccessor` and //! `WriteAccessor` structs, which are obtained once from a transaction and //! used to perform actual data manipulation. These are needed to work with the //! borrow checker: Cursors have a lifetime bound by their transaction and thus //! borrow it, so we need something else to permit borrowing mutable data. The //! accessors reflect this borrowing: Reading from the database requires an //! immutable borrow of the accessor, while writing (which may invalidate //! pointers) requires a mutable borrow of the accessor, thus causing the //! borrow checker to ensure that all read accesses are disposed before any //! write. //! //! Finally, the `Cursor` struct can be created from a transaction to permit //! more flexible access to a database. Each `Cursor` corresponds to a //! `MDB_cursor`. Accessing data through a cursor requires borrowing //! appropriately from the accessor of the transaction owning the cursor. //! //! If you want to define your own types to store in the database, see the //! `lmdb_zero::traits` submodule. //! //! # Lifetimes //! //! Lmdb-zero heavily uses lifetime parameters to allow user code to safely //! retain handles into LMDB without extra runtime overhead. //! //! While this makes the library very flexible, it also makes it somewhat //! harder to use when its types need to be referenced explicitly, for example //! as struct members. The documentation for each type with lifetime parameters //! therefore includes a short discussion of how the lifetimes are intended to //! interact and how best to work with them. //! //! # Major Differences from the LMDB C API //! //! Databases cannot be created or destroyed within a transaction due to the //! awkward memory management semantics. For similar reasons, opening a //! database more than once is not permitted (though note that LMDB doesn't //! strictly allow this either --- it just silently returns an existing //! handle). //! //! Access to data within the environment is guarded by transaction-specific //! "accessors", which must be used in conjunction with the cursor or //! transaction. This is how these bindings integrate with the borrow checker. //! //! APIs which obtain a reference to the owner of an object are not supported. //! //! Various APIs which radically change behaviour (including memory semantics) //! in response to flags are separated into different calls which each express //! their memory semantics clearly. //! //! # Non-Zero Cost //! //! There are three general areas where this wrapper adds non-zero-cost //! abstractions: //! //! - Opening and closing databases adds locking overhead, since in LMDB it is //! unsynchronised. This shouldn't have much impact since one rarely opens //! and closes databases at a very high rate. //! //! - There is additional overhead in tracking what database handles are //! currently open so that attempts to reopen one can be prevented. //! //! - Cursors and transactions track their owners separately. Additionally, //! when two are used in conjunction, a runtime test is required to ensure //! that they actually can be used together. This means that the handle //! values are slightly larger and some function calls have an extra (very //! predictable) branch if the optimiser does not optimise the branch away //! entirely. //! //! # Using Zero-Copy //! //! This crate is primarily focussed on supporting zero-copy on all operations //! where this is possible. The examples above demonstrate one aspect of this: //! the `&str`s returned when querying for items are pointers into the database //! itself, valid as long as the accessor is. //! //! The main traits to look at are `lmdb_zero::traits::AsLmdbBytes` and //! `lmdb_zero::traits::FromLmdbBytes`, which are used to cast between byte //! arrays and the types to be stored in the database. //! `lmdb_zero::traits::FromReservedLmdbBytes` is used if you want to use the //! `reserve` methods (in which you write the key only to the database and get //! a pointer to a value to fill in after the fact). If you have a //! `#[repr(C)]`, `Copy` struct, you can also use `lmdb_zero::traits::LmdbRaw` //! if you just want to shove the raw struct itself into the database. All of //! these have caveats which can be found on the struct documentation. //! //! Be aware that using zero-copy to save anything more interesting than byte //! strings means your databases will not be portable to other architectures. //! This mainly concerns byte-order, but types like `usize` whose size varies //! by platform can also cause problems. //! //! # Notes on Memory Safety //! //! It is not possible to use lmdb-zero without at least one unsafe block, //! because doing anything with a memory-mapped file requires making //! assumptions about the host environment. Lmdb-zero is not in a position to //! decide these assumptions, and so they are passed up to the caller. //! //! However, if these assumptions are met, it should be impossible to cause //! memory unsafety (eg, aliasing mutable references; dangling pointers; buffer //! under/overflows) by use of lmdb-zero's safe API. //! //! # Unavailable LMDB APIs //! //! - `mdb_env_copy`, `mdb_env_copyfd`: Only the `2`-suffixed versions that //! take flags are exposed. //! //! - `mdb_env_set_userctx`, `mdb_env_get_userctx`: Not generally useful for //! Rust; unclear how ownership would be expressed; would likely end up forcing //! an almost-never-used generic arg on `Environment` on everyone. //! //! - `mdb_env_set_assert`: Does not seem useful enough to expose. //! //! - `mdb_txn_env`, `mdb_cursor_txn`, `mdb_cursor_dbi`: Would allow violating //! borrow semantics. //! //! - `mdb_cmp`, `mdb_dcmp`: Doesn't seem useful; this would basically be a //! reinterpret cast from the input values to whatever the table comparator //! expects and then invoking the `Ord` implementation. If the types match, //! this is strictly inferior to just using `Ord` directly; if they don't, it //! at best is obfuscating, and at worst completely broken. //! //! - `mdb_set_relfunc`, `mdb_set_relctx`: Currently a noop in LMDB. Even if it //! weren't, it is unlikely that there is any remotely safe or convenient way //! to provide an interface to it. //! //! - `mdb_reader_list`: Doesn't seem useful enough to expose. #![deny(missing_docs)] extern crate liblmdb_sys as ffi; extern crate libc; #[macro_use] extern crate bitflags; use std::ffi::CStr; pub use ffi::mdb_mode_t as FileMode; pub use ffi::mdb_filehandle_t as Fd; macro_rules! lmdb_call { ($x:expr) => { { let code = $x; if 0 != code { return Err($crate::Error::Code(code)); } } } } /// Returns the LMDB version as a string. pub fn version_str() -> &'static str { let mut major: libc::c_int = 0; let mut minor: libc::c_int = 0; let mut rev: libc::c_int = 0; unsafe { CStr::from_ptr(ffi::mdb_version(&mut major, &mut minor, &mut rev)) .to_str().unwrap_or("(invalid)") } } /// Returns the LMDB version as (major, minor, revision). pub fn version() -> (i32, i32, i32) { let mut major: libc::c_int = 0; let mut minor: libc::c_int = 0; let mut rev: libc::c_int = 0; unsafe { ffi::mdb_version(&mut major, &mut minor, &mut rev); } (major as i32, minor as i32, rev as i32) } /// Empty type used to indicate "don't care" when reading values from LMDB. /// /// `FromLmdbBytes` is implemented for this type by simply returning its only /// value without inspecting anything. pub struct Ignore; mod mdb_vals; mod ffi2; pub mod error; pub use error::{Error, Result}; mod env; pub use env::{open, copy, EnvBuilder, Environment, Stat, EnvInfo}; mod dbi; pub use dbi::{db, Database, DatabaseOptions}; pub mod traits; mod unaligned; pub use unaligned::{Unaligned, unaligned}; mod tx; pub use tx::{ConstTransaction, ReadTransaction, WriteTransaction}; pub use tx::ResetTransaction; pub use tx::{ConstAccessor, WriteAccessor}; pub use tx::{put, del}; mod cursor; pub use cursor::{StaleCursor, Cursor}; mod iter; pub use iter::{CursorIter, MaybeOwned};