From 334b4652b60514ab63106428456ffd4f400ebfeb Mon Sep 17 00:00:00 2001 From: Oleksandr Anyshchenko Date: Thu, 7 May 2020 10:05:16 +0300 Subject: [PATCH] Add some doc-comments and tiny refactoring (#424) --- src/backup.rs | 2 +- src/db.rs | 16 +++--- src/db_options.rs | 116 +++++++++++++++++++++++------------------ src/merge_operator.rs | 6 +-- src/slice_transform.rs | 2 +- src/snapshot.rs | 24 +++++++-- 6 files changed, 97 insertions(+), 69 deletions(-) diff --git a/src/backup.rs b/src/backup.rs index 00610ee..1b3f0aa 100644 --- a/src/backup.rs +++ b/src/backup.rs @@ -85,7 +85,7 @@ impl BackupEngine { /// * `wal_dir` - A path to the wal directory /// * `opts` - Restore options /// - /// # Example + /// # Examples /// /// ```ignore /// use rocksdb::backup::{BackupEngine, BackupEngineOptions}; diff --git a/src/db.rs b/src/db.rs index 207b3a0..17759e5 100644 --- a/src/db.rs +++ b/src/db.rs @@ -959,8 +959,8 @@ impl DB { /// Retrieves a RocksDB property by name. /// - /// For a full list of properties, see - /// https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L428-L634 + /// Full list of properties could be find + /// [here](https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L428-L634). pub fn property_value(&self, name: &str) -> Result, Error> { let prop_name = match CString::new(name) { Ok(c) => c, @@ -995,8 +995,8 @@ impl DB { /// Retrieves a RocksDB property by name, for a specific column family. /// - /// For a full list of properties, see - /// https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L428-L634 + /// Full list of properties could be find + /// [here](https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L428-L634). pub fn property_value_cf( &self, cf: &ColumnFamily, @@ -1035,8 +1035,8 @@ impl DB { /// Retrieves a RocksDB property and casts it to an integer. /// - /// For a full list of properties that return int values, see - /// https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L654-L689 + /// Full list of properties that return int values could be find + /// [here](https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L654-L689). pub fn property_int_value(&self, name: &str) -> Result, Error> { match self.property_value(name) { Ok(Some(value)) => match value.parse::() { @@ -1053,8 +1053,8 @@ impl DB { /// Retrieves a RocksDB property for a specific column family and casts it to an integer. /// - /// For a full list of properties that return int values, see - /// https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L654-L689 + /// Full list of properties that return int values could be find + /// [here](https://github.com/facebook/rocksdb/blob/08809f5e6cd9cc4bc3958dd4d59457ae78c76660/include/rocksdb/db.h#L654-L689). pub fn property_int_value_cf( &self, cf: &ColumnFamily, diff --git a/src/db_options.rs b/src/db_options.rs index 48946d6..d6890d9 100644 --- a/src/db_options.rs +++ b/src/db_options.rs @@ -29,13 +29,14 @@ use crate::{ Snapshot, }; -pub fn new_cache(capacity: size_t) -> *mut ffi::rocksdb_cache_t { +fn new_cache(capacity: size_t) -> *mut ffi::rocksdb_cache_t { unsafe { ffi::rocksdb_cache_create_lru(capacity) } } /// Database-wide options around performance and behavior. /// -/// Please read [the official tuning guide](https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide), and most importantly, measure performance under realistic workloads with realistic hardware. +/// Please read the official tuning [guide](https://github.com/facebook/rocksdb/wiki/RocksDB-Tuning-Guide) +/// and most importantly, measure performance under realistic workloads with realistic hardware. /// /// # Examples /// @@ -273,7 +274,7 @@ impl BlockBasedOptions { /// Defines the index type to be used for SS-table lookups. /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{BlockBasedOptions, BlockBasedIndexType, Options}; @@ -321,7 +322,9 @@ impl BlockBasedOptions { } /// Format version, reserved for backward compatibility. - /// See https://github.com/facebook/rocksdb/blob/f059c7d9b96300091e07429a60f4ad55dac84859/include/rocksdb/table.h#L249-L274. + /// + /// See full [list](https://github.com/facebook/rocksdb/blob/f059c7d9b96300091e07429a60f4ad55dac84859/include/rocksdb/table.h#L249-L274) + /// of the supported versions. /// /// Default: 2. pub fn set_format_version(&mut self, version: i32) { @@ -363,7 +366,7 @@ impl BlockBasedOptions { /// valid only when using `DataBlockIndexType::BinaryAndHash`. /// /// Default: `BinarySearch` - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{BlockBasedOptions, DataBlockIndexType, Options}; @@ -407,7 +410,7 @@ impl Options { /// cores. You almost definitely want to call this function if your system is /// bottlenecked by RocksDB. /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -475,7 +478,7 @@ impl Options { /// /// Default: `false` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -494,7 +497,7 @@ impl Options { /// /// Default: `false` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -516,7 +519,7 @@ impl Options { /// Default: `DBCompressionType::Snappy` (`DBCompressionType::None` if /// snappy feature is not enabled). /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, DBCompressionType}; @@ -538,7 +541,7 @@ impl Options { /// each level of the database; these override the value specified in /// the previous field 'compression'. /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, DBCompressionType}; @@ -580,7 +583,7 @@ impl Options { /// /// Default: `0` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -742,7 +745,7 @@ impl Options { /// /// Default: `false` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -767,7 +770,7 @@ impl Options { /// /// Default: `-1` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -788,7 +791,7 @@ impl Options { /// /// Default: `false` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -814,7 +817,7 @@ impl Options { /// /// This option applies to table files /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -837,7 +840,7 @@ impl Options { /// /// Default: true /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -861,7 +864,7 @@ impl Options { /// /// Default: false /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -885,7 +888,7 @@ impl Options { /// /// Default: false /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -921,7 +924,7 @@ impl Options { /// /// Default: true /// - /// # Example + /// # Examples /// /// ``` /// #[allow(deprecated)] @@ -943,7 +946,7 @@ impl Options { /// /// Default: `6` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -967,7 +970,7 @@ impl Options { /// /// Default: `1` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -991,7 +994,7 @@ impl Options { /// /// Default: `2` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1022,7 +1025,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1047,7 +1050,7 @@ impl Options { /// /// Default: 0 (disabled) /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1074,7 +1077,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1090,7 +1093,7 @@ impl Options { /// Default: `10` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1108,7 +1111,7 @@ impl Options { /// The older manifest file be deleted. /// The default value is MAX_INT so that roll-over does not take place. /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1135,7 +1138,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1159,7 +1162,7 @@ impl Options { /// /// Default: `1` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1180,7 +1183,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1202,7 +1205,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1222,7 +1225,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1240,7 +1243,7 @@ impl Options { /// /// Default: DBCompactionStyle::Level /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, DBCompactionStyle}; @@ -1267,7 +1270,7 @@ impl Options { /// /// Default: `1` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1298,7 +1301,7 @@ impl Options { /// /// Default: `1` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1319,7 +1322,7 @@ impl Options { /// /// Dynamically changeable through SetOptions() API /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1364,10 +1367,10 @@ impl Options { } /// Defines the underlying memtable implementation. - /// See https://github.com/facebook/rocksdb/wiki/MemTable for more information. + /// See official [wiki](https://github.com/facebook/rocksdb/wiki/MemTable) for more information. /// Defaults to using a skiplist. /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, MemtableFactory}; @@ -1410,7 +1413,15 @@ impl Options { } } - /// See https://github.com/facebook/rocksdb/wiki/PlainTable-Format. + // This is a factory that provides TableFactory objects. + // Default: a block-based table factory that provides a default + // implementation of TableBuilder and TableReader with default + // BlockBasedTableOptions. + /// Sets the factory as plain table. + /// See official [wiki](https://github.com/facebook/rocksdb/wiki/PlainTable-Format) for more + /// information. + /// + /// # Examples /// /// ``` /// use rocksdb::{Options, PlainTableFactoryOptions}; @@ -1441,7 +1452,7 @@ impl Options { /// /// Default: `false` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1461,7 +1472,7 @@ impl Options { /// /// Default: `0` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1480,7 +1491,7 @@ impl Options { /// /// Default: DBRecoveryMode::PointInTime /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, DBRecoveryMode}; @@ -1518,7 +1529,7 @@ impl Options { /// /// Default: `600` (10 mins) /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1554,7 +1565,7 @@ impl Options { /// /// Default: `0` /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::{Options, SliceTransform}; @@ -1575,7 +1586,7 @@ impl Options { /// /// Default: same directory as the database /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1612,7 +1623,7 @@ impl Options { /// /// Default: false /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1630,7 +1641,7 @@ impl Options { /// /// Default: false /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1653,7 +1664,7 @@ impl Options { /// /// Default: false /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1673,7 +1684,7 @@ impl Options { /// /// Default: disable /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::Options; @@ -1718,7 +1729,7 @@ impl FlushOptions { /// /// Default: true /// - /// # Example + /// # Examples /// /// ``` /// use rocksdb::FlushOptions; @@ -1890,7 +1901,7 @@ pub enum DataBlockIndexType { } /// Defines the underlying memtable implementation. -/// See https://github.com/facebook/rocksdb/wiki/MemTable for more information. +/// See official [wiki](https://github.com/facebook/rocksdb/wiki/MemTable) for more information. pub enum MemtableFactory { Vector, HashSkipList { @@ -1904,7 +1915,8 @@ pub enum MemtableFactory { } /// Used with DBOptions::set_plain_table_factory. -/// See https://github.com/facebook/rocksdb/wiki/PlainTable-Format. +/// See official [wiki](https://github.com/facebook/rocksdb/wiki/PlainTable-Format) for more +/// information. /// /// Defaults: /// user_key_length: 0 (variable length) diff --git a/src/merge_operator.rs b/src/merge_operator.rs index 5fe0769..a47faea 100644 --- a/src/merge_operator.rs +++ b/src/merge_operator.rs @@ -223,10 +223,10 @@ mod test { } #[test] - fn mergetest() { + fn merge_test() { use crate::{Options, DB}; - let path = "_rust_rocksdb_mergetest"; + let path = "_rust_rocksdb_merge_test"; let mut opts = Options::default(); opts.create_if_missing(true); opts.set_merge_operator("test operator", test_provided_merge, None); @@ -331,7 +331,7 @@ mod test { #[test] #[allow(clippy::too_many_lines)] - fn counting_mergetest() { + fn counting_merge_test() { use crate::{DBCompactionStyle, Options, DB}; use std::sync::Arc; use std::thread; diff --git a/src/slice_transform.rs b/src/slice_transform.rs index 6d2c977..403303a 100644 --- a/src/slice_transform.rs +++ b/src/slice_transform.rs @@ -19,7 +19,7 @@ use libc::{c_char, c_void, size_t}; use crate::ffi; -/// A SliceTranform is a generic pluggable way of transforming one string +/// A `SliceTransform` is a generic pluggable way of transforming one string /// to another. Its primary use-case is in configuring rocksdb /// to store prefix blooms by setting prefix_extractor in /// ColumnFamilyOptions. diff --git a/src/snapshot.rs b/src/snapshot.rs index 2d5df31..41b2482 100644 --- a/src/snapshot.rs +++ b/src/snapshot.rs @@ -16,6 +16,8 @@ use crate::{ffi, ColumnFamily, DBIterator, DBRawIterator, Error, IteratorMode, R /// A consistent view of the database at the point of creation. /// +/// # Examples +/// /// ``` /// use rocksdb::{DB, IteratorMode, Options}; /// @@ -34,6 +36,7 @@ pub struct Snapshot<'a> { } impl<'a> Snapshot<'a> { + /// Creates a new `Snapshot` of the database `db`. pub fn new(db: &DB) -> Snapshot { let snapshot = unsafe { ffi::rocksdb_create_snapshot(db.inner) }; Snapshot { @@ -42,21 +45,27 @@ impl<'a> Snapshot<'a> { } } + /// Creates an iterator over the data in this snapshot, using the default read options. pub fn iterator(&self, mode: IteratorMode) -> DBIterator<'a> { let readopts = ReadOptions::default(); self.iterator_opt(mode, readopts) } + /// Creates an iterator over the data in this snapshot under the given column family, using + /// the default read options. pub fn iterator_cf(&self, cf_handle: &ColumnFamily, mode: IteratorMode) -> DBIterator { let readopts = ReadOptions::default(); self.iterator_cf_opt(cf_handle, readopts, mode) } + /// Creates an iterator over the data in this snapshot, using the given read options. pub fn iterator_opt(&self, mode: IteratorMode, mut readopts: ReadOptions) -> DBIterator<'a> { readopts.set_snapshot(self); DBIterator::new(self.db, readopts, mode) } + /// Creates an iterator over the data in this snapshot under the given column family, using + /// the given read options. pub fn iterator_cf_opt( &self, cf_handle: &ColumnFamily, @@ -67,25 +76,27 @@ impl<'a> Snapshot<'a> { DBIterator::new_cf(self.db, cf_handle, readopts, mode) } - /// Opens a raw iterator over the data in this snapshot, using the default read options. + /// Creates a raw iterator over the data in this snapshot, using the default read options. pub fn raw_iterator(&self) -> DBRawIterator { let readopts = ReadOptions::default(); self.raw_iterator_opt(readopts) } - /// Opens a raw iterator over the data in this snapshot under the given column family, using the default read options. + /// Creates a raw iterator over the data in this snapshot under the given column family, using + /// the default read options. pub fn raw_iterator_cf(&self, cf_handle: &ColumnFamily) -> DBRawIterator { let readopts = ReadOptions::default(); self.raw_iterator_cf_opt(cf_handle, readopts) } - /// Opens a raw iterator over the data in this snapshot, using the given read options. + /// Creates a raw iterator over the data in this snapshot, using the given read options. pub fn raw_iterator_opt(&self, mut readopts: ReadOptions) -> DBRawIterator { readopts.set_snapshot(self); DBRawIterator::new(self.db, readopts) } - /// Opens a raw iterator over the data in this snapshot under the given column family, using the given read options. + /// Creates a raw iterator over the data in this snapshot under the given column family, using + /// the given read options. pub fn raw_iterator_cf_opt( &self, cf_handle: &ColumnFamily, @@ -95,11 +106,14 @@ impl<'a> Snapshot<'a> { DBRawIterator::new_cf(self.db, cf_handle, readopts) } + /// Returns the bytes associated with a key value with default read options. pub fn get>(&self, key: K) -> Result>, Error> { let readopts = ReadOptions::default(); self.get_opt(key, readopts) } + /// Returns the bytes associated with a key value and given column family with default read + /// options. pub fn get_cf>( &self, cf: &ColumnFamily, @@ -109,6 +123,7 @@ impl<'a> Snapshot<'a> { self.get_cf_opt(cf, key.as_ref(), readopts) } + /// Returns the bytes associated with a key value and given read options. pub fn get_opt>( &self, key: K, @@ -118,6 +133,7 @@ impl<'a> Snapshot<'a> { self.db.get_opt(key.as_ref(), &readopts) } + /// Returns the bytes associated with a key value, given column family and read options. pub fn get_cf_opt>( &self, cf: &ColumnFamily,