You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(Echo): Expand README with comprehensive getting started guide
Expand the Echo README from a concise (~150 line) overview to a full developer onboarding guide with installation instructions, usage examples, and contribution pathways.
Key additions include:
- New "Getting Started" section with Cargo.toml installation snippet and three-step usage walkthrough (initialize scheduler, submit tasks, graceful shutdown)
- Detailed "Key Features" list covering work-stealing, task prioritization, builder API, and graceful shutdown
- "Core Architecture Principles" table mapping Performance, Structured Concurrency, Decoupling, Resilience, and Composability to their key components
- "Echo in the Land Ecosystem" section with Mermaid diagram showing integration with Mountain and ActionEffect pattern
- Contribution call-to-action with four-tier task matrix (Quick Wins, Architectural, Expert Tuning, Advanced Logic)
- Expanded license and changelog reference sections
This addresses the developer friction identified in recent README iterations by providing the concrete setup and usage code that was trimmed in the initial benefit-focused rewrite.
> **VS Code's background tasks (file indexing, symbol scanning, git blame) run in a single-threaded Node.js process. Heavy indexing freezes everything on that thread. The only escape is spawning more processes, adding memory and IPC overhead.**
44
+
A Resilient, High-Performance Task Scheduler for Rust
45
+
46
+
> **VS Code's background tasks (file indexing, symbol scanning, git blame) run
47
+
> in a single-threaded Node.js process. Heavy indexing freezes everything on
48
+
> that thread. The only escape is spawning more processes, adding memory and IPC
49
+
> overhead.**
46
50
47
-
_"Indexing, search, and builds run on every CPU core in parallel. The editor stays responsive."_
51
+
_"Indexing, search, and builds run on every CPU core in parallel. The editor
Echo is a lock-free work-stealing scheduler built on Rust's `crossbeam-deque`. Every task runs in a supervised worker pool spanning all CPU cores. Tasks are work-stolen (idle threads pick up tasks from busy threads' queues), supervised (every task has a parent scope with controlled crash propagation), and gracefully shut down (no task can outlive its scope).
55
-
56
60
📖 **[Rust API Documentation](https://Rust.Documentation.Editor.Land/Echo/)**
57
61
62
+
Welcome to **Echo**! This crate provides a powerful, structured concurrency
63
+
runtime for Rust applications, built on a high-performance **work-stealing
64
+
scheduler**. It is designed to be the core execution engine for application
65
+
backends like `Mountain`, integrating seamlessly with declarative systems like
66
+
the `ActionEffect` pattern. **Echo** moves beyond simple task spawning
67
+
(`tokio::spawn`) to provide a robust framework for managing, prioritizing, and
68
+
executing complex asynchronous workflows with resilience and efficiency.
69
+
70
+
**Echo** is engineered to:
71
+
72
+
1.**Provide High-Performance Concurrency:** Utilizes a lock-free,
73
+
work-stealing queue (`crossbeam-deque`) to ensure all worker threads remain
74
+
busy, maximizing CPU utilization and application throughput.
75
+
2.**Enable Structured Task Management:** Offers a clean API for submitting
76
+
tasks with different priorities, allowing critical, UI-blocking operations
77
+
to pre-empt background work.
78
+
3.**Integrate Natively with Effect Systems:** Designed from the ground up to
79
+
be the execution backend for systems like the `ActionEffect` pattern,
80
+
providing a bridge between declarative task definitions and their concrete
81
+
execution.
82
+
83
+
---
84
+
85
+
## Key Features 🔐
86
+
87
+
-**Work-Stealing Scheduler:** Implements a modern, priority-aware work-stealing
88
+
algorithm to efficiently distribute tasks across a pool of worker threads.
89
+
-**Task Prioritization:** Supports submitting tasks with `High`, `Normal`, or
90
+
`Low` priority, ensuring that latency-sensitive operations are handled
91
+
immediately.
92
+
-**Fluent Builder API:** A clean `SchedulerBuilder` allows for easy
93
+
configuration of the worker pool size.
94
+
-**Graceful Shutdown:** Provides a `Stop()` method to ensure all worker threads
95
+
complete their current tasks and exit cleanly, preventing orphaned threads.
96
+
-**Decoupled Architecture:** A generic `Queue` module provides the core
97
+
work-stealing logic, which is consumed by the application-specific
|**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`|
107
+
|**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`|
108
+
|**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`|
109
+
|**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`|
110
+
|**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`|
111
+
58
112
---
59
113
60
-
## What It Does 🔐
114
+
## Deep Dive & Component Breakdown 🔬
61
115
62
-
-**Work-stealing across all cores.** Idle threads pick up tasks from busy threads' queues automatically.
63
-
-**Supervised task scopes.** Every task has a parent scope. Crash propagation is controlled.
64
-
-**Guaranteed teardown.** No task can outlive its scope. Shutdown is deterministic.
65
-
-**UI never blocks.** Heavy indexing, symbol analysis, and test runners all go to Echo's thread pool.
116
+
To understand how `Echo`'s internal components interact to provide these
117
+
services, please refer to the detailed technical breakdown in
0 commit comments