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
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Mostlylucid.Ephemeral.Atoms.Retry" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Mostlylucid.Ephemeral.Atoms.Retry" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Mostlylucid.Ephemeral.Atoms.Retry" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Mostlylucid.Ephemeral.Atoms.Retry --version 3.0.0
                    
#r "nuget: Mostlylucid.Ephemeral.Atoms.Retry, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Mostlylucid.Ephemeral.Atoms.Retry@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Mostlylucid.Ephemeral.Atoms.Retry&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Mostlylucid.Ephemeral.Atoms.Retry&version=3.0.0
                    
Install as a Cake Tool

Mostlylucid.Ephemeral.Atoms.Retry

NuGet

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();

Package Description
mostlylucid.ephemeral Core library
mostlylucid.ephemeral.patterns.circuitbreaker Circuit breaker
mostlylucid.ephemeral.complete All in one DLL

License

Unlicense (public domain)

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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
Loading failed