Crate bloomcraft

Expand description

Production-grade Bloom filters for Rust.

BloomCraft provides a comprehensive family of Bloom filter implementations spanning classical algorithms, cache-optimised variants, lock-free concurrent filters, and hierarchical/tree filters — all with a uniform BloomFilter trait interface and type-safe builders.

§Modules

core - Core traits, parameter math, and bit-vector primitives.
filters - Bloom filter implementations.
hash - Hashers and index-generation strategies.
builder - Builders for standard, counting, and scalable filters.
sync - Concurrent shared-filter variants.
error - Crate-wide error and Result types.
serde_support - Serialization helpers, available with the serde feature.
metrics - Metrics collection, available with the metrics feature.

§Quick start

use bloomcraft::filters::StandardBloomFilter;
use bloomcraft::core::BloomFilter;

let mut filter: StandardBloomFilter<&str> =
    StandardBloomFilter::new(10_000, 0.01).expect("valid params");
filter.insert(&"hello");
filter.insert(&"world");

assert!(filter.contains(&"hello"));
assert!(!filter.contains(&"goodbye"));

§Concurrency models

Model	Trait	`&self` / `&mut self`	Examples
Single-threaded	`BloomFilter`	`&mut self`	`StandardBloomFilter`, `CountingBloomFilter`, `ScalableBloomFilter`
Lock-free atomic	`ConcurrentBloomFilter`	`&self` (atomic ops)	`StandardBloomFilter`
Interior mutability	`SharedBloomFilter`	`&self` (shards/stripes)	`ShardedBloomFilter`, `StripedBloomFilter`

use bloomcraft::StandardBloomFilter;
use bloomcraft::core::ConcurrentBloomFilter;
use std::sync::Arc;

let filter = Arc::new(StandardBloomFilter::<String>::new(10_000, 0.01).unwrap());
let f2 = Arc::clone(&filter);
std::thread::spawn(move || { f2.insert_concurrent(&"item".to_string()); }).join().unwrap();
assert!(filter.contains(&"item".to_string()));

§Choosing a filter

Filter	Use case	Concurrency
`StandardBloomFilter`	General-purpose, known size	Lock-free atomic
`CountingBloomFilter`	Dynamic sets with deletion	`Mutex`-wrapped
`ScalableBloomFilter`	Unknown or unbounded size	`Mutex`-wrapped
`AtomicScalableBloomFilter`	Concurrent, unbounded size	Lock-free atomic
`PartitionedBloomFilter`	Cache-optimised queries	`Mutex`-wrapped
`AtomicPartitionedBloomFilter`	Concurrent, cache-optimised	Lock-free atomic
`RegisterBlockedBloomFilter`	Ultra-fast queries (AVX2)	`Mutex`-wrapped
`TreeBloomFilter`	Hierarchical / location-aware	`Mutex`-wrapped
`ShardedBloomFilter`	High-throughput lock-free	`SharedBloomFilter`
`StripedBloomFilter`	Moderate concurrency, low overhead	`SharedBloomFilter`
`ClassicBitsFilter`	Educational / historical	`Mutex`-wrapped
`ClassicHashFilter`	Educational / historical	`Mutex`-wrapped

§Builders

Each major filter has a type-state builder that enforces correct parameter ordering at compile time:

use bloomcraft::builder::StandardBloomFilterBuilder;
use bloomcraft::filters::StandardBloomFilter;

let filter: StandardBloomFilter<&str> = StandardBloomFilterBuilder::new()
    .expected_items(10_000)
    .false_positive_rate(0.01)
    .build()
    .expect("valid params");

§Hashers

By default filters use StdHasher (FNV-1a). Enable the wyhash or xxhash features for faster alternatives, or simd for AVX2/NEON-accelerated hashing:

use bloomcraft::filters::StandardBloomFilter;
use bloomcraft::hash::WyHasher;

let filter: StandardBloomFilter<String, WyHasher> =
    StandardBloomFilter::with_hasher(10_000, 0.01, WyHasher::new())
        .expect("valid params");

§Serialization

With the serde feature enabled, filters implement Serialize / Deserialize for any format (JSON, Bincode, MessagePack, …):

use bloomcraft::StandardBloomFilter;

let filter = StandardBloomFilter::<String>::new(10_000, 0.01).unwrap();
filter.insert(&"serialize_me".to_string());
let json = serde_json::to_string(&filter).expect("serialization failed");
let restored: StandardBloomFilter<String> =
    serde_json::from_str(&json).expect("deserialization failed");
assert!(restored.contains(&"serialize_me".to_string()));

See serde_support for format-specific helper types (validation, version checks, and estimated sizes before round-tripping).

§Observable metrics

With the metrics feature, filters carry a MetricsCollector that tracks insert/query counts, latency histograms, and false-positive rates with sliding-window detection:

use bloomcraft::StandardBloomFilter;
use bloomcraft::metrics::{MetricsCollector, LatencyHistogram};

let collector = MetricsCollector::with_histogram();
let filter = StandardBloomFilter::<String>::new(10_000, 0.01).unwrap();

§Feature flags

Flag	Description	Default
`serde`	`Serialize`/`Deserialize` for all filter types	off
`bincode`	Binary serialisation helpers (used with `serde`)	off
`xxhash`	XXHash3 hasher (fast on large inputs)	off
`wyhash`	WyHash hasher (fast on small inputs)	off
`simd`	AVX2/NEON SIMD batch hashing	off
`metrics`	`MetricsCollector`, `LatencyHistogram`, `FalsePositiveTracker`	off
`trace`	Query tracing for `ScalableBloomFilter`	off
`concurrent`	`AtomicScalableBloomFilter`, `AtomicPartitionedBloomFilter`	off

§Unsafe code policy

unsafe is used in five well-audited locations, each justified with an explicit safety comment:

sync/sharded.rs — AtomicPtr<Arc<BitVec>> for lock-free reads during concurrent clear operations.
sync/striped.rs — UnsafeCell<Arc<BitVec>> guarded by parking_lot::RwLock.
sync/striped.rs — Thread-safety marker trait impls (Send + Sync) for types whose correctness follows from the RwLock guards.
hash/simd.rs — AVX2 / NEON intrinsics with runtime CPUID feature detection and a scalar fallback path.
error.rs — None (zero unsafe in error types).

All public methods are safe. Unsafe internals are not exposed.

§Notes

The crate root re-exports the most commonly used traits and types. More specialized functionality remains available through module paths.

Re-exports§

pub use crate::error::BloomCraftError;
pub use crate::error::Result;
pub use crate::core::BloomFilter;
pub use crate::core::ConcurrentBloomFilter;
pub use crate::core::DeletableBloomFilter;
pub use crate::core::MergeableBloomFilter;
pub use crate::core::MutableBloomFilter;
pub use crate::core::ScalableBloomFilter as ScalableBloomFilterTrait;
pub use crate::core::SharedBloomFilter;
pub use crate::filters::CapacityExhaustedBehavior;
pub use crate::filters::ClassicBitsFilter;
pub use crate::filters::ClassicHashFilter;
pub use crate::filters::CounterSize;
pub use crate::filters::CountingBloomFilter;
pub use crate::filters::FilterHealth;
pub use crate::filters::GrowthStrategy;
pub use crate::filters::PartitionedBloomFilter;
pub use crate::filters::QueryStrategy;
pub use crate::filters::RegisterBlockedBloomFilter;
pub use crate::filters::ScalableBloomFilter;
pub use crate::filters::StandardBloomFilter;
pub use crate::filters::TreeBloomFilter;
pub use crate::filters::QueryTrace;trace
pub use crate::filters::QueryTraceBuilder;trace
pub use crate::filters::AtomicPartitionedBloomFilter;concurrent
pub use crate::filters::AtomicScalableBloomFilter;concurrent
pub use crate::hash::BloomHasher;
pub use crate::hash::DoubleHashing;
pub use crate::hash::EnhancedDoubleHashing;
pub use crate::hash::HashStrategy;
pub use crate::hash::HashStrategyKind;
pub use crate::hash::IndexingStrategy;
pub use crate::hash::StdHasher;
pub use crate::hash::TripleHashing;
pub use crate::hash::WyHasher;wyhash
pub use crate::hash::WyHasherBuilder;wyhash
pub use crate::hash::XxHasher;xxhash
pub use crate::hash::XxHasherBuilder;xxhash
pub use crate::hash::SimdHasher;simd
pub use crate::builder::CountingBloomFilterBuilder;
pub use crate::builder::ScalableBloomFilterBuilder;
pub use crate::builder::StandardBloomFilterBuilder;
pub use crate::sync::ShardedBloomFilter;
pub use crate::sync::StripedBloomFilter;
pub use crate::serde_support as serde;serde
pub use crate::metrics::FalsePositiveTracker;metrics
pub use crate::metrics::FilterMetrics;metrics
pub use crate::metrics::LatencyHistogram;metrics
pub use crate::metrics::LatencyStats;metrics
pub use crate::metrics::MetricsCollector;metrics
pub use crate::metrics::MetricsSnapshot;metrics

Modules§

builder: Fluent, type-safe builders for every Bloom filter variant in the crate.
core: Core types, traits, and utilities for BloomCraft.
error: Error types for BloomCraft operations.
filters: Bloom filter implementations.
hash: Hash function implementations and strategies for Bloom filters.
metricsmetrics: Metrics collection for Bloom filters.
prelude: Convenient imports for common BloomCraft use.
serde_supportserde: Serialization support for Bloom filters.
sync: Concurrent and thread-safe Bloom filter implementations.
util: Internal utility functions and helpers.