refactor(Echo): Improve code clarity, documentation, and API consistency

Refactored the Echo scheduler crate to enhance readability, maintainability, and consistency with Land's architectural principles. Key changes include:
- Renamed `SchedulerBuilder::Count` to `WithWorkerCount` and `SchedulerBuilder::Queue` to `WithQueue` for clearer fluent API semantics
- Simplified work-stealing logic in `Queue::StealingQueue` with improved error handling and reduced allocations
- Updated module and function documentation throughout to better explain Echo's role as Mountain's execution engine
- Revised README and Deep Dive docs to reflect architectural relationships with Mountain's ActionEffect system
- Renamed internal fields for clarity (e.g., `Handle` → `WorkerHandles`, `Running` → `IsRunning`)

These changes ensure Echo remains a robust foundation for Mountain's structured concurrency model, where it executes ActionEffect futures via Tauri's async runtime. The improved documentation clarifies Echo's integration points with Mountain's Track dispatcher and environment services.

Refs #291 #292 #290

Author: NikolaRHristov

README.md

@@ -18,9 +18,9 @@
 
 Welcome to **Echo**! This crate provides a powerful, structured concurrency
 runtime for Rust applications, built on a high-performance **work-stealing
-scheduler**. It is designed to be the core execution engine for the `Mountain`
-backend, integrating seamlessly with the declarative `ActionEffect` system
-defined in the `Common` crate. **Echo** moves beyond simple task spawning
+scheduler**. It is designed to be the core execution engine for application
+backends like `Mountain`, integrating seamlessly with declarative systems like
+the `ActionEffect` pattern. **Echo** moves beyond simple task spawning
 (`tokio::spawn`) to provide a robust framework for managing, prioritizing, and
 executing complex asynchronous workflows with resilience and efficiency.
 
@@ -58,13 +58,13 @@ executing complex asynchronous workflows with resilience and efficiency.
 
 ## Core Architecture Principles 🏗️
 
-| Principle                  | Description                                                                                                                                                     | Key Components Involved                                               |
-| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
-| **Performance**            | Use lock-free data structures (`crossbeam-deque`) and a high-performance work-stealing algorithm to achieve maximum throughput and low-latency task execution.  | `Queue::StealingQueue`, `Scheduler::Worker`                           |
-| **Structured Concurrency** | Manage all asynchronous operations within a supervised pool of workers, providing graceful startup and shutdown, unlike fire-and-forget `tokio::spawn`.         | `Scheduler::Scheduler`, `Scheduler::SchedulerBuilder`                 |
-| **Decoupling**             | Separate the generic **Queueing Logic** from the application-specific **Scheduler Implementation**. The scheduler uses the queue to run its tasks.              | `Queue::StealingQueue<T>`, `Scheduler::Scheduler`, `Task::Task::Task` |
-| **Resilience**             | The scheduler's design is inherently resilient; the failure of one task (if it panics) is contained within its `tokio` task and does not crash the worker pool. | `Scheduler::Worker::Run`                                              |
-| **Composability**          | Provide a simple `Submit` API that accepts any `Future<Output = ()>`, making it easy to integrate with any asynchronous Rust code.                              | `Task::Task::Task`, `Scheduler::Scheduler::Submit`                    |
+| Principle                  | Description                                                                                                                                                     | Key Components Involved                                             |
+| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ |
+| **Performance**            | Use lock-free data structures (`crossbeam-deque`) and a high-performance work-stealing algorithm to achieve maximum throughput and low-latency task execution.  | `Queue::StealingQueue`, `Scheduler::Worker`                         |
+| **Structured Concurrency** | Manage all asynchronous operations within a supervised pool of workers, providing graceful startup and shutdown, unlike fire-and-forget `tokio::spawn`.         | `Scheduler::Scheduler`, `Scheduler::SchedulerBuilder`               |
+| **Decoupling**             | Separate the generic **Queueing Logic** from the application-specific **Scheduler Implementation**. The scheduler uses the queue to run its tasks.              | `Queue::StealingQueue<TTask>`, `Scheduler::Scheduler`, `Task::Task` |
+| **Resilience**             | The scheduler's design is inherently resilient; the failure of one task (if it panics) is contained within its `tokio` task and does not crash the worker pool. | `Scheduler::Worker::Run`                                            |
+| **Composability**          | Provide a simple `Submit` API that accepts any `Future<Output = ()>`, making it easy to integrate with any asynchronous Rust code.                              | `Task::Task`, `Scheduler::Scheduler::Submit`                        |
 
 ---
 
@@ -94,8 +94,8 @@ graph LR
 	end
 
 	subgraph "Mountain (Application Logic)"
-        AppRuntime["Mountain AppRuntime"]:::mountain
-        MountainEnv["MountainEnvironment (Service Impls)"]:::mountain
+        ApplicationRunTime["Mountain ApplicationRunTime"]:::mountain
+        MountainEnvironment["MountainEnvironment (Service Impls)"]:::mountain
         Track["Track (Request Dispatcher)"]:::mountain
 	end
 
@@ -109,10 +109,10 @@ graph LR
         WorkerPool -- Pull tasks from --> WorkStealingQueue;
 	end
 
-    Track -- Dispatches --> ActionEffect;
-    ActionEffect -- Is run by --> AppRuntime;
-    AppRuntime -- Submits Future to --> Scheduler;
-    WorkerPool -- Executes Future using --> MountainEnv;
+    Track -- Dispatches to --> ApplicationRunTime;
+    ApplicationRunTime -- Creates Future from --> ActionEffect;
+    ApplicationRunTime -- Submits Future to --> Scheduler;
+    WorkerPool -- Executes Future using --> MountainEnvironment;
 ```
 
 ---
@@ -126,9 +126,9 @@ separation of concerns:
 Echo/
 └── Source/
     ├── Library.rs               # Crate root, declares all modules.
-    ├── Scheduler/               # The main public API: Scheduler and Builder. Consumes the Queue.
+    ├── Scheduler/               # The main public API: Scheduler and SchedulerBuilder.
     ├── Queue/                   # The generic, high-performance work-stealing queue library.
-    └── Task/                    # The application-specific definition of a Task and its Priority.
+    └── Task/                    # The concrete definition of a Task and its Priority.
 ```
 
 ---
@@ -157,28 +157,21 @@ Echo = { git = "https://github.com/CodeEditorLand/Echo.git", branch = "Current"
 `Echo` is designed to be integrated into an application's main entry point and
 used throughout the application, often via a shared context or runtime.
 
-1.  **Define the Public API:** In your library's root (`lib.rs` or `main.rs`),
-    re-export the primary components for easy access.
-
-    ```rust
-    // In your application's lib.rs
-    pub use Echo::Scheduler::{Scheduler, SchedulerBuilder};
-    pub use Echo::Task::Priority::Priority;
-    ```
-
-2.  **Initialize the Scheduler:** Create and start the scheduler when your
+1.  **Initialize the Scheduler:** Create and start the scheduler when your
     application starts. It is typically wrapped in an `Arc` to be shared safely
     across your application.
 
     ```rust
     // In your application's main function
     use std::sync::Arc;
+    use Echo::Scheduler::SchedulerBuilder;
+    use Echo::Task::Priority;
 
     // Use the fluent builder to configure and build the scheduler
-    let Scheduler = Arc::new(SchedulerBuilder::Create().Count(8).Build());
+    let Scheduler = Arc::new(SchedulerBuilder::Create().WithWorkerCount(8).Build());
     ```
 
-3.  **Submit Tasks:** Use the `Scheduler` instance to submit asynchronous work
+2.  **Submit Tasks:** Use the `Scheduler` instance to submit asynchronous work
     from anywhere in your application.
 
     ```rust
@@ -195,13 +188,13 @@ used throughout the application, often via a shared context or runtime.
     Scheduler.Submit(async { /* critical work */ }, Priority::High);
     ```
 
-4.  **Graceful Shutdown:** Before your application exits, ensure a clean
+3.  **Graceful Shutdown:** Before your application exits, ensure a clean
     shutdown of all worker threads.
 
     ```rust
     // In your application's shutdown sequence
-    // Note: Arc::get_mut requires the Arc to have only one strong reference.
-    if let Some(mut Scheduler) = Arc::get_mut(&mut Scheduler) {
+    // Note: Arc::try_unwrap requires the Arc to have only one strong reference.
+    if let Ok(mut Scheduler) = Arc::try_unwrap(Scheduler) {
         Scheduler.Stop().await;
     }
     ```

Source/Library.rs

@@ -1,15 +1,14 @@
-//! A Resilient, High-Performance Task Scheduler.
+//! # Echo: A Resilient, High-Performance Task Scheduler
 //!
 //! Provides a structured concurrency runtime for Rust applications, built on a
 //! high-performance, priority-aware, work-stealing scheduler. It is designed
-//! to be a robust and efficient core execution engine.
+//! to be a robust and efficient core execution engine for demanding,
+//! concurrent workloads.
 
 #![allow(non_snake_case, non_camel_case_types)]
 
 // --- Crate Modules ---
 // Declares the main modules that constitute the library.
 pub mod Queue;
-
 pub mod Scheduler;
-
 pub mod Task;

Source/Queue/StealingQueue.rs

@@ -1,8 +1,8 @@
-//! A generic, priority-aware, work-stealing queue implementation.
+//! # StealingQueue
 //!
-//! This module is self-contained and can be used by any scheduler or
-//! application to manage and distribute tasks of any type that can be
-//! prioritized.
+//! A generic, priority-aware, work-stealing queue implementation. This module
+//! is self-contained and can be used by any scheduler or application to manage
+//! and distribute tasks of any type that can be prioritized.
 
 #![allow(non_snake_case, non_camel_case_types)]
 
@@ -20,152 +20,138 @@ pub trait Prioritized {
 	fn Rank(&self) -> Self::Kind;
 }
 
-/// Defines the internal priority levels used by the generic queue.
+/// Defines the internal priority levels used by the generic queue. These map
+/// directly to the different deques managed by the system.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Priority {
 	High,
-
 	Normal,
-
 	Low,
 }
 
 /// Holds the queue components that are safe to share across all threads.
 ///
-/// This includes global injectors for submitting new tasks and stealers for
-/// taking tasks from other workers, organized by priority level.
-pub struct Share<T> {
-	/// Global, multi-producer queues for each priority.
-	pub Injector:(Injector<T>, Injector<T>, Injector<T>),
-
-	/// Share handles for stealing tasks from each worker's queue.
-	pub Stealer:(Vec<Stealer<T>>, Vec<Stealer<T>>, Vec<Stealer<T>>),
+/// This includes global injectors for submitting new tasks from any context and
+/// stealers for taking tasks from other workers' deques, organized by priority
+/// level.
+pub struct Share<TTask> {
+	/// Global, multi-producer queues for each priority level.
+	pub Injector:(Injector<TTask>, Injector<TTask>, Injector<TTask>),
+
+	/// Shared handles for stealing tasks from each worker's local queue.
+	pub Stealer:(Vec<Stealer<TTask>>, Vec<Stealer<TTask>>, Vec<Stealer<TTask>>),
 }
 
 /// A generic, priority-aware, work-stealing queue.
 ///
 /// This is the public-facing entry point for submitting tasks. It is generic
-/// over any task type `T` that implements the `Prioritized` trait.
-pub struct StealingQueue<T:Prioritized<Kind = Priority>> {
+/// over any task type `TTask` that implements the `Prioritized` trait.
+pub struct StealingQueue<TTask:Prioritized<Kind = Priority>> {
 	/// A shared, thread-safe pointer to the queue's shared components.
-	Share:Arc<Share<T>>,
+	Share:Arc<Share<TTask>>,
 }
 
 /// Contains all necessary components for a single worker thread to operate.
 ///
 /// This includes the thread-local `Worker` deques, which are not safe to share,
-/// making this context object the sole owner of a worker's private queues.
-pub struct Context<T> {
+/// making this `Context` object the sole owner of a worker's private queues.
+pub struct Context<TTask> {
 	/// A unique identifier for the worker, used to avoid self-stealing.
 	pub Identifier:usize,
 
 	/// Thread-local work queues for each priority level.
-	pub Local:(Worker<T>, Worker<T>, Worker<T>),
+	pub Local:(Worker<TTask>, Worker<TTask>, Worker<TTask>),
 
 	/// A reference to the shared components of the entire queue system.
-	pub Share:Arc<Share<T>>,
+	pub Share:Arc<Share<TTask>>,
 }
 
-impl<T:Prioritized<Kind = Priority>> StealingQueue<T> {
+impl<TTask:Prioritized<Kind = Priority>> StealingQueue<TTask> {
 	/// Creates a complete work-stealing queue system.
 	///
 	/// This function initializes all the necessary queues, both shared and
 	/// thread-local, for a given number of workers.
 	///
-	/// Returns a tuple containing:
+	/// # Returns
+	///
+	/// A tuple containing:
 	/// 1. The public-facing `StealingQueue` for submitting new tasks.
 	/// 2. A `Vec` of `Context` objects, one for each worker thread to own.
-	pub fn Create(Count:usize) -> (Self, Vec<Context<T>>) {
-		let mut High:Vec<Worker<T>> = Vec::with_capacity(Count);
-
-		let mut Normal:Vec<Worker<T>> = Vec::with_capacity(Count);
-
-		let mut Low:Vec<Worker<T>> = Vec::with_capacity(Count);
+	pub fn Create(Count:usize) -> (Self, Vec<Context<TTask>>) {
+		let mut High:Vec<Worker<TTask>> = Vec::with_capacity(Count);
+		let mut Normal:Vec<Worker<TTask>> = Vec::with_capacity(Count);
+		let mut Low:Vec<Worker<TTask>> = Vec::with_capacity(Count);
 
 		// For each priority level, create a thread-local worker queue and its
 		// corresponding shared stealer.
-		let StealerHigh:Vec<Stealer<T>> = (0..Count)
+		let StealerHigh:Vec<Stealer<TTask>> = (0..Count)
 			.map(|_| {
 				let Worker = Worker::new_fifo();
-
 				let Stealer = Worker.stealer();
-
 				High.push(Worker);
-
 				Stealer
 			})
 			.collect();
 
-		let StealerNormal:Vec<Stealer<T>> = (0..Count)
+		let StealerNormal:Vec<Stealer<TTask>> = (0..Count)
 			.map(|_| {
 				let Worker = Worker::new_fifo();
-
 				let Stealer = Worker.stealer();
-
 				Normal.push(Worker);
-
 				Stealer
 			})
 			.collect();
 
-		let StealerLow:Vec<Stealer<T>> = (0..Count)
+		let StealerLow:Vec<Stealer<TTask>> = (0..Count)
 			.map(|_| {
 				let Worker = Worker::new_fifo();
-
 				let Stealer = Worker.stealer();
-
 				Low.push(Worker);
-
 				Stealer
 			})
 			.collect();
 
 		// Bundle all shared components into an Arc for safe sharing.
 		let Share = Arc::new(Share {
 			Injector:(Injector::new(), Injector::new(), Injector::new()),
-
 			Stealer:(StealerHigh, StealerNormal, StealerLow),
 		});
 
 		// Create a unique context for each worker, giving it ownership of its
 		// local queues and a reference to the shared components.
-		let mut Context = Vec::with_capacity(Count);
-
+		let mut Contexts = Vec::with_capacity(Count);
 		for Identifier in 0..Count {
-			Context.push(Context {
+			Contexts.push(Context {
 				Identifier,
-
 				Local:(High.remove(0), Normal.remove(0), Low.remove(0)),
-
 				Share:Share.clone(),
 			});
 		}
 
 		let Queue = Self { Share };
-
-		(Queue, Context)
+		(Queue, Contexts)
 	}
 
 	/// Submits a new task to the appropriate global queue based on its
 	/// priority. This method is thread-safe and can be called from any
 	/// context.
-	pub fn Submit(&self, Task:T) {
+	pub fn Submit(&self, Task:TTask) {
 		match Task.Rank() {
 			Priority::High => self.Share.Injector.0.push(Task),
-
 			Priority::Normal => self.Share.Injector.1.push(Task),
-
 			Priority::Low => self.Share.Injector.2.push(Task),
 		}
 	}
 }
 
-impl<T> Context<T> {
+impl<TTask> Context<TTask> {
 	/// Finds the next available task for the worker to execute.
-	// This method implements the complete work-finding logic:
-	/// 1. Check local queue (high to low priority).
-	/// 2. Steal from the system (high to low priority).
-	pub fn Next(&self) -> Option<T> {
+	///
+	/// This method implements the complete work-finding logic:
+	/// 1. Check local deques (from high to low priority).
+	/// 2. If local deques are empty, attempt to steal from the system (from
+	///    high to low priority).
+	pub fn Next(&self) -> Option<TTask> {
 		self.Local
 			.0
 			.pop()
@@ -178,10 +164,15 @@ impl<T> Context<T> {
 
 	/// Attempts to steal a task from a specific priority set.
 	///
-	/// It first tries to steal a batch from the global injector queue. If that
-	/// fails, it attempts to steal from a randomly chosen peer worker to ensure
-	/// fair distribution and avoid contention hotspots.
-	pub fn Steal<'a>(&self, Injector:&'a Injector<T>, Stealer:&'a [Stealer<T>], Local:&'a Worker<T>) -> Option<T> {
+	/// It first tries to steal a batch from the global injector queue for that
+	/// priority. If that fails, it attempts to steal from a randomly chosen
+	/// peer worker to ensure fair distribution and avoid contention hotspots.
+	pub fn Steal<'a>(
+		&self,
+		Injector:&'a Injector<TTask>,
+		Stealers:&'a [Stealer<TTask>],
+		Local:&'a Worker<TTask>,
+	) -> Option<TTask> {
 		// First, try to steal a batch from the global injector.
 		// `steal_batch_and_pop` is efficient: it moves a batch into our local
 		// queue and returns one task immediately if successful.
@@ -190,14 +181,15 @@ impl<T> Context<T> {
 		}
 
 		// If the global queue is empty, try stealing from peers.
-		let Count = Stealer.len();
-
+		let Count = Stealers.len();
 		if Count <= 1 {
+			// Cannot steal if there are no other workers.
 			return None;
 		}
 
 		// Allocation-free random iteration: pick a random starting point.
-		let Start = rand::rng().random_range(0..Count);
+		let mut Rng = rand::rng();
+		let Start = Rng.random_range(0..Count);
 
 		// Iterate through all peers starting from the random offset.
 		for i in 0..Count {
@@ -208,7 +200,7 @@ impl<T> Context<T> {
 				continue;
 			}
 
-			if let Steal::Success(Task) = Stealer[Index].steal_batch_and_pop(Local) {
+			if let Steal::Success(Task) = Stealers[Index].steal_batch_and_pop(Local) {
 				return Some(Task);
 			}
 		}