Author: NikolaRHristov

README.md

@@ -162,38 +162,46 @@ used throughout the application, often via a shared context or runtime.
     across your application.
 
     ```rust
-    // In your application's main function
+// 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
+// Use the fluent builder to configure and build the scheduler
+   
     let Scheduler = Arc::new(SchedulerBuilder::Create().WithWorkerCount(8).Build());
     ```
 
 2.  **Submit Tasks:** Use the `Scheduler` instance to submit asynchronous work
     from anywhere in your application.
 
     ```rust
-    // An example async block to be run by the scheduler
+// An example async block to be run by the scheduler
+   
     let MyTask = async {
         println!("This is running on an Echo worker thread!");
-        // ... perform some work ...
+// ... perform some work ...
+       
     };
 
-    // Submit the task with a desired priority
+// Submit the task with a desired priority
+   
     Scheduler.Submit(MyTask, Priority::Normal);
 
-    // Another example with high priority
+// Another example with high priority
+   
     Scheduler.Submit(async { /* critical work */ }, Priority::High);
     ```
 
 3.  **Graceful Shutdown:** Before your application exits, ensure a clean
     shutdown of all worker threads.
 
     ```rust
-    // In your application's shutdown sequence
-    // Note: Arc::try_unwrap requires the Arc to have only one strong reference.
+// In your application's shutdown sequence
+   
+// 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

@@ -3,12 +3,15 @@
 //! 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 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

@@ -25,7 +25,9 @@ pub trait Prioritized {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Priority {
 	High,
+
 	Normal,
+
 	Low,
 }
 
@@ -54,6 +56,7 @@ pub struct StealingQueue<TTask:Prioritized<Kind = Priority>> {
 /// 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<TTask> {
 	/// A unique identifier for the worker, used to avoid self-stealing.
@@ -79,56 +82,72 @@ impl<TTask:Prioritized<Kind = Priority>> StealingQueue<TTask> {
 	/// 2. A `Vec` of `Context` objects, one for each worker thread to own.
 	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<TTask>> = (0..Count)
 			.map(|_| {
 				let Worker = Worker::new_fifo();
+
 				let Stealer = Worker.stealer();
+
 				High.push(Worker);
+
 				Stealer
 			})
 			.collect();
 
 		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<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 Contexts = Vec::with_capacity(Count);
+
 		for Identifier in 0..Count {
 			Contexts.push(Context {
 				Identifier,
+
 				Local:(High.remove(0), Normal.remove(0), Low.remove(0)),
+
 				Share:Share.clone(),
 			});
 		}
 
 		let Queue = Self { Share };
+
 		(Queue, Contexts)
 	}
 
@@ -138,7 +157,9 @@ impl<TTask:Prioritized<Kind = Priority>> StealingQueue<TTask> {
 	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),
 		}
 	}
@@ -169,8 +190,11 @@ impl<TTask> Context<TTask> {
 	/// 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.
@@ -182,13 +206,15 @@ impl<TTask> Context<TTask> {
 
 		// If the global queue is empty, try stealing from peers.
 		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 mut Rng = rand::rng();
+
 		let Start = Rng.random_range(0..Count);
 
 		// Iterate through all peers starting from the random offset.

Source/Queue/mod.rs

@@ -1,6 +1,7 @@
 //! # Queue Module
 //!
 //! This module encapsulates all logic for the generic, priority-aware,
+
 //! work-stealing queue system, which is the foundational data structure of the
 //! `Echo` scheduler.
 

Source/Scheduler/Scheduler.rs

@@ -28,8 +28,10 @@ use crate::{
 pub struct Scheduler {
 	/// The underlying work-stealing queue system used for task submission.
 	Queue:StealingQueue<Task>,
+
 	/// Handles to the spawned worker threads, used for graceful shutdown.
 	WorkerHandles:Vec<JoinHandle<()>>,
+
 	/// An atomic flag to signal all workers to shut down.
 	IsRunning:Arc<AtomicBool>,
 }
@@ -52,10 +54,12 @@ impl Scheduler {
 		// Spawn an asynchronous task for each worker.
 		for Context in Contexts.into_iter() {
 			let IsRunning = IsRunning.clone();
+
 			let WorkerHandle = tokio::spawn(async move {
 				// Each task creates and runs a worker, consuming its context.
 				Worker::Create(Context, IsRunning).Run().await;
 			});
+
 			WorkerHandles.push(WorkerHandle);
 		}
 
@@ -79,15 +83,18 @@ impl Scheduler {
 	pub async fn Stop(&mut self) {
 		if !self.IsRunning.swap(false, Ordering::Relaxed) {
 			info!("[Scheduler] Stop already initiated.");
+
 			return;
 		}
 
 		info!("[Scheduler] Stopping worker threads...");
+
 		for Handle in self.WorkerHandles.drain(..) {
 			if let Err(Error) = Handle.await {
 				error!("[Scheduler] Error joining worker handle: {}", Error);
 			}
 		}
+
 		info!("[Scheduler] All workers stopped successfully.");
 	}
 }
@@ -101,6 +108,7 @@ impl Drop for Scheduler {
 	fn drop(&mut self) {
 		if self.IsRunning.load(Ordering::Relaxed) {
 			warn!("[Scheduler] Dropped without explicit stop. Signaling workers to terminate.");
+
 			self.IsRunning.store(false, Ordering::Relaxed);
 		}
 	}

Source/Scheduler/SchedulerBuilder.rs

@@ -15,6 +15,7 @@ use crate::Scheduler::Scheduler::Scheduler;
 pub enum Concurrency {
 	/// Specifies a maximum number of concurrent tasks for a queue.
 	Limit(usize),
+
 	/// Allows an unlimited number of concurrent tasks for a queue.
 	Unlimited,
 }
@@ -27,6 +28,7 @@ pub enum Concurrency {
 pub struct SchedulerBuilder {
 	/// The number of worker threads to be spawned in the scheduler's pool.
 	Count:usize,
+
 	/// Configuration for named queues with concurrency limits (for future
 	/// use).
 	Configuration:HashMap<String, Concurrency>,
@@ -40,6 +42,7 @@ impl SchedulerBuilder {
 	/// viable.
 	pub fn Create() -> Self {
 		let Default = num_cpus::get().max(2);
+
 		Self { Count:Default, Configuration:HashMap::new() }
 	}
 
@@ -49,17 +52,20 @@ impl SchedulerBuilder {
 	pub fn WithWorkerCount(mut self, Count:usize) -> Self {
 		if Count == 0 {
 			warn!("[SchedulerBuilder] Worker count of 0 is invalid. Defaulting to logical CPUs.");
+
 			self.Count = num_cpus::get().max(2);
 		} else {
 			self.Count = Count;
 		}
+
 		self
 	}
 
 	/// Configures a named queue with a specific concurrency limit (for future
 	/// use).
 	pub fn WithQueue(mut self, Name:&str, Limit:Concurrency) -> Self {
 		self.Configuration.insert(Name.to_string(), Limit);
+
 		self
 	}
 

Source/Scheduler/Worker.rs

@@ -19,6 +19,7 @@ pub struct Worker {
 	/// The worker's execution context, which contains its private deques and a
 	/// reference to the shared queue system.
 	Context:Context<Task>,
+
 	/// An atomic flag, shared by all workers, to signal a shutdown request.
 	IsRunning:Arc<AtomicBool>,
 }
@@ -46,7 +47,9 @@ impl Worker {
 					"[Worker {}] Executing local task with priority: {:?}.",
 					self.Context.Identifier, Task.Priority
 				);
+
 				Task.Operation.await;
+
 				continue;
 			}
 
@@ -58,6 +61,7 @@ impl Worker {
 					"[Worker {}] Executing stolen task with priority: {:?}.",
 					self.Context.Identifier, Task.Priority
 				);
+
 				Task.Operation.await;
 			} else {
 				// If there's truly no work anywhere, yield to the OS.

Source/Scheduler/mod.rs

@@ -9,6 +9,7 @@
 
 // --- Public API ---
 pub mod Scheduler;
+
 pub mod SchedulerBuilder;
 
 // --- Internal Implementation ---

Source/Task/Priority.rs

@@ -8,6 +8,7 @@
 /// Represents the priority of a task to be executed by the scheduler.
 ///
 /// This enumeration allows the scheduler to ensure that high-priority,
+
 /// user-facing operations (e.g., responding to UI input) are executed before
 /// lower-priority, long-running background tasks (e.g., file indexing).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]

Source/Task/Task.rs

@@ -18,6 +18,7 @@ pub type Operation = Pin<Box<dyn Future<Output = ()> + Send>>;
 /// Represents a single, schedulable unit of work for the `Echo` scheduler.
 ///
 /// This struct encapsulates an asynchronous operation along with metadata,
+
 /// such as its `Priority`, that the scheduler uses to determine execution
 /// order.
 pub struct Task {
@@ -51,7 +52,9 @@ impl Prioritized for Task {
 	fn Rank(&self) -> Self::Kind {
 		match self.Priority {
 			Priority::High => QueuePriority::High,
+
 			Priority::Normal => QueuePriority::Normal,
+
 			Priority::Low => QueuePriority::Low,
 		}
 	}