Schedules and manages background tasks for caching operations. This class provides a robust infrastructure for executing cache-related background work with support for concurrency control, retry policies, and overload detection.
Namespace: Metalama.Patterns.Caching.Implementation
Assembly: Metalama.Patterns.Caching.Backend.dll
Syntax
public sealed class BackgroundTaskScheduler : IAsyncDisposable, IDisposableRemarks
Execution Modes:
- Parallel mode (default): Tasks run concurrently up to the
maxConcurrencylimit. Additional tasks queue until a slot becomes available. - Sequential mode (
sequential=true): Tasks execute strictly one after another in enqueue order. Useful for operations that must not overlap.
Concurrency Control:
The scheduler uses an internal SemaphoreSlim to throttle execution. The default
maxConcurrency is 50, meaning up to 50 tasks can execute simultaneously in parallel mode.
Additional tasks wait in a queue until a semaphore slot becomes available.
Overload Detection:
When the number of queued tasks exceeds the overloadThreshold (default: 500) above the
maxConcurrency, the scheduler enters an overloaded state. The IsOverloaded
property reflects this state, and the IsOverloadedChanged event fires on state transitions.
Retry Policy: An optional IRetryPolicy can be provided to enable automatic retries for failed tasks. During retry delays, the semaphore is released to allow other tasks to proceed, then re-acquired before the next attempt.
Cancellation: The scheduler supports two cancellation mechanisms:
- Global cancellation via Cancel(): Cancels all pending and running tasks.
- Per-task cancellation: Each enqueued task can have its own CancellationToken that is combined with the global token.
Disposal: The Dispose() and DisposeAsync(CancellationToken) methods wait for all pending tasks to complete before releasing resources. Use the overload with a CancellationToken to abort waiting if needed.
Constructors
| Name | Description |
|---|---|
| BackgroundTaskScheduler(IServiceProvider?, IRetryPolicy?, bool, int, int) | Initializes a new instance of the BackgroundTaskScheduler class. |
| BackgroundTaskScheduler(IServiceProvider?, bool) | Initializes a new instance of the BackgroundTaskScheduler class. |
Properties
| Name | Description |
|---|---|
| BackgroundTaskExceptions | Gets the number of background task exceptions that occurred. |
| IsOverloaded | Gets a value indicating whether the scheduler is overloaded with pending tasks. |
Methods
| Name | Description |
|---|---|
| Cancel() | Cancels all pending background tasks. |
| Dispose() | |
| Dispose(CancellationToken) | Disposes the scheduler, waiting for all tasks to complete. |
| DisposeAsync(CancellationToken) | Disposes the scheduler asynchronously, waiting for all tasks to complete. |
| EnqueueBackgroundTask(Func<CancellationToken, Task>, CancellationToken) | Enqueues a background task. |
| EnqueueBackgroundTask(Func<CancellationToken, ValueTask>) | Enqueues a background task. |
| StopAcceptingBackgroundTasks() | Forbids the use of the EnqueueBackgroundTask(Func<CancellationToken, ValueTask>) method. This method is used for debugging purposes only. |
| WhenBackgroundTasksCompleted(CancellationToken) | Returns a Task that completes when all enqueued background tasks complete. |
Events
| Name | Description |
|---|---|
| BackgroundTaskEnqueued | Event raised when a background task is enqueued. |
| IsOverloadedChanged | Event raised when the IsOverloaded property changes. |