hashiverse_lib/tools/pow_generator/mod.rs
1//! # Proof-of-work search engine
2//!
3//! Proof-of-work is mandatory on every outgoing RPC, every peer announcement, and every
4//! piece of report/feedback — so finding a PoW solution quickly is on the hot path for
5//! virtually every client and server action. This module isolates that work behind a
6//! single trait, [`pow_generator::PowGenerator`], so the calling code doesn't care
7//! whether it's running on a 32-core server or a single-threaded WASM Web Worker.
8//!
9//! ## Implementations
10//!
11//! - [`native_parallel_pow_generator::NativeParallelPowGenerator`] — rayon +
12//! `tokio::task::spawn_blocking`, saturates every CPU core on native targets.
13//! - [`single_threaded_pow_generator::SingleThreadedPowGenerator`] — single-threaded
14//! fallback that works on every target including WASM. Browser clients run this
15//! (with a relaxed `pow_min`) because Web Workers don't expose thread pools.
16//!
17//! ## Observability
18//!
19//! [`pow_generator::JobTracker`] + [`pow_generator::PowJobStatus`] expose the set of
20//! in-flight PoW jobs and the best-so-far pow for each. The web client surfaces this in
21//! the UI so that when a post feels slow to send the user can see it's because PoW is
22//! still grinding.
23//!
24//! ## Shared loop
25//!
26//! [`pow_generator::generate_loop`] is the one-true batching loop used by both
27//! implementations: repeatedly call [`pow_generator::PowGenerator::generate_best_effort`]
28//! in 64K-attempt batches, update the tracker, and bail as soon as a batch returns
29//! `pow >= pow_min`. Every batch also yields to the runtime so on single-threaded targets
30//! other tasks still get a chance to run.
31
32pub mod pow_generator;
33pub mod native_parallel_pow_generator;
34pub mod single_threaded_pow_generator;