A Resilient, High-Performance Task Scheduler for Rust

Echo is a bounded work-stealing task scheduler designed as the core execution engine for application backends like Mountain. It provides structured concurrency with priority-based task scheduling, ensuring that latency-sensitive operations always take precedence over background work. The scheduler distributes tasks across a Tokio thread pool using lock-free work-stealing queues, maximizing CPU utilization without the memory and IPC overhead of process-based parallelism.

The system separates generic queueing logic from application-specific scheduling concerns through a clean abstraction layer. Workers consume tasks from local FIFO deques and attempt to steal from peer workers or the global injector queue when local work is exhausted. This architecture delivers low-latency execution for foreground operations while efficiently processing batch work in the background.

Rust API Documentation 📖

Welcome to Echo! This crate provides a structured concurrency runtime for Rust applications, built on a high-performance work-stealing 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 to provide a robust framework for managing, prioritizing, and executing complex asynchronous workflows with resilience and efficiency.

Echo provides a bounded work-stealing task scheduler that acts as the core execution engine for Rust application backends. It solves the problem of unstructured concurrency by offering structured, priority-based task scheduling with graceful shutdown, ensuring that latency-sensitive operations always take precedence over background work while maximizing CPU utilization across a pool of worker threads. The crate moves beyond simple tokio::spawn to provide a robust framework for managing, prioritizing, and executing complex asynchronous workflows with resilience and efficiency.

• Work-Stealing Scheduler: Implements a priority-aware work-stealing algorithm using crossbeam-deque to efficiently distribute tasks across a pool of worker threads. Idle workers automatically steal from busy workers, eliminating scheduling bottlenecks and keeping all cores productive.
• Task Prioritization: Supports submitting tasks with High, Normal, or Low priority levels. High-priority tasks are executed first from local and global deques, ensuring that latency-sensitive operations respond immediately while background work yields gracefully.
• Fluent Builder API: The SchedulerBuilder provides a clean, chainable configuration interface for the worker pool. It defaults to the number of logical CPU cores with a minimum of two workers, and supports explicit worker count overrides as well as named queue configuration for future extensibility.
• Graceful Shutdown: The Stop() method signals all worker threads to terminate and waits for each to complete its current task before joining. An automatic Drop guard ensures workers are signaled to stop even if the scheduler is dropped without an explicit shutdown call.
• Decoupled Architecture: The generic Queue module provides the core work-stealing logic as a standalone library, independent of any specific scheduler implementation. The StealingQueue<TTask> accepts any type implementing the Prioritized trait, making it reusable across projects.

graph LR
    classDef common   fill:#d4f5d4,stroke:#27ae60,stroke-width:1px,stroke-dasharray:5 5,color:#0a3a0a;
    classDef mountain fill:#f0d0ff,stroke:#9b59b6,stroke-width:2px,color:#2c0050;
    classDef echo     fill:#fffde0,stroke:#f0b429,stroke-width:2px,color:#4a3500;
    classDef worker   fill:#ffe0f0,stroke:#c0396a,stroke-width:1px,color:#4a0020;

    subgraph COMMON["Common - Abstract Core"]
        ActionEffect["ActionEffect\n(operation as value)"]:::common
        Prioritized["Prioritized trait\n(High / Normal / Low)"]:::common
    end

    subgraph MOUNTAIN["Mountain ⛰️ - Application Logic"]
        Track["Track/ - Request Dispatcher"]:::mountain
        AppRunTime["ApplicationRunTime\n(RunTime/ApplicationRunTime/)"]:::mountain
        MountainEnv["Environment/ Providers\n(concrete service impls)"]:::mountain
        Track --> AppRunTime
    end

    subgraph ECHO["Echo 📣 - Work-Stealing Scheduler"]
        direction TB
        subgraph SCHEDULER["Scheduler/"]
            SchedBuilder["SchedulerBuilder.rs\n(fluent config, defaults to num_cpus)"]:::echo
            SchedCore["Scheduler.rs\n(Submit API + graceful Stop)"]:::echo
            Workers["Worker.rs\n(Tokio threads, steal-on-idle)"]:::worker
            SchedBuilder --> SchedCore
            SchedCore --> Workers
        end
        subgraph QUEUE["Queue/"]
            StealQ["StealingQueue.rs\n(crossbeam-deque, lock-free)"]:::echo
        end
        subgraph TASK["Task/"]
            TaskDef["Task.rs + Priority.rs\n(Future wrapper + priority level)"]:::echo
        end

        Workers -- steals from --> StealQ
        SchedCore -- enqueues --> StealQ
        TaskDef -.implements.-> Prioritized
    end

    AppRunTime -- creates Future from --> ActionEffect
    AppRunTime -- Submit Future --> SchedCore
    Workers -- executes using --> MountainEnv

This diagram illustrates Echo's role as the core execution engine within the Mountain backend.

Echo serves as the core execution engine for Mountain, the native Rust/Tauri backend of the Land Code Editor. It integrates seamlessly with the ActionEffect pattern from the Common crate, executing composed asynchronous workflows across a priority-aware worker pool. The Mountain runtime submits futures derived from ActionEffect values to the Echo scheduler, which distributes them across its workers alongside the concrete Environment provider implementations.

To add Echo to your project, add the following to your Cargo.toml:

[dependencies]
Echo = { git = "https://github.com/CodeEditorLand/Echo.git", branch = "Current" }

The crate depends on tokio, crossbeam-deque, rand, log, num_cpus, and Common from the Land workspace. All dependencies are resolved through the workspace Cargo.toml configuration.

First, create and start the scheduler when your application initializes. The builder defaults to the number of logical CPU cores, with a minimum of two workers to ensure work-stealing is viable:

use std::sync::Arc;
use Echo::Scheduler::SchedulerBuilder;
use Echo::Task::Priority;

let Scheduler = Arc::new(SchedulerBuilder::Create().WithWorkerCount(8).Build());

Submit asynchronous tasks from anywhere in your application using the scheduler instance. Tasks are queued by priority and executed by the next available worker:

let MyTask = async {
    println!("This is running on an Echo worker thread!");
    // ... perform some work ...
};

// Submit the task with a desired priority
Scheduler.Submit(MyTask, Priority::Normal);

// Another example with high priority
Scheduler.Submit(async { /* critical work */ }, Priority::High);

Before your application exits, ensure a clean shutdown of all worker threads. The Stop() method drains the queue and waits for in-flight tasks to complete:

// 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;
}

• Rust API Documentation 📖

• Architecture Overview — Internal module structure
• Deep Dive — In-depth technical details
• Land Documentation — Complete documentation index
• Mountain — Primary consumer of Echo
• Common — Abstract traits and ActionEffect system
• Why Rust
• Contribution Guide
• TODO List — Performance optimization challenges
• CHANGELOG.md — History of changes specific to Echo

Echo is built on a high-performance foundation, but there is always room to push the boundaries of speed and efficiency. We maintain a detailed roadmap of features and performance optimizations, with tasks suitable for all skill levels.

Interested in tackling one of these challenges?

• Check out our full TODO for challenges!
• Follow our Contribution Guide to get started!

This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program, under grant agreement No 101135429.

Echo is a core element of the Land ecosystem. This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

The project is operated by PlayForm, based in Sofia, Bulgaria. PlayForm acts as the open-source steward for Code Editor Land under the NGI0 Commons Fund grant.