review fixes

storage/blockchain/src/service/mod.rs

@@ -36,9 +36,10 @@
 //! - The last [`BCReadHandle`] is dropped => reader thread-pool exits
 //! - The last [`BCWriteHandle`] is dropped => writer thread exits
 //!
-//! Upon dropping the [`cuprate_database::Env`]:
+//! TODO: update this when ConcreteEnv is removed
+//! Upon dropping the [`cuprate_database::ConcreteEnv`]:
 //! - All un-processed database transactions are completed
-//! - All data gets flushed to disk (caused by [`Drop::drop`] impl on `Env`)
+//! - All data gets flushed to disk (caused by [`Drop::drop`] impl on `ConcreteEnv`)
 //!
 //! ## Request and Response
 //! To interact with the database (whether reading or writing data),
@@ -129,8 +130,6 @@ pub use write::init_write_service;
 
 mod free;
 pub use free::init;
-
-// Internal type aliases for `service`.
 mod types;
 pub use types::{BCReadHandle, BCWriteHandle};
 

storage/blockchain/src/service/read.rs

@@ -6,8 +6,10 @@ use std::{
     sync::Arc,
 };
 
-use rayon::iter::{IntoParallelIterator, ParallelIterator};
-use rayon::ThreadPool;
+use rayon::{
+    iter::{IntoParallelIterator, ParallelIterator},
+    ThreadPool,
+};
 use thread_local::ThreadLocal;
 
 use cuprate_database::{ConcreteEnv, DatabaseRo, Env, EnvInner, RuntimeError};
@@ -31,18 +33,18 @@ use crate::{
         free::{compact_history_genesis_not_included, compact_history_index_to_height_offset},
         types::{BCReadHandle, ResponseResult},
     },
-    tables::OpenTables,
-    tables::{BlockHeights, BlockInfos, Tables},
+    tables::{BlockHeights, BlockInfos, OpenTables, Tables},
     types::{Amount, AmountIndex, BlockHash, BlockHeight, KeyImage, PreRctOutputId},
 };
 
 //---------------------------------------------------------------------------------------------------- init_read_service
-/// Initialize the [`BCReadHandle`] thread-pool backed by `rayon`.
+/// Initialize the [`BCReadHandle`] thread-pool backed by [`rayon`].
 ///
 /// This spawns `threads` amount of reader threads
 /// attached to `env` and returns a handle to the pool.
 ///
-/// Should be called _once_ per actual database.
+/// Should be called _once_ per actual database. Calling this function more than once will create
+/// multiple unnecessary rayon thread-pools.
 #[cold]
 #[inline(never)] // Only called once.
 pub fn init_read_service(env: Arc<ConcreteEnv>, threads: ReaderThreads) -> BCReadHandle {
@@ -52,7 +54,8 @@ pub fn init_read_service(env: Arc<ConcreteEnv>, threads: ReaderThreads) -> BCRea
 /// Initialize the blockchain database read service, with a specific rayon thread-pool instead of
 /// creating a new one.
 ///
-/// Should be called _once_ per actual database.
+/// Should be called _once_ per actual database, although nothing bad will happen, cloning the [`BCReadHandle`]
+/// is the correct way to get multiple handles to the database.
 #[cold]
 #[inline(never)] // Only called once.
 pub fn init_read_service_with_pool(env: Arc<ConcreteEnv>, pool: Arc<ThreadPool>) -> BCReadHandle {

storage/blockchain/src/service/types.rs

@@ -1,6 +1,4 @@
 //! Database service type aliases.
-//!
-//! Only used internally for our `tower::Service` impls.
 
 //---------------------------------------------------------------------------------------------------- Use
 use cuprate_database::RuntimeError;

storage/service/README.md

@@ -0,0 +1,6 @@
+# Cuprate's `tower::Service` database abstraction.
+
+This crate contains the building blocks for creating a `tower::Service` interface to `cuprate_blockchain`.
+
+It is split into 2 `tower::Service`s a read service which is backed by a `rayon::ThreadPool` and a write service which
+spawns a single thread to handle write requests.

storage/service/src/reader_threads.rs

@@ -1,12 +1,9 @@
-//! Database [`Env`](crate::Env) configuration.
+//! Reader thread-pool configuration and initiation.
 //!
-//! This module contains the main [`Config`]uration struct
-//! for the database [`Env`](crate::Env)ironment, and data
-//! structures related to any configuration setting.
+//! This module contains [`ReaderThreads`] which allow specifying the amount of
+//! reader threads for the [`rayon::ThreadPool`].
 //!
-//! These configurations are processed at runtime, meaning
-//! the `Env` can/will dynamically adjust its behavior
-//! based on these values.
+//! It also contains [`init_thread_pool`] which initiates the thread-pool.
 
 //---------------------------------------------------------------------------------------------------- Import
 use std::{num::NonZeroUsize, sync::Arc};
@@ -31,6 +28,8 @@ pub fn init_thread_pool(reader_threads: ReaderThreads) -> Arc<ThreadPool> {
 }
 
 //---------------------------------------------------------------------------------------------------- ReaderThreads
+/// Amount of database reader threads to spawn
+///
 /// This controls how many reader thread `service`'s
 /// thread-pool will spawn to receive and send requests/responses.
 ///

storage/service/src/service/read.rs

@@ -44,7 +44,8 @@ where
 {
     /// Creates the [`DatabaseReadService`] with the provided backing thread-pool.
     ///
-    /// Should be called _once_ per actual database.
+    /// Should be called _once_ per actual database, although nothing bad will happen, cloning the [`DatabaseReadService`]
+    /// is the correct way to get multiple handles to the database.
     #[cold]
     #[inline(never)] // Only called once.
     pub fn new(