rocksdb/
lib.rs

1// Copyright 2020 Tyler Neely
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15
16//! Rust wrapper for RocksDB.
17//!
18//! # Examples
19//!
20//! ```
21//! use rocksdb::{DB, Options};
22//! // NB: db is automatically closed at end of lifetime
23//! let tempdir = tempfile::Builder::new()
24//!     .prefix("_path_for_rocksdb_storage")
25//!     .tempdir()
26//!     .expect("Failed to create temporary path for the _path_for_rocksdb_storage");
27//! let path = tempdir.path();
28//! {
29//!    let db = DB::open_default(path).unwrap();
30//!    db.put(b"my key", b"my value").unwrap();
31//!    match db.get(b"my key") {
32//!        Ok(Some(value)) => println!("retrieved value {}", String::from_utf8(value).unwrap()),
33//!        Ok(None) => println!("value not found"),
34//!        Err(e) => println!("operational problem encountered: {}", e),
35//!    }
36//!    db.delete(b"my key").unwrap();
37//! }
38//! let _ = DB::destroy(&Options::default(), path);
39//! ```
40//!
41//! Opening a database and a single column family with custom options:
42//!
43//! ```
44//! use rocksdb::{DB, ColumnFamilyDescriptor, Options};
45//!
46//! let tempdir = tempfile::Builder::new()
47//!     .prefix("_path_for_rocksdb_storage_with_cfs")
48//!     .tempdir()
49//!     .expect("Failed to create temporary path for the _path_for_rocksdb_storage_with_cfs.");
50//! let path = tempdir.path();
51//! let mut cf_opts = Options::default();
52//! cf_opts.set_max_write_buffer_number(16);
53//! let cf = ColumnFamilyDescriptor::new("cf1", cf_opts);
54//!
55//! let mut db_opts = Options::default();
56//! db_opts.create_missing_column_families(true);
57//! db_opts.create_if_missing(true);
58//! {
59//!     let db = DB::open_cf_descriptors(&db_opts, path, vec![cf]).unwrap();
60//! }
61//! let _ = DB::destroy(&db_opts, path);
62//! ```
63//!
64
65#![warn(clippy::pedantic)]
66#![allow(
67    // Next `cast_*` lints don't give alternatives.
68    clippy::cast_possible_wrap, clippy::cast_possible_truncation, clippy::cast_sign_loss,
69    // Next lints produce too much noise/false positives.
70    clippy::module_name_repetitions, clippy::similar_names, clippy::must_use_candidate,
71    // '... may panic' lints.
72    // Too much work to fix.
73    clippy::missing_errors_doc,
74    // False positive: WebSocket
75    clippy::doc_markdown,
76    clippy::missing_safety_doc,
77    clippy::needless_pass_by_value,
78    clippy::ptr_as_ptr,
79    clippy::missing_panics_doc,
80    clippy::from_over_into,
81)]
82
83#[macro_use]
84mod ffi_util;
85
86pub mod backup;
87pub mod checkpoint;
88mod column_family;
89pub mod compaction_filter;
90pub mod compaction_filter_factory;
91mod comparator;
92mod db;
93mod db_iterator;
94mod db_options;
95mod db_pinnable_slice;
96mod env;
97mod iter_range;
98pub mod merge_operator;
99pub mod perf;
100mod prop_name;
101pub mod properties;
102mod slice_transform;
103mod snapshot;
104mod sst_file_writer;
105pub mod statistics;
106mod transactions;
107mod write_batch;
108
109pub use crate::{
110    column_family::{
111        AsColumnFamilyRef, BoundColumnFamily, ColumnFamily, ColumnFamilyDescriptor,
112        ColumnFamilyRef, ColumnFamilyTtl, DEFAULT_COLUMN_FAMILY_NAME,
113    },
114    compaction_filter::Decision as CompactionDecision,
115    db::{
116        DBAccess, DBCommon, DBWithThreadMode, LiveFile, MultiThreaded, Range, SingleThreaded,
117        ThreadMode, DB,
118    },
119    db_iterator::{
120        DBIterator, DBIteratorWithThreadMode, DBRawIterator, DBRawIteratorWithThreadMode,
121        DBWALIterator, Direction, IteratorMode,
122    },
123    db_options::{
124        BlockBasedIndexType, BlockBasedOptions, BlockBasedTablePinningTier,
125        BottommostLevelCompaction, Cache, ChecksumType, CompactOptions, CompactionPri,
126        CuckooTableOptions, DBCompactionStyle, DBCompressionType, DBPath, DBRecoveryMode,
127        DataBlockIndexType, FifoCompactOptions, FlushOptions, IngestExternalFileOptions,
128        KeyEncodingType, LogLevel, LruCacheOptions, MemtableFactory, Options,
129        PlainTableFactoryOptions, ReadOptions, ReadTier, UniversalCompactOptions,
130        UniversalCompactionStopStyle, WaitForCompactOptions, WriteBufferManager, WriteOptions,
131    },
132    db_pinnable_slice::DBPinnableSlice,
133    env::Env,
134    ffi_util::CStrLike,
135    iter_range::{IterateBounds, PrefixRange},
136    merge_operator::MergeOperands,
137    perf::{PerfContext, PerfMetric, PerfStatsLevel},
138    slice_transform::SliceTransform,
139    snapshot::{Snapshot, SnapshotWithThreadMode},
140    sst_file_writer::SstFileWriter,
141    transactions::{
142        OptimisticTransactionDB, OptimisticTransactionOptions, Transaction, TransactionDB,
143        TransactionDBOptions, TransactionOptions,
144    },
145    write_batch::{
146        WriteBatch, WriteBatchIterator, WriteBatchIteratorCf, WriteBatchWithTransaction,
147    },
148};
149
150use librocksdb_sys as ffi;
151
152use std::error;
153use std::fmt;
154
155/// RocksDB error kind.
156#[derive(Debug, Clone, PartialEq, Eq)]
157pub enum ErrorKind {
158    NotFound,
159    Corruption,
160    NotSupported,
161    InvalidArgument,
162    IOError,
163    MergeInProgress,
164    Incomplete,
165    ShutdownInProgress,
166    TimedOut,
167    Aborted,
168    Busy,
169    Expired,
170    TryAgain,
171    CompactionTooLarge,
172    ColumnFamilyDropped,
173    Unknown,
174}
175
176/// A simple wrapper round a string, used for errors reported from
177/// ffi calls.
178#[derive(Debug, Clone, PartialEq, Eq)]
179pub struct Error {
180    message: String,
181}
182
183impl Error {
184    fn new(message: String) -> Error {
185        Error { message }
186    }
187
188    pub fn into_string(self) -> String {
189        self.into()
190    }
191
192    /// Parse corresponding [`ErrorKind`] from error message.
193    pub fn kind(&self) -> ErrorKind {
194        match self.message.split(':').next().unwrap_or("") {
195            "NotFound" => ErrorKind::NotFound,
196            "Corruption" => ErrorKind::Corruption,
197            "Not implemented" => ErrorKind::NotSupported,
198            "Invalid argument" => ErrorKind::InvalidArgument,
199            "IO error" => ErrorKind::IOError,
200            "Merge in progress" => ErrorKind::MergeInProgress,
201            "Result incomplete" => ErrorKind::Incomplete,
202            "Shutdown in progress" => ErrorKind::ShutdownInProgress,
203            "Operation timed out" => ErrorKind::TimedOut,
204            "Operation aborted" => ErrorKind::Aborted,
205            "Resource busy" => ErrorKind::Busy,
206            "Operation expired" => ErrorKind::Expired,
207            "Operation failed. Try again." => ErrorKind::TryAgain,
208            "Compaction too large" => ErrorKind::CompactionTooLarge,
209            "Column family dropped" => ErrorKind::ColumnFamilyDropped,
210            _ => ErrorKind::Unknown,
211        }
212    }
213}
214
215impl AsRef<str> for Error {
216    fn as_ref(&self) -> &str {
217        &self.message
218    }
219}
220
221impl From<Error> for String {
222    fn from(e: Error) -> String {
223        e.message
224    }
225}
226
227impl error::Error for Error {
228    fn description(&self) -> &str {
229        &self.message
230    }
231}
232
233impl fmt::Display for Error {
234    fn fmt(&self, formatter: &mut fmt::Formatter) -> Result<(), fmt::Error> {
235        self.message.fmt(formatter)
236    }
237}
238
239#[cfg(test)]
240mod test {
241    use crate::{
242        OptimisticTransactionDB, OptimisticTransactionOptions, Transaction, TransactionDB,
243        TransactionDBOptions, TransactionOptions,
244    };
245
246    use super::{
247        column_family::UnboundColumnFamily,
248        db_options::{CacheWrapper, WriteBufferManagerWrapper},
249        env::{Env, EnvWrapper},
250        BlockBasedOptions, BoundColumnFamily, Cache, ColumnFamily, ColumnFamilyDescriptor,
251        DBIterator, DBRawIterator, IngestExternalFileOptions, Options, PlainTableFactoryOptions,
252        ReadOptions, Snapshot, SstFileWriter, WriteBatch, WriteBufferManager, WriteOptions, DB,
253    };
254
255    #[test]
256    fn is_send() {
257        // test (at compile time) that certain types implement the auto-trait Send, either directly for
258        // pointer-wrapping types or transitively for types with all Send fields
259
260        fn is_send<T: Send>() {
261            // dummy function just used for its parameterized type bound
262        }
263
264        is_send::<DB>();
265        is_send::<DBIterator<'_>>();
266        is_send::<DBRawIterator<'_>>();
267        is_send::<Snapshot>();
268        is_send::<Options>();
269        is_send::<ReadOptions>();
270        is_send::<WriteOptions>();
271        is_send::<IngestExternalFileOptions>();
272        is_send::<BlockBasedOptions>();
273        is_send::<PlainTableFactoryOptions>();
274        is_send::<ColumnFamilyDescriptor>();
275        is_send::<ColumnFamily>();
276        is_send::<BoundColumnFamily<'_>>();
277        is_send::<UnboundColumnFamily>();
278        is_send::<SstFileWriter>();
279        is_send::<WriteBatch>();
280        is_send::<Cache>();
281        is_send::<CacheWrapper>();
282        is_send::<Env>();
283        is_send::<EnvWrapper>();
284        is_send::<TransactionDB>();
285        is_send::<OptimisticTransactionDB>();
286        is_send::<Transaction<'_, TransactionDB>>();
287        is_send::<TransactionDBOptions>();
288        is_send::<OptimisticTransactionOptions>();
289        is_send::<TransactionOptions>();
290        is_send::<WriteBufferManager>();
291        is_send::<WriteBufferManagerWrapper>();
292    }
293
294    #[test]
295    fn is_sync() {
296        // test (at compile time) that certain types implement the auto-trait Sync
297
298        fn is_sync<T: Sync>() {
299            // dummy function just used for its parameterized type bound
300        }
301
302        is_sync::<DB>();
303        is_sync::<Snapshot>();
304        is_sync::<Options>();
305        is_sync::<ReadOptions>();
306        is_sync::<WriteOptions>();
307        is_sync::<IngestExternalFileOptions>();
308        is_sync::<BlockBasedOptions>();
309        is_sync::<PlainTableFactoryOptions>();
310        is_sync::<UnboundColumnFamily>();
311        is_sync::<ColumnFamilyDescriptor>();
312        is_sync::<SstFileWriter>();
313        is_sync::<Cache>();
314        is_sync::<CacheWrapper>();
315        is_sync::<Env>();
316        is_sync::<EnvWrapper>();
317        is_sync::<TransactionDB>();
318        is_sync::<OptimisticTransactionDB>();
319        is_sync::<TransactionDBOptions>();
320        is_sync::<OptimisticTransactionOptions>();
321        is_sync::<TransactionOptions>();
322        is_sync::<WriteBufferManager>();
323        is_sync::<WriteBufferManagerWrapper>();
324    }
325}
rocksdb/lib.rs

rocksdb/
lib.rs
