Merge pull request #6 from digixoil/develop

Add work dispatching and related rate control support, in addition to mutual exclusion manager

Author: russlank

README.md

@@ -12,6 +12,7 @@ A lightweight, high-performance, thread-safe background work queue manager and d
 - 🔒 **Safe Background Execution**: No scoped service leaks across async boundaries
 - 🔄 **Context Capture & Rehydration**: Automatically captures and restores context (user claims, tenant ID, etc.)
 - ⚙️ **Flexible Handler Pipeline**: Multiple handlers can process the same work type with ordered execution
+- ⏱️ **Rate Control**: Built-in debounce and throttle scheduling for controlling work execution timing
 - 📊 **Observable**: Structured logging at all execution boundaries
 - 🎯 **Multi-Targeting**: Supports .NET 6.0 through .NET 10.0
 - 📚 **Fully Documented**: Comprehensive XML documentation for all public APIs
@@ -24,6 +25,7 @@ XpressWork provides safe, in-memory background work execution for .NET applicati
 - Request context (user identity, tenant, etc.) is captured and restored
 - Multiple handlers can process work items in deterministic order
 - Proper cancellation and exception handling
+- Rate-controlled scheduling with debounce and throttle patterns
 
 ## What XpressWork Is NOT
 
@@ -174,23 +176,130 @@ await submitter.Enqueue(new BackgroundActionWorkArguments(
     Name: "ProcessOrder"));
 ```
 
+## Rate-Controlled Scheduling
+
+XpressWork includes a scheduling layer for rate-controlling when work is submitted to the queue. This is useful for scenarios where you need to coalesce rapid events or limit execution frequency.
+
+### Enable Scheduling
+
+```csharp
+services.AddXpressWork<MyAppContext, MyAppScopeFactory>();
+services.AddXpressWorkScheduling<MyAppContext>();
+```
+
+### Debounce Pattern
+
+Execute work only after a period of inactivity. Useful for auto-save scenarios where you want to save only after the user stops typing.
+
+```csharp
+public class PreferencesService
+{
+    private readonly IBackgroundWorkScheduler<MyAppContext> _scheduler;
+
+    public PreferencesService(IBackgroundWorkScheduler<MyAppContext> scheduler)
+    {
+        _scheduler = scheduler;
+    }
+
+    public async Task SavePreferencesAsync(Guid userId, UserPreferences prefs)
+    {
+        // Only save after 500ms of inactivity
+        // Multiple rapid calls reset the timer
+        await _scheduler.Debounce(
+            interval: TimeSpan.FromMilliseconds(500),
+            key: userId,  // Unique key per user
+            workArgument: new SavePreferencesArgs { UserId = userId, Preferences = prefs });
+    }
+}
+```
+
+### Throttle Pattern
+
+Execute work at most once per interval. Useful for sensor data or metrics where you want regular updates regardless of input frequency.
+
+```csharp
+public class SensorService
+{
+    private readonly IBackgroundWorkScheduler<MyAppContext> _scheduler;
+
+    public async Task ProcessTemperatureAsync(Guid sensorId, double temperature)
+    {
+        // Process at most once per second, using the latest reading
+        await _scheduler.Throttle(
+            interval: TimeSpan.FromSeconds(1),
+            key: sensorId,
+            workArgument: new ProcessTemperatureArgs { SensorId = sensorId, Temperature = temperature });
+    }
+}
+```
+
+### Run-Once-Then Patterns
+
+Execute immediately on first call, then apply rate limiting for subsequent calls.
+
+```csharp
+// Execute first call immediately, then debounce subsequent calls
+await _scheduler.RunOnceThenDebounce(
+    interval: TimeSpan.FromMilliseconds(500),
+    key: userId,
+    workArgument: new SaveArgs { ... });
+
+// Execute first call immediately, then throttle subsequent calls
+await _scheduler.RunOnceThenThrottle(
+    interval: TimeSpan.FromSeconds(1),
+    key: sensorId,
+    workArgument: new ProcessArgs { ... });
+```
+
+### Cancellation and Flushing
+
+```csharp
+// Cancel pending scheduled work
+var (action, parameters) = _scheduler.Cancel<SavePreferencesArgs>(userId);
+
+// Flush all pending work immediately (also called on shutdown)
+await _scheduler.FlushAsync();
+
+// Discard all pending work without execution
+_scheduler.Clear();
+```
+
 ## Architecture Overview
 
 | Component | Lifetime | Responsibility |
 |-----------|----------|----------------|
 | `BackgroundWorkQueue<TContext>` | **Singleton** | Owns channel, scheduling, execution |
 | `IBackgroundWorkSubmitter<TContext>` | **Scoped** | Captures caller scope & enqueues |
+| `IBackgroundWorkScheduler<TContext>` | **Singleton** | Rate-controlled scheduling (debounce/throttle) |
 | `IBackgroundWorkScopeFactory<TContext>` | Singleton | Capture + rehydrate logic |
 | `IBackgroundWorkContextAccessor<TContext>` | Scoped | Holds rehydrated context |
 | `IWorkHandler<TArgs>` | Scoped | Executes work |
 
+### Conceptual Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Your Application                         │
+├──────────────────────────────────────────────────────────────┤
+│  IBackgroundWorkScheduler     │  IBackgroundWorkSubmitter    │
+│  (rate-controlled scheduling) │  (immediate submission)      │
+├──────────────────────────────────────────────────────────────┤
+│                  IBackgroundWorkQueue                        │
+│                  (execution pipeline)                        │
+├──────────────────────────────────────────────────────────────┤
+│  IWorkHandler<T>  │  IWorkHandler<T>  │  IWorkHandler<T>     │
+│  (ordered execution in isolated scopes)                      │
+└──────────────────────────────────────────────────────────────┘
+```
+
 ### Key Invariants
 
 1. **Background execution never uses the original request/caller scope**
 2. **No scoped services are captured and reused across async boundaries**
 3. **Each work item executes in a new `AsyncServiceScope`**
 4. **Context is rehydrated before resolving handlers**
 5. **Handler ordering is deterministic and stable**
+6. **Scheduler flushes all pending work on graceful shutdown**
 
 ## Configuration Options
 
@@ -233,20 +342,24 @@ Handlers with the same `Order` value are sorted deterministically by type name.
 - Resolve services inside handlers, not in work arguments
 - Use the scoped submitter from within a DI scope
 - Handle cancellation tokens properly in handlers
+- Use debounce for user input that triggers saves/updates
+- Use throttle for high-frequency events (sensors, metrics)
 
 ### 🚫 DON'T
 
 - Capture scoped services in work arguments
 - Store `IServiceProvider` or `HttpContext` in work arguments
 - Resolve the submitter from a singleton
 - Use XpressWork for work that requires persistence or distribution
+- Use very short debounce/throttle intervals (< 10ms)
 
 ## Thread Safety
 
 All operations are thread-safe:
 - Multiple producers can enqueue concurrently
 - Context does not bleed across work items
 - Queue processing is sequential by default
+- Scheduler operations are thread-safe with concurrent dictionary storage
 
 ## Examples