CALM is a high-performance execution engine built on a single-thread message pump (CalmPump) using `System.Threading.Channels`. It structurally eliminates Race Conditions and Deadlocks in multi-threaded programming.
Standard async/await in C# is powerful, but it doesn't automatically prevent
deadlocks or race conditions. These bugs are notoriously hard to reproduce and debug.
CALM was born from the struggle of managing shared state in complex async applications.
Previously, we tried solving this using a single-threaded coroutine approach with
yield return. While it ensured thread safety, it lacked support for
efficient IO-bound interleaving and standard try/catch blocks across yield
points.
CALM solves these challenges by running standard async methods on a dedicated
single-threaded message pump. This approach provides:
- Lock-free Safety: Serialized execution eliminates race conditions.
- Resource Efficiency: No thread pool churn or semaphore management.
- Simplicity: Focus on business logic using standard async C# code.
- CalmPump (Message Pump): Channel-based single-thread execution engine.
- Role-based Messaging: Clear separation of roles for Commands, Queries, and Events.
- Atomic Outbox (Unit of Work): Atomic event publishing upon successful command execution.
- Resource Efficiency: Minimizes thread pool consumption and prevents starvation.
- Watchdog (Stall Detection): Automatic detection of tasks monopolizing the thread.
- OpenTelemetry Integration: Native support for performance and health monitoring.
| Learning Objective | Documentation |
|---|---|
| Get up and running quickly | Quickstart Guide |
| Learn engine basics | Operations & Thread Control |
| Implement messaging | Role-based Messaging |
| Leverage Dependency Injection | DI Integration Guide |
| Integrate with GUI | GUI Application Integration |
| Customize configuration | Configuration Properties |
| Learn error handling | Diagnostics & Exceptions |
| Deep dive into architecture | Architecture & Concepts |