jleony/nanoreth
1
0
Fork 0
mirror of https://github.com/hl-archive-node/nanoreth.git synced 2025-12-06 10:59:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add more docs to reth-db (#2002)

Browse Source
This commit is contained in:
Bjerg
2023-03-28 19:40:58 +02:00
committed by GitHub
parent 3810548bd7
commit 44f5f7d269
5 changed files with 122 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
crates/storage/db/src/abstraction/common.rs
View File

@ -1,10 +1,19 @@
/// Alias type containing key value pairs.
/// A key-value pair for table `T`.
pub type KeyValue<T> = (<T as Table>::Key, <T as Table>::Value);
/// Alias type for a `(key, value)` result coming from a cursor.
/// A fallible key-value pair that may or may not exist.
///
/// The `Result` represents that the operation might fail, while the `Option` represents whether or
/// not the entry exists.
pub type PairResult<T> = Result<Option<KeyValue<T>>, Error>;
/// Alias type for a `(key, value)` result coming from an iterator.
/// A key-value pair coming from an iterator.
///
/// The `Result` represents that the operation might fail, while the `Option` represents whether or
/// not there is another entry.
pub type IterPairResult<T> = Option<Result<KeyValue<T>, Error>>;
/// Alias type for a value result coming from a cursor without its key.
/// A value only result for table `T`.
pub type ValueOnlyResult<T> = Result<Option<<T as Table>::Value>, Error>;
use crate::{abstraction::table::*, Error};

60
crates/storage/db/src/abstraction/cursor.rs
View File

@ -9,33 +9,34 @@ use crate::{
Error,
};
/// Read only cursor over table.
/// A read-only cursor over table `T`.
pub trait DbCursorRO<'tx, T: Table> {
/// First item in table
/// Positions the cursor at the first entry in the table, returning it.
fn first(&mut self) -> PairResult<T>;
/// Seeks for the exact `(key, value)` pair with `key`.
/// Seeks to the KV pair exactly at `key`.
fn seek_exact(&mut self, key: T::Key) -> PairResult<T>;
/// Seeks for a `(key, value)` pair greater or equal than `key`.
/// Seeks to the KV pair whose key is greater than or equal to `key`.
fn seek(&mut self, key: T::Key) -> PairResult<T>;
/// Returns the next `(key, value)` pair.
/// Position the cursor at the next KV pair, returning it.
#[allow(clippy::should_implement_trait)]
fn next(&mut self) -> PairResult<T>;
/// Returns the previous `(key, value)` pair.
/// Position the cursor at the previous KV pair, returning it.
fn prev(&mut self) -> PairResult<T>;
/// Returns the last `(key, value)` pair.
/// Positions the cursor at the last entry in the table, returning it.
fn last(&mut self) -> PairResult<T>;
/// Returns the current `(key, value)` pair of the cursor.
/// Get the KV pair at the cursor's current position.
fn current(&mut self) -> PairResult<T>;
/// Returns an iterator that walks through the table. If `start_key`
/// is None, starts from the first entry of the table. If it not, starts at a key
/// greater or equal than the key value wrapped inside Some().
/// Get an iterator that walks through the table.
///
/// If `start_key` is `None`, then the walker will start from the first entry of the table,
/// otherwise it starts at the entry greater than or equal to the provided key.
fn walk<'cursor>(
&'cursor mut self,
start_key: Option<T::Key>,
@ -43,7 +44,7 @@ pub trait DbCursorRO<'tx, T: Table> {
where
Self: Sized;
/// Returns an iterator for the keys in the specified range.
/// Get an iterator that walks over a range of keys in the table.
fn walk_range<'cursor>(
&'cursor mut self,
range: impl RangeBounds<T::Key>,
@ -51,9 +52,10 @@ pub trait DbCursorRO<'tx, T: Table> {
where
Self: Sized;
/// Returns an iterator that walks backwards through the table. If `start_key`
/// is None, starts from the last entry of the table. If it not, starts at a key
/// greater or equal than the key value wrapped inside Some().
/// Get an iterator that walks through the table in reverse order.
///
/// If `start_key` is `None`, then the walker will start from the last entry of the table,
/// otherwise it starts at the entry greater than or equal to the provided key.
fn walk_back<'cursor>(
&'cursor mut self,
start_key: Option<T::Key>,
@ -62,22 +64,36 @@ pub trait DbCursorRO<'tx, T: Table> {
Self: Sized;
}
/// Read only cursor over DupSort table.
/// A read-only cursor over the dup table `T`.
pub trait DbDupCursorRO<'tx, T: DupSort> {
/// Returns the next `(key, value)` pair of a DupSort table.
/// Positions the cursor at the next KV pair of the table, returning it.
fn next_dup(&mut self) -> PairResult<T>;
/// Returns the next `(key, value)` pair skipping the duplicates.
/// Positions the cursor at the next KV pair of the table, skipping duplicates.
fn next_no_dup(&mut self) -> PairResult<T>;
/// Returns the next `value` of a duplicate `key`.
/// Positions the cursor at the next duplicate value of the current key.
fn next_dup_val(&mut self) -> ValueOnlyResult<T>;
/// Seek by key and subkey. Make sure that the returned value subkey matches the queried one.
/// Positions the cursor at the entry greater than or equal to the provided key/subkey pair.
///
/// # Note
///
/// The position of the cursor might not correspond to the key/subkey pair if the entry does not
/// exist.
fn seek_by_key_subkey(&mut self, key: T::Key, subkey: T::SubKey) -> ValueOnlyResult<T>;
/// Returns an iterator starting at a key greater or equal than `start_key` of a DupSort
/// table.
/// Get an iterator that walks through the dup table.
///
/// The cursor will start at different points in the table depending on the values of `key` and
/// `subkey`:
///
/// | `key` | `subkey` | **Equivalent starting position** |
/// |--------|----------|-----------------------------------------|
/// | `None` | `None` | [`DbCursorRO::first()`] |
/// | `Some` | `None` | [`DbCursorRO::seek()`] |
/// | `None` | `Some` | [`DbDupCursorRO::seek_by_key_subkey()`] |
/// | `Some` | `Some` | [`DbDupCursorRo::seek_by_key_subkey()`] |
fn walk_dup<'cursor>(
&'cursor mut self,
key: Option<T::Key>,

2
crates/storage/db/src/abstraction/mod.rs
View File

@ -1,4 +1,4 @@
/// Common return types
/// Common types used throughout the abstraction.
pub mod common;
/// Cursor database traits.
pub mod cursor;

59
crates/storage/db/src/lib.rs
View File

@ -1,4 +1,59 @@
//! Rust database abstraction and concrete database implementations.
//! reth's database abstraction layer with concrete implementations.
//!
//! The database abstraction assumes that the underlying store is a KV store subdivided into tables.
//!
//! One or more changes are tied to a transaction that is atomically committed to the data store at
//! the same time. Strong consistency in what data is written and when is important for reth, so it
//! is not possible to write data to the database outside of using a transaction.
//!
//! Good starting points for this crate are:
//!
//! - [`Database`] for the main database abstraction
//! - [`DbTx`] (RO) and [`DbTxMut`] (RW) for the transaction abstractions.
//! - [`DbCursorRO`] (RO) and [`DbCursorRW`] (RW) for the cursor abstractions (see below).
//!
//! # Cursors and Walkers
//!
//! The abstraction also defines a couple of helpful abstractions for iterating and writing data:
//!
//! - **Cursors** ([`DbCursorRO`] / [`DbCursorRW`]) for iterating data in a table. Cursors are
//! assumed to resolve data in a sorted manner when iterating from start to finish, and it is safe
//! to assume that they are efficient at doing so.
//! - **Walkers** ([`Walker`] / [`RangeWalker`] / [`ReverseWalker`]) use cursors to walk the entries
//! in a table, either fully from a specific point, or over a range.
//!
//! Dup tables (see below) also have corresponding cursors and walkers (e.g. [`DbDupCursorRO`]).
//! These **should** be preferred when working with dup tables, as they provide additional methods
//! that are optimized for dup tables.
//!
//! # Tables
//!
//! reth has two types of tables: simple KV stores (one key, one value) and dup tables (one key,
//! many values). Dup tables can be efficient for certain types of data.
//!
//! Keys are de/serialized using the [`Encode`] and [`Decode`] traits, and values are de/serialized
//! ("compressed") using the [`Compress`] and [`Decompress`] traits.
//!
//! Tables implement the [`Table`] trait.
//!
//! # Overview
//!
//! An overview of the current data model of reth can be found in the [`tables`] module.
//!
//! [`Database`]: crate::abstraction::database::Database
//! [`DbTx`]: crate::abstraction::transaction::DbTx
//! [`DbTxMut`]: crate::abstraction::transaction::DbTxMut
//! [`DbCursorRO`]: crate::abstraction::cursor::DbCursorRO
//! [`DbCursorRW`]: crate::abstraction::cursor::DbCursorRW
//! [`Walker`]: crate::abstraction::cursor::Walker
//! [`RangeWalker`]: crate::abstraction::cursor::RangeWalker
//! [`ReverseWalker`]: crate::abstraction::cursor::ReverseWalker
//! [`DbDupCursorRO`]: crate::abstraction::cursor::DbDupCursorRO
//! [`Encode`]: crate::abstraction::table::Encode
//! [`Decode`]: crate::abstraction::table::Decode
//! [`Compress`]: crate::abstraction::table::Compress
//! [`Decompress`]: crate::abstraction::table::Decompress
//! [`Table`]: crate::abstraction::table::Table
#![warn(missing_docs, unreachable_pub)]
#![deny(unused_must_use, rust_2018_idioms)]
@ -7,7 +62,7 @@
attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables))
))]
/// Abstracted part of database, containing traits for transactions and cursors.
/// Traits defining the database abstractions, such as cursors and transactions.
pub mod abstraction;
mod implementation;

15
crates/storage/db/src/tables/mod.rs
View File

@ -1,8 +1,19 @@
//! Table and data structures
//! Tables and data models.
//!
//! # Overview
//!
//! This module defines the tables in reth, as well as some table-related abstractions:
//!
//! - [`codecs`] integrates different codecs into [`Encode`] and [`Decode`]
//! - [`models`] defines the values written to tables
//!
//! # Database Tour
//!
//! TODO(onbjerg): Find appropriate format for this...
pub mod codecs;
pub mod models;
pub mod utils;
pub(crate) mod utils;
/// Declaration of all Database tables.
use crate::{