SingleFlightCoordinator<TKey> Class

Definition

Namespace: Bodu.Financial.ExchangeRates

Assembly: Bodu.Financial.ExchangeRates.dll

Package: Bodu.Financial.ExchangeRates 1.0.0

Source: SingleFlightCoordinator{T}.cs

Coordinates concurrent asynchronous operations keyed by TKey so that at most one operation per key runs at a time, with every concurrent caller for that key awaiting the same shared task.

public sealed class SingleFlightCoordinator<TKey> where TKey : notnull

Type Parameters

TKey: The type that identifies an operation; equal keys share one in-flight result.

Inheritance: object

SingleFlightCoordinator<TKey>

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

This is the classic single-flight (request-coalescing) pattern: when several callers request the same key while a fetch is already running, they join the running task instead of starting duplicate work. The in-flight entry is removed as soon as the operation completes - including when it faults - so a failure never poisons the key and the next caller starts a fresh attempt. Callers that join an in-flight operation observe its outcome, including its exception.

Cancellation. The cancellation-aware overloads decouple the shared operation's lifetime from any single caller's token. Once started, the operation runs to completion and fulfills the shared promise even if every caller abandons its wait; the operation itself is invoked with None because its result populates shared state for the next caller. A caller's cancellationToken governs only that caller's wait: when it is signalled the caller observes OperationCanceledException for itself and stops waiting, without cancelling the shared operation or affecting any other caller. This makes the coalesced work safe for idempotent cache-warming fetches, where one caller's cancellation must never fault the other joiners. A reference-counted variant that cancels the shared operation only once all participants have cancelled is a deliberate non-goal here. The token-less overloads carry no caller token into the operation and never cancel a caller's wait.

A given key must always be used with the same result type. Instances are safe for concurrent use.

Constructors

SingleFlightCoordinator()

public SingleFlightCoordinator()

Methods

RunAsync(TKey, Func<CancellationToken, Task>, CancellationToken)

Runs operation for key, or joins the operation already in flight for that key, then awaits its completion, abandoning this caller's wait when cancellationToken is signalled.

public Task RunAsync(TKey key, Func<CancellationToken, Task> operation, CancellationToken cancellationToken)

Parameters

key TKey: The key that identifies the operation.
operation Func<CancellationToken, Task>: The asynchronous operation to run when none is in flight for key, invoked with a token decoupled from any caller.
cancellationToken CancellationToken: A token that abandons this caller's wait on the shared result.

Returns

Task: A task that completes when the operation for key completes.

Exceptions

ArgumentNullException: Thrown when operation is null.
OperationCanceledException: Thrown when cancellationToken is signalled before the shared operation completes; the shared operation continues regardless.

RunAsync(TKey, Func<Task>)

Runs operation for key, or joins the operation already in flight for that key, then awaits its completion.

public Task RunAsync(TKey key, Func<Task> operation)

Parameters

key TKey: The key that identifies the operation.
operation Func<Task>: The asynchronous operation to run when none is in flight for key.

Returns

Task: A task that completes when the operation for key completes.

Exceptions

ArgumentNullException: Thrown when operation is null.

RunAsync<TResult>(TKey, Func<CancellationToken, Task<TResult>>, CancellationToken)

Runs operation for key, or joins the operation already in flight for that key, then awaits and returns its result, abandoning this caller's wait when cancellationToken is signalled.

public Task<TResult> RunAsync<TResult>(TKey key, Func<CancellationToken, Task<TResult>> operation, CancellationToken cancellationToken)

Parameters

key TKey: The key that identifies the operation.
operation Func<CancellationToken, Task<TResult>>: The asynchronous operation to run when none is in flight for key, invoked with a token decoupled from any caller.
cancellationToken CancellationToken: A token that abandons this caller's wait on the shared result.

Returns

Task<TResult>: A task that yields the result of the operation for key.

Type Parameters

TResult: The result produced by the operation.

Exceptions

ArgumentNullException: Thrown when operation is null.
OperationCanceledException: Thrown when cancellationToken is signalled before the shared operation completes; the shared operation continues regardless.

RunAsync<TResult>(TKey, Func<Task<TResult>>)

Runs operation for key, or joins the operation already in flight for that key, then awaits and returns its result.

public Task<TResult> RunAsync<TResult>(TKey key, Func<Task<TResult>> operation)

Parameters

key TKey: The key that identifies the operation.
operation Func<Task<TResult>>: The asynchronous operation to run when none is in flight for key.

Returns

Task<TResult>: A task that yields the result of the operation for key.

Type Parameters

TResult: The result produced by the operation.

Exceptions

ArgumentNullException: Thrown when operation is null.

Applies to

Product	Versions
.NET	8, 10