Update docs

Author: iambriccardo

relay-threading/src/builder.rs

@@ -6,10 +6,11 @@ use std::sync::Arc;
 use crate::pool::{AsyncPool, Thread};
 use crate::pool::{CustomSpawn, DefaultSpawn, ThreadSpawn};
 
-/// A builder for constructing an [`AsyncPool`] with custom configurations.
+/// [`AsyncPoolBuilder`] provides a flexible way to configure and build an [`AsyncPool`] for executing
+/// asynchronous tasks concurrently on dedicated threads.
 ///
-/// Use this builder to fine-tune the performance and threading behavior of your asynchronous
-/// task pool.
+/// This builder enables you to customize the number of threads, concurrency limits, thread naming,
+/// and panic handling strategies.
 pub struct AsyncPoolBuilder<S = DefaultSpawn> {
     pub(crate) runtime: tokio::runtime::Handle,
     pub(crate) thread_name: Option<Box<dyn FnMut(usize) -> String>>,
@@ -23,7 +24,9 @@ pub struct AsyncPoolBuilder<S = DefaultSpawn> {
 }
 
 impl AsyncPoolBuilder<DefaultSpawn> {
-    /// Creates a new [`AsyncPoolBuilder`] with default settings.
+    /// Initializes a new [`AsyncPoolBuilder`] with default settings.
+    ///
+    /// The builder is tied to the provided [`tokio::runtime::Handle`] and prepares to configure an [`AsyncPool`].
     pub fn new(runtime: tokio::runtime::Handle) -> AsyncPoolBuilder<DefaultSpawn> {
         AsyncPoolBuilder {
             runtime,
@@ -41,8 +44,10 @@ impl<S> AsyncPoolBuilder<S>
 where
     S: ThreadSpawn,
 {
-    /// Specifies a custom hook to generate the thread name given the thread index within the
-    /// [`AsyncPool`].
+    /// Specifies a custom naming convention for threads in the [`AsyncPool`].
+    ///
+    /// The provided closure receives the thread's index and returns a name,
+    /// which can be useful for debugging and logging.
     pub fn thread_name<F>(mut self, thread_name: F) -> Self
     where
         F: FnMut(usize) -> String + 'static,
@@ -51,11 +56,14 @@ where
         self
     }
 
-    /// Specifies a custom hook to handle the panic happening in one of the threads of the
-    /// [`AsyncPool`].
+    /// Sets a custom panic handler for threads in the [`AsyncPool`].
+    ///
+    /// If a thread panics, the provided handler will be invoked so that you can perform
+    /// custom error handling or cleanup.
     ///
-    /// The `panic_handler` is called once for each panicking thread with the error caught in the
-    /// panicking as argument.
+    /// # Panics
+    ///
+    /// In the absence of this handler, thread panics will propagate.
     pub fn thread_panic_handler<F>(mut self, panic_handler: F) -> Self
     where
         F: Fn(Box<dyn Any + Send>) + Send + Sync + 'static,
@@ -64,11 +72,14 @@ where
         self
     }
 
-    /// Specifies a custom hook to handle the panic happening in one of the tasks of the
-    /// [`AsyncPool`].
+    /// Sets a custom panic handler for tasks executed by the [`AsyncPool`].
+    ///
+    /// This handler is used to manage panics that occur during task execution, allowing for graceful
+    /// error handling.
     ///
-    /// The `panic_handler` is called once for each panicking task with the error caught in the
-    /// panicking as argument.
+    /// # Panics
+    ///
+    /// Without a handler, panics in tasks will propagate.
     pub fn task_panic_handler<F>(mut self, panic_handler: F) -> Self
     where
         F: Fn(Box<dyn Any + Send>) + Send + Sync + 'static,
@@ -77,7 +88,10 @@ where
         self
     }
 
-    /// Specifies a custom hook to dynamically adjust thread settings for the [`AsyncPool`].
+    /// Configures a custom thread spawning procedure for the [`AsyncPool`].
+    ///
+    /// This method allows you to adjust thread settings (e.g. naming, stack size) before thread creation,
+    /// making it possible to apply application-specific configurations.
     pub fn spawn_handler<F>(self, spawn_handler: F) -> AsyncPoolBuilder<CustomSpawn<F>>
     where
         F: FnMut(Thread) -> io::Result<()>,
@@ -93,21 +107,26 @@ where
         }
     }
 
-    /// Sets the number of executor threads for running tasks in the [`AsyncPool`].
+    /// Sets the number of worker threads for the [`AsyncPool`].
+    ///
+    /// This determines how many dedicated threads will be available for running tasks concurrently.
     pub fn num_threads(mut self, num_threads: usize) -> Self {
         self.num_threads = num_threads;
         self
     }
 
-    /// Adjusts the maximum number of concurrent tasks allowed per executor in the [`AsyncPool`].
+    /// Sets the maximum number of concurrent tasks per thread in the [`AsyncPool`].
     ///
-    /// The max concurrency determines how many futures can be polled simultaneously.
+    /// This controls how many futures can be polled simultaneously on each worker thread.
     pub fn max_concurrency(mut self, max_concurrency: usize) -> Self {
         self.max_concurrency = max_concurrency;
         self
     }
 
-    /// Finalizes the configuration and constructs an operational [`AsyncPool`] for executing tasks.
+    /// Constructs an [`AsyncPool`] based on the configured settings.
+    ///
+    /// Finalizing the builder sets up dedicated worker threads and configures the executor
+    /// to enforce the specified concurrency limits.
     pub fn build<F>(self) -> Result<AsyncPool<F>, io::Error>
     where
         F: Future<Output = ()> + Send + 'static,

relay-threading/src/lib.rs

@@ -22,13 +22,6 @@
 //! backpressure - when workers are overwhelmed, task submission will block until capacity becomes
 //! available, preventing resource exhaustion.
 //!
-//! ## Modules
-//!
-//! - **builder**: Contains the [`AsyncPoolBuilder`] which configures and constructs an [`AsyncPool`].
-//! - **multiplexing**: Provides the [`Multiplexed`] future that manages and executes multiple asynchronous tasks concurrently.
-//! - **pool**: Implements the [`AsyncPool`] and related types, such as [`Thread`]. Together they encapsulate the logic
-//!   for scheduling tasks across multiple threads.
-//!
 //! ## Usage Example
 //!
 //! ```rust
@@ -55,11 +48,6 @@
 //!
 //! Both the async pool and its task multiplexer support custom panic handlers, allowing graceful
 //! recovery from panics in either thread execution or individual tasks.
-//!
-//! For more details on specific functionalities, refer to the documentation in the submodules:
-//! - [`builder`]
-//! - [`multiplexing`]
-//! - [`pool`]
 
 mod builder;
 mod multiplexing;

relay-threading/src/multiplexing.rs

@@ -12,10 +12,10 @@ use pin_project_lite::pin_project;
 use tokio::task::Unconstrained;
 
 pin_project! {
-    /// Manages a collection of asynchronous tasks that are executed concurrently.
+    /// Manages concurrent execution of asynchronous tasks.
     ///
-    /// This helper is designed for use within the [`Multiplexed`] executor to schedule and drive tasks
-    /// while respecting a set concurrency limit.
+    /// This internal structure collects and drives futures concurrently, invoking a panic handler (if provided)
+    /// when a task encounters a panic.
     struct Tasks<F> {
         #[pin]
         futures: FuturesUnordered<Unconstrained<CatchUnwind<AssertUnwindSafe<F>>>>,
@@ -24,9 +24,9 @@ pin_project! {
 }
 
 impl<F> Tasks<F> {
-    /// Initializes a new [`Tasks`] collection for managing asynchronous tasks.
+    /// Creates a new task manager.
     ///
-    /// This collection is used internally by [`Multiplexed`] to schedule task execution.
+    /// This internal constructor initializes a new collection for tracking asynchronous tasks.
     #[allow(clippy::type_complexity)]
     fn new(panic_handler: Option<Arc<dyn Fn(Box<dyn Any + Send>) + Send + Sync>>) -> Self {
         Self {
@@ -50,21 +50,16 @@ impl<F> Tasks<F>
 where
     F: Future<Output = ()>,
 {
-    /// Adds a new asynchronous task to the collection.
-    ///
-    /// Use this method to submit additional tasks for concurrent execution.
+    /// Adds a future to the collection for concurrent execution.
     fn push(&mut self, future: F) {
         let future = AssertUnwindSafe(future).catch_unwind();
         self.futures.push(tokio::task::unconstrained(future));
     }
 
-    /// Drives the scheduled tasks until one remains pending.
-    ///
-    /// This method advances the execution of managed tasks until it encounters a task
-    /// that is not immediately ready, ensuring that completed tasks are processed and the
-    /// multiplexer can schedule new ones.
+    /// Drives the execution of collected tasks until a pending state is encountered.
     ///
-    /// For any task that panics, the `panic_handler` callback will be called.
+    /// If a future panics and a panic handler is provided, the handler is invoked.
+    /// Otherwise, the panic is propagated.
     fn poll_tasks_until_pending(self: Pin<&mut Self>, cx: &mut Context<'_>) {
         let mut this = self.project();
 
@@ -98,12 +93,14 @@ where
 }
 
 pin_project! {
-    /// A task multiplexer that concurrently executes asynchronous tasks while limiting the maximum
-    /// number of tasks running simultaneously.
+    /// [`Multiplexed`] is a future that concurrently schedules asynchronous tasks from a stream while ensuring that
+    /// the number of concurrently executing tasks does not exceed a specified limit.
+    ///
+    /// This multiplexer is primarily used by the [`AsyncPool`] to manage task execution on worker threads.
     ///
-    /// The [`Multiplexed`] executor retrieves tasks from a stream and schedules them according to the
-    /// specified concurrency limit. The multiplexer completes once all tasks have been executed and
-    /// no further tasks are available.
+    /// # Panics
+    ///
+    /// If any task panics without a custom panic handler, the panic will propagate.
     pub struct Multiplexed<S, F> {
         max_concurrency: usize,
         #[pin]
@@ -112,14 +109,15 @@ pin_project! {
         tasks: Tasks<F>,
     }
 }
+
 impl<S, F> Multiplexed<S, F>
 where
     S: Stream<Item = F>,
 {
-    /// Constructs a new [`Multiplexed`] executor with a concurrency limit and a stream of tasks.
+    /// Creates a new [`Multiplexed`] instance with a defined concurrency limit and a stream of tasks.
     ///
-    /// This multiplexer should be awaited until completion, at which point all submitted tasks
-    /// will have been executed.
+    /// Tasks from the stream will be scheduled for execution concurrently, and an optional panic handler
+    /// can be provided to manage errors during task execution.
     #[allow(clippy::type_complexity)]
     pub fn new(
         max_concurrency: usize,
@@ -141,12 +139,10 @@ where
 {
     type Output = ();
 
-    /// Drives the execution of the multiplexer by advancing scheduled tasks and fetching new ones.
+    /// Polls the [`Multiplexed`] future to drive task execution.
     ///
-    /// This method polls the collection of tasks and retrieves additional tasks from the stream until
-    /// the concurrency limit is reached or no more tasks are available. It yields `Poll::Pending` when
-    /// there is ongoing work and returns `Poll::Ready(())` only once the task stream is exhausted
-    /// and no active tasks remain.
+    /// This method repeatedly schedules new tasks from the stream while enforcing the concurrency limit.
+    /// It completes when the stream is exhausted and no active tasks remain.
     fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
         let mut this = self.project();