#[cfg(feature = "atomic-polyfill")] use atomic_polyfill as atomic; #[cfg(not(feature = "atomic-polyfill"))] use core::sync::atomic;
use alloc::boxed::Box; use atomic::{AtomicUsize, Ordering}; use core::any::{Any, TypeId}; use core::fmt; use core::hash::BuildHasher; use core::hash::Hasher;
static RAND_SOURCE: OnceBox<Box<dyn RandomSource + Send + Sync>> = OnceBox::new();
}
} /// A supplier of Randomness used for different hashers. /// See [set_random_source]. /// /// If [set_random_source] aHash will default to the best available source of randomness. /// In order this is: /// 1. OS provided random number generator (available if the `runtime-rng` flag is enabled which it is by default) - This should be very strong. /// 2. Strong compile time random numbers used to permute a static "counter". (available if `compile-time-rng` is enabled. /// __Enabling this is recommended if `runtime-rng` is not possible__) /// 3. A static counter that adds the memory address of each [RandomState] created permuted with fixed constants. /// (Similar to above but with fixed keys) - This is the weakest option. The strength of this heavily depends on whether or not ASLR is enabled. /// (Rust enables ASLR by default) pubtrait RandomSource { fn gen_hasher_seed(&self) -> usize;
}
impl RandomSource for DefaultRandomSource {
cfg_if::cfg_if! { if#[cfg(all(target_arch = "arm", target_os = "none"))] { fn gen_hasher_seed(&self) -> usize { let stack = selfas *const _ as usize; let previous = self.counter.load(Ordering::Relaxed); let new = previous.wrapping_add(stack); self.counter.store(new, Ordering::Relaxed);
new
}
} else { fn gen_hasher_seed(&self) -> usize { let stack = selfas *const _ as usize; self.counter.fetch_add(stack, Ordering::Relaxed)
}
}
}
}
cfg_if::cfg_if! { if#[cfg(all(target_arch = "arm", target_os = "none"))] { #[inline] fn get_src() -> &'static dyn RandomSource { static RAND_SOURCE: DefaultRandomSource = DefaultRandomSource::default();
&RAND_SOURCE
}
} else { /// Provides an optional way to manually supply a source of randomness for Hasher keys. /// /// The provided [RandomSource] will be used to be used as a source of randomness by [RandomState] to generate new states. /// If this method is not invoked the standard source of randomness is used as described in the Readme. /// /// The source of randomness can only be set once, and must be set before the first RandomState is created. /// If the source has already been specified `Err` is returned with a `bool` indicating if the set failed because /// method was previously invoked (true) or if the default source is already being used (false). #[cfg(not(all(target_arch = "arm", target_os = "none")))] pubfn set_random_source(source: impl RandomSource + Send + Sync + 'static) -> Result<(), bool> {
RAND_SOURCE.set(Box::new(Box::new(source))).map_err(|s| s.as_ref().type_id() != TypeId::of::<&DefaultRandomSource>())
}
/// Provides a [Hasher] factory. This is typically used (e.g. by [HashMap]) to create /// [AHasher]s in order to hash the keys of the map. See `build_hasher` below. /// /// [build_hasher]: ahash:: /// [Hasher]: std::hash::Hasher /// [BuildHasher]: std::hash::BuildHasher /// [HashMap]: std::collections::HashMap /// /// There are multiple constructors each is documented in more detail below: /// /// | Constructor | Dynamically random? | Seed | /// |---------------|---------------------|------| /// |`new` | Each instance unique|_[RandomSource]_| /// |`generate_with`| Each instance unique|`u64` x 4 + [RandomSource]| /// |`with_seed` | Fixed per process |`u64` + static random number| /// |`with_seeds` | Fixed |`u64` x 4| /// #[derive(Clone)] pubstruct RandomState { pub(crate) k0: u64, pub(crate) k1: u64, pub(crate) k2: u64, pub(crate) k3: u64,
}
impl RandomState { /// Create a new `RandomState` `BuildHasher` using random keys. /// /// Each instance will have a unique set of keys derived from [RandomSource]. /// #[inline] pubfn new() -> RandomState { let src = get_src(); let fixed = get_fixed_seeds(); Self::from_keys(&fixed[0], &fixed[1], src.gen_hasher_seed())
}
/// Create a new `RandomState` `BuildHasher` based on the provided seeds, but in such a way /// that each time it is called the resulting state will be different and of high quality. /// This allows fixed constant or poor quality seeds to be provided without the problem of different /// `BuildHasher`s being identical or weak. /// /// This is done via permuting the provided values with the value of a static counter and memory address. /// (This makes this method somewhat more expensive than `with_seeds` below which does not do this). /// /// The provided values (k0-k3) do not need to be of high quality but they should not all be the same value. #[inline] pubfn generate_with(k0: u64, k1: u64, k2: u64, k3: u64) -> RandomState { let src = get_src(); let fixed = get_fixed_seeds();
RandomState::from_keys(&fixed[0], &[k0, k1, k2, k3], src.gen_hasher_seed())
}
/// Internal. Used by Default. #[inline] pub(crate) fn with_fixed_keys() -> RandomState { let [k0, k1, k2, k3] = get_fixed_seeds()[0];
RandomState { k0, k1, k2, k3 }
}
/// Build a `RandomState` from a single key. The provided key does not need to be of high quality, /// but all `RandomState`s created from the same key will produce identical hashers. /// (In contrast to `generate_with` above) /// /// This allows for explicitly setting the seed to be used. /// /// Note: This method does not require the provided seed to be strong. #[inline] pubfn with_seed(key: usize) -> RandomState { let fixed = get_fixed_seeds();
RandomState::from_keys(&fixed[0], &fixed[1], key)
}
/// Allows for explicitly setting the seeds to used. /// All `RandomState`s created with the same set of keys key will produce identical hashers. /// (In contrast to `generate_with` above) /// /// Note: If DOS resistance is desired one of these should be a decent quality random number. /// If 4 high quality random number are not cheaply available this method is robust against 0s being passed for /// one or more of the parameters or the same value being passed for more than one parameter. /// It is recommended to pass numbers in order from highest to lowest quality (if there is any difference). #[inline] pubconstfn with_seeds(k0: u64, k1: u64, k2: u64, k3: u64) -> RandomState {
RandomState {
k0: k0 ^ PI2[0],
k1: k1 ^ PI2[1],
k2: k2 ^ PI2[2],
k3: k3 ^ PI2[3],
}
}
/// Calculates the hash of a single value. This provides a more convenient (and faster) way to obtain a hash: /// For example: #[cfg_attr(
feature = "std",
doc = r##" # Examples
``` use std::hash::BuildHasher; use ahash::RandomState;
let hash_builder = RandomState::new(); let hash = hash_builder.hash_one("Some Data");
``` "##
)] /// This is similar to: #[cfg_attr(
feature = "std",
doc = r##" # Examples
``` use std::hash::{BuildHasher, Hash, Hasher}; use ahash::RandomState;
let hash_builder = RandomState::new(); letmut hasher = hash_builder.build_hasher(); "Some Data".hash(&mut hasher); let hash = hasher.finish();
``` "##
)] /// (Note that these two ways to get a hash may not produce the same value for the same data) /// /// This is intended as a convenience for code which *consumes* hashes, such /// as the implementation of a hash table or in unit tests that check /// whether a custom [`Hash`] implementation behaves as expected. /// /// This must not be used in any code which *creates* hashes, such as in an /// implementation of [`Hash`]. The way to create a combined hash of /// multiple values is to call [`Hash::hash`] multiple times using the same /// [`Hasher`], not to call this method repeatedly and combine the results. #[inline] pubfn hash_one<T: Hash>(&self, x: T) -> u64 where Self: Sized,
{ usecrate::specialize::CallHasher;
T::get_hash(&x, self)
}
}
/// Creates an instance of RandomState using keys obtained from the random number generator. /// Each instance created in this way will have a unique set of keys. (But the resulting instance /// can be used to create many hashers each or which will have the same keys.) /// /// This is the same as [RandomState::new()] /// /// NOTE: For safety this trait impl is only available available if either of the flags `runtime-rng` (on by default) or /// `compile-time-rng` are enabled. This is to prevent weakly keyed maps from being accidentally created. Instead one of /// constructors for [RandomState] must be used. #[cfg(any(feature = "compile-time-rng", feature = "runtime-rng", feature = "no-rng"))] impl Default for RandomState { #[inline] fn default() -> Self { Self::new()
}
}
impl BuildHasher for RandomState { type Hasher = AHasher;
/// Constructs a new [AHasher] with keys based on this [RandomState] object. /// This means that two different [RandomState]s will will generate /// [AHasher]s that will return different hashcodes, but [Hasher]s created from the same [BuildHasher] /// will generate the same hashes for the same input data. /// #[cfg_attr(
feature = "std",
doc = r##" # Examples
``` use ahash::{AHasher, RandomState}; use std::hash::{Hasher, BuildHasher};
/// Calculates the hash of a single value. This provides a more convenient (and faster) way to obtain a hash: /// For example: #[cfg_attr(
feature = "std",
doc = r##" # Examples
``` use std::hash::BuildHasher; use ahash::RandomState;
let hash_builder = RandomState::new(); let hash = hash_builder.hash_one("Some Data");
``` "##
)] /// This is similar to: #[cfg_attr(
feature = "std",
doc = r##" # Examples
``` use std::hash::{BuildHasher, Hash, Hasher}; use ahash::RandomState;
let hash_builder = RandomState::new(); letmut hasher = hash_builder.build_hasher(); "Some Data".hash(&mut hasher); let hash = hasher.finish();
``` "##
)] /// (Note that these two ways to get a hash may not produce the same value for the same data) /// /// This is intended as a convenience for code which *consumes* hashes, such /// as the implementation of a hash table or in unit tests that check /// whether a custom [`Hash`] implementation behaves as expected. /// /// This must not be used in any code which *creates* hashes, such as in an /// implementation of [`Hash`]. The way to create a combined hash of /// multiple values is to call [`Hash::hash`] multiple times using the same /// [`Hasher`], not to call this method repeatedly and combine the results. #[cfg(feature = "specialize")] #[inline] fn hash_one<T: Hash>(&self, x: T) -> u64 {
RandomState::hash_one(self, x)
}
}
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.