hashdb/lib.rs
1// Copyright 2015-2018 Parity Technologies (UK) Ltd.
2// This file is part of Parity.
3
4// Parity is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8
9// Parity is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13
14// You should have received a copy of the GNU General Public License
15// along with Parity. If not, see <http://www.gnu.org/licenses/>.
16
17//! Database of byte-slices keyed to their hash.
18
19#![cfg_attr(not(feature = "std"), no_std)]
20
21#[cfg(feature = "std")]
22extern crate core;
23
24#[cfg(feature = "std")]
25#[cfg(feature = "std")]
26use std::collections::HashMap;
27use core::{fmt::Debug, hash::Hash};
28
29/// Trait describing an object that can hash a slice of bytes. Used to abstract
30/// other types over the hashing algorithm. Defines a single `hash` method and an
31/// `Out` associated type with the necessary bounds.
32pub trait Hasher: Sync + Send {
33 /// The output type of the `Hasher`
34 type Out: AsRef<[u8]> + AsMut<[u8]> + Default + Debug + PartialEq + Eq + Hash + Send + Sync + Clone + Copy;
35 /// What to use to build `HashMap`s with this `Hasher`
36 type StdHasher: Sync + Send + Default + core::hash::Hasher;
37 /// The length in bytes of the `Hasher` output
38 const LENGTH: usize;
39
40 /// Compute the hash of the provided slice of bytes returning the `Out` type of the `Hasher`
41 fn hash(x: &[u8]) -> Self::Out;
42}
43
44/// Trait modelling datastore keyed by a hash defined by the `Hasher`.
45#[cfg(feature = "std")]
46pub trait HashDB<H: Hasher, T>: Send + Sync + AsHashDB<H, T> {
47 /// Get the keys in the database together with number of underlying references.
48 fn keys(&self) -> HashMap<H::Out, i32>;
49
50 /// Look up a given hash into the bytes that hash to it, returning None if the
51 /// hash is not known.
52 fn get(&self, key: &H::Out) -> Option<T>;
53
54 /// Check for the existance of a hash-key.
55 fn contains(&self, key: &H::Out) -> bool;
56
57 /// Insert a datum item into the DB and return the datum's hash for a later lookup. Insertions
58 /// are counted and the equivalent number of `remove()`s must be performed before the data
59 /// is considered dead.
60 fn insert(&mut self, value: &[u8]) -> H::Out;
61
62 /// Like `insert()`, except you provide the key and the data is all moved.
63 fn emplace(&mut self, key: H::Out, value: T);
64
65 /// Remove a datum previously inserted. Insertions can be "owed" such that the same number of `insert()`s may
66 /// happen without the data being eventually being inserted into the DB. It can be "owed" more than once.
67 fn remove(&mut self, key: &H::Out);
68}
69
70/// Upcast trait.
71#[cfg(feature = "std")]
72pub trait AsHashDB<H: Hasher, T> {
73 /// Perform upcast to HashDB for anything that derives from HashDB.
74 fn as_hashdb(&self) -> &HashDB<H, T>;
75 /// Perform mutable upcast to HashDB for anything that derives from HashDB.
76 fn as_hashdb_mut(&mut self) -> &mut HashDB<H, T>;
77}
78
79// NOTE: There used to be a `impl<T> AsHashDB for T` but that does not work with generics. See https://stackoverflow.com/questions/48432842/implementing-a-trait-for-reference-and-non-reference-types-causes-conflicting-im
80// This means we need concrete impls of AsHashDB in several places, which somewhat defeats the point of the trait.
81#[cfg(feature = "std")]
82impl<'a, H: Hasher, T> AsHashDB<H, T> for &'a mut HashDB<H, T> {
83 fn as_hashdb(&self) -> &HashDB<H, T> { &**self }
84 fn as_hashdb_mut(&mut self) -> &mut HashDB<H, T> { &mut **self }
85}