Calm.Core 1.0.0

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./documents/images/calm-logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="./documents/images/calm-logo-light.svg"> <img alt="CALM Logo" src="./documents/images/calm-logo-light.svg" width="450"> </picture> </div>

CALM

CALM (Cooperative Async Lock-free Messaging) is a high-performance, lightweight execution engine for .NET designed to simplify concurrent programming.

By ensuring single-threaded execution within a dedicated context, CALM structurally eliminates common concurrency pitfalls such as race conditions, deadlocks, and this reference leaks. It provides a "Calm" development experience where you can focus on business logic using standard Task-based code without worrying about thread safety.

🚀 Key Features

• Guaranteed Single-Threading: All operations within an engine instance are serialized, providing an actor-like thread-safety model.
• Resource Efficiency: Minimizes thread pool consumption by processing all tasks on a single dedicated thread, preventing thread pool starvation even under high task volumes.
• Structural Safety: Designed to prevent this reference leaks during registration by enforcing a "Construction-First, Connection-Second" protocol.
• Deadlock Elimination: By serializing all tasks through a high-performance Channel-based message pump, it removes the need for traditional locks.
• Role-based Messaging: Built-in support for Commands, Queries, and Events with a simple, attribute-based handler discovery.
• DI Ready: Seamlessly integrates with Microsoft.Extensions.DependencyInjection and supports automatic handler registration from assemblies.
• Multi-Target Support: Compatible with .NET Framework 4.7.2, .NET Standard 2.0/2.1, and .NET 8/10.

📦 Packages

<table> <tr> <th>Package</th> <th>Nuget</th> </tr> <tr> <td> <strong>Calm.Core</strong><br /> <div style="font-size: 0.8em; opacity: 0.7;"> The core high-performance execution engine and messaging abstractions. </div> </td> <td> <a href="https://www.nuget.org/packages/Calm.Core"> <img src="https://img.shields.io/nuget/v/Calm.Core" alt="Nuget" /> </a> </td> </tr> <tr> <td> <strong>Calm.Extensions.DependencyInjection</strong><br /> <div style="font-size: 0.8em; opacity: 0.7;"> Seamless integration with <code>Microsoft.Extensions.DependencyInjection</code>. </div> </td> <td> <a href="https://www.nuget.org/packages/Calm.Extensions.DependencyInjection"> <img src="https://img.shields.io/nuget/v/Calm.Extensions.DependencyInjection" alt="Nuget" /> </a> </td> </tr> </table>

📦 Installation

Install the core package via NuGet:

dotnet add package Calm.Core

If you are using Dependency Injection (recommended), install the extensions:

dotnet add package Calm.Extensions.DependencyInjection

⚡ Quick Start

1. Define your Messages

Implement ICalmCommand, ICalmQuery<T>, or ICalmEvent.

public record GreetCommand(string Name) : ICalmCommand;
public record GetVersionQuery() : ICalmQuery<string>;

2. Implement Handlers

Decorate your methods with the [CalmHandler] attribute.

public class GreetingService
{
    [CalmHandler]
    public Task HandleAsync(GreetCommand command, CancellationToken ct)
    {
        Console.WriteLine($"Hello, {command.Name}!");
        return Task.CompletedTask;
    }

    [CalmHandler]
    public Task<string> HandleAsync(GetVersionQuery query, CancellationToken ct)
    {
        return Task.FromResult("1.0.0");
    }
}

3. Setup and Execution (with DI)

var services = new ServiceCollection();

// Add CALM and register handlers from the assembly
services.AddCalm();
services.AddCalmHandlersFromAssembly(ServiceLifetime.Singleton, typeof(GreetingService).Assembly);

var provider = services.BuildServiceProvider();

// Start the engine
var calm = provider.GetRequiredService<ICalm>();
calm.Start();

// Send a command
await calm.Command.SendAsync(new GreetCommand("World"));

// Send a query
var version = await calm.Query.SendAsync(new GetVersionQuery());

⚠️ Important Safety Rules

To maintain the safety guarantees provided by CALM, please adhere to these rules:

1. Avoid .ConfigureAwait(false): Within CALM handlers or tasks, always stay on the engine thread. Using false can leak the execution to the thread pool, leading to race conditions.
2. Do NOT Register in Constructors: Never call Register(this) in a constructor. This leads to a "this-reference leak" where an uninitialized object is exposed to the engine. Use a Load event or an explicit initialization method instead.
3. Always Unregister: To prevent memory leaks, ensure that instances registered with the engine are Unregister()ed or disposed of when no longer needed.

🎓 Learning Path with Samples

To help you get started with CALM, we have prepared a series of samples that guide you through its features step-by-step. You can find them in the samples directory.

See the Samples README for a detailed breakdown of each sample.

📚 Documentation

For detailed guides, advanced configurations, and architectural deep-dives, please refer to our Documentation Site.

• Quickstart Guide
• Engine Operations & Thread Control
• Role-based Messaging
• GUI Application Integration

📄 License

• Documentation (/documents): Licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
• All other contents: Licensed under the Apache License 2.0.