Mostlylucid.Ephemeral.Atoms.Retry
3.0.0
dotnet add package Mostlylucid.Ephemeral.Atoms.Retry --version 3.0.0
NuGet\Install-Package Mostlylucid.Ephemeral.Atoms.Retry -Version 3.0.0
<PackageReference Include="Mostlylucid.Ephemeral.Atoms.Retry" Version="3.0.0" />
<PackageVersion Include="Mostlylucid.Ephemeral.Atoms.Retry" Version="3.0.0" />
<PackageReference Include="Mostlylucid.Ephemeral.Atoms.Retry" />
paket add Mostlylucid.Ephemeral.Atoms.Retry --version 3.0.0
#r "nuget: Mostlylucid.Ephemeral.Atoms.Retry, 3.0.0"
#:package Mostlylucid.Ephemeral.Atoms.Retry@3.0.0
#addin nuget:?package=Mostlylucid.Ephemeral.Atoms.Retry&version=3.0.0
#tool nuget:?package=Mostlylucid.Ephemeral.Atoms.Retry&version=3.0.0
Mostlylucid.Ephemeral.Atoms.Retry
Signal-driven retry with backoff for transient failures. Every attempt failure, exhaustion, and
eventual success is raised onto the shared signal sink — so a SignalBasedCircuitBreaker (or
anything else watching the sink) can observe real failure history, instead of retries being
invisible inside this atom.
dotnet add package mostlylucid.ephemeral.atoms.retry
Quick Start
using Mostlylucid.Ephemeral.Atoms.Retry;
await using var atom = new RetryAtom<ApiRequest>(
async (req, ct) => await CallExternalApi(req, ct),
backoff: BackoffStrategies.Exponential(TimeSpan.FromMilliseconds(100)),
maxTotalDuration: TimeSpan.FromSeconds(30),
maxAttempts: 3);
// Automatically retries on failure
await atom.EnqueueAsync(new ApiRequest("https://api.example.com"));
await atom.DrainAsync();
All Options
new RetryAtom<T>(
// Required: async work body
body: async (item, ct) => await ProcessAsync(item, ct),
// Required, no default: delay-per-attempt. Use a named strategy below, or your own
// Func<int, TimeSpan>. There is deliberately no baked-in default here — a retry
// schedule is a caller decision, not a library constant.
backoff: BackoffStrategies.Exponential(TimeSpan.FromMilliseconds(100)),
// Required, no default: bounds the ENTIRE retry loop for one item — all attempts and
// backoff waits combined. The underlying coordinator owns the concurrency slot and must
// not let one item hold it forever.
maxTotalDuration: TimeSpan.FromSeconds(30),
// Max attempts including the first
// Default: 3
maxAttempts: 3,
// Max concurrent operations
// Default: Environment.ProcessorCount
maxConcurrency: 4,
// Shared signal sink — required for signals to be observable at all, and required if
// you also supply a breaker
// Default: null
signals: sharedSink,
// Optional circuit breaker gating intake (see below)
// Default: null
breaker: null,
// Optional clock for backoff waits, for testability
// Default: TimeProvider.System
timeProvider: null
)
API Reference
// Enqueue with automatic retry. Throws CircuitOpenException if a breaker is supplied and open.
ValueTask<long> id = await atom.EnqueueAsync(item, ct);
// Drain
await atom.DrainAsync(ct);
await atom.DisposeAsync();
Signals
When signals is supplied, this atom raises:
| Signal | When |
|---|---|
RetryAtom<T>.AttemptFailedSignal |
An attempt fails and another will be tried |
RetryAtom<T>.ExhaustedSignal |
The final attempt fails and no more remain |
RetryAtom<T>.SucceededAfterRetrySignal |
An item succeeds after at least one prior failure |
Backoff Strategies
Use BackoffStrategies for named, reusable strategies instead of writing a lambda every time.
using Mostlylucid.Ephemeral.Atoms.Retry;
BackoffStrategies.Constant(TimeSpan.FromMilliseconds(500)); // Always 500ms
BackoffStrategies.Linear(TimeSpan.FromMilliseconds(50)); // 50ms, 100ms, 150ms, ...
BackoffStrategies.Exponential(TimeSpan.FromMilliseconds(100)); // 100ms, 200ms, 400ms, ...
BackoffStrategies.Exponential(TimeSpan.FromMilliseconds(100), factor: 3.0); // 100ms, 300ms, 900ms, ...
BackoffStrategies.ExponentialWithJitter(TimeSpan.FromMilliseconds(100)); // exponential +/- 20% jitter
Or supply your own Func<int, TimeSpan> directly — attempt number is 1-based.
Example: Circuit Breaker
RetryAtom composes directly with SignalBasedCircuitBreaker. The breaker reads the atom's own
ExhaustedSignal from the shared sink — no separate wiring needed.
using Mostlylucid.Ephemeral.Atoms.Retry;
using Mostlylucid.Ephemeral.Patterns.CircuitBreaker;
var sink = new SignalSink();
var breaker = new SignalBasedCircuitBreaker(
failureSignal: RetryAtom<ApiRequest>.ExhaustedSignal,
threshold: 5,
windowSize: TimeSpan.FromSeconds(30));
await using var atom = new RetryAtom<ApiRequest>(
async (req, ct) => await CallExternalApi(req, ct),
backoff: BackoffStrategies.Exponential(TimeSpan.FromMilliseconds(100)),
maxTotalDuration: TimeSpan.FromSeconds(30),
signals: sink,
breaker: breaker);
try
{
await atom.EnqueueAsync(request);
}
catch (CircuitOpenException ex)
{
// Too many items have exhausted their retries recently; back off upstream instead
// of piling more attempts onto a downstream that's already failing.
log.Warn($"Circuit open, retry after {ex.RetryAfter}");
}
Example: HTTP Calls
await using var atom = new RetryAtom<HttpRequest>(
async (req, ct) =>
{
var response = await httpClient.SendAsync(req.Message, ct);
response.EnsureSuccessStatusCode();
},
backoff: BackoffStrategies.Exponential(TimeSpan.FromSeconds(1)),
maxTotalDuration: TimeSpan.FromSeconds(30),
maxAttempts: 3,
maxConcurrency: 8);
foreach (var request in requests)
await atom.EnqueueAsync(request);
await atom.DrainAsync();
Related Packages
| Package | Description |
|---|---|
| mostlylucid.ephemeral | Core library |
| mostlylucid.ephemeral.patterns.circuitbreaker | Circuit breaker |
| mostlylucid.ephemeral.complete | All in one DLL |
License
Unlicense (public domain)
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.9)
- mostlylucid.ephemeral (>= 3.0.0)
- Mostlylucid.Ephemeral.Patterns.CircuitBreaker (>= 3.0.0)
- System.IO.Hashing (>= 10.0.9)
-
net8.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.9)
- mostlylucid.ephemeral (>= 3.0.0)
- Mostlylucid.Ephemeral.Patterns.CircuitBreaker (>= 3.0.0)
- System.IO.Hashing (>= 10.0.9)
-
net9.0
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 10.0.9)
- mostlylucid.ephemeral (>= 3.0.0)
- Mostlylucid.Ephemeral.Patterns.CircuitBreaker (>= 3.0.0)
- System.IO.Hashing (>= 10.0.9)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on Mostlylucid.Ephemeral.Atoms.Retry:
| Package | Downloads |
|---|---|
|
mostlylucid.ephemeral.complete
Meta-package that references all Mostlylucid.Ephemeral packages - bounded async execution with signals, atoms, and patterns. Install this single package to get everything. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 3.0.0 | 385 | 8/21/2026 |
| 2.10.0 | 161 | 7/23/2026 |
| 2.9.1 | 160 | 7/9/2026 |
| 2.9.0 | 151 | 7/8/2026 |
| 2.8.1 | 135 | 7/6/2026 |
| 2.7.0 | 121 | 7/4/2026 |
| 2.6.4 | 137 | 6/21/2026 |
| 2.6.3 | 125 | 5/22/2026 |
| 2.6.2 | 133 | 5/22/2026 |
| 2.6.0 | 120 | 5/22/2026 |
| 2.5.1 | 128 | 5/22/2026 |
| 2.5.0 | 125 | 5/3/2026 |
| 2.4.0 | 132 | 4/17/2026 |
| 2.3.2 | 155 | 1/9/2026 |
| 2.3.1 | 154 | 1/9/2026 |
| 2.3.1-alpha0 | 162 | 1/9/2026 |
| 2.3.0 | 1,393 | 1/8/2026 |
| 2.3.0-alpha1 | 150 | 1/8/2026 |
| 2.1.0 | 152 | 1/8/2026 |
| 2.1.0-preview | 142 | 1/8/2026 |