IVSoftware.Portable.EpochCompletionSource 1.0.0-beta

IVSoftware.Portable.EpochCompletionSource [GitHub]

A reusable abstraction for awaiting renewable "epochs" that complete deterministically by scope or probabilistically by quiescent time.

Offers a Hybrid Solution

IVSoftware.Portable.WatchdogTimer allows a class to restart settling intervals without task cancellation exceptions, extending activity until a dwell interval completes.

IVSoftware.Portable.Disposable.DisposableHost provides a concurrent, reference-counted scope that defines a shared, ephemeral context for the duration of an epoch.

The missing piece is how an external observer can deterministically await an object that employs either mechanism without guessing timing. One compelling reason to do this would be to compose a unit test that observes it.

Example - Filter a Collection after Input Text Settles

Consider a class that models an IME.

class SettleBeforeFilterModel : INotifyPropertyChanged
{
    public SettleBeforeFilterModel()
    {
        WDTSettle = new WatchdogTimer(defaultCompleteAction: FilterList)
        {
            Interval = TimeSpan.FromSeconds(0.1)
        };
    }

    /// <summary>
    /// Placeholder - Will apply filtering to Items based on settled input text.
    /// </summary>
    private void FilterList() { } 

    public string InputText
    {
        get => _inputText;
        set
        {
            if (!Equals(_inputText, value))
            {
                _inputText = value;
                WDTSettle.StartOrRestart();
                OnPropertyChanged();
            }
        }
    }
    string _inputText = string.Empty;

	public ObservableCollection<Item>{ get; } = new();    

    public WatchdogTimer WDTSettle { get; }
    
    protected virtual void OnPropertyChanged([CallerMemberName] string? propertyName = null) =>
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));

    public event PropertyChangedEventHandler? PropertyChanged;
}

This works at runtime, but it is not testable. There is no deterministic way to know when the final filter operation has completed (i.e., via CollectionChanged on Items). Polling or inserting a "magic delay" is brittle and race-prone.

Converting to an Awaitable Class

By composing an EpochController, the model becomes awaitable without changing its public behavior:

class SettleBeforeFilterModel : INotifyPropertyChanged, IAwaitableEpoch
{
    readonly EpochController _epoch = new();

    public string InputText
    {
        get => _inputText;
        set
        {
            if (!Equals(_inputText, value))
            {
                _inputText = value;
                WDTEpoch.StartOrRestart();
                OnPropertyChanged();
            }
        }
    }
    string _inputText = string.Empty;

    public DisposableHost DHostEpoch => _epoch.DHostEpoch;
    public WatchdogTimer WDTEpoch => _epoch.WDTEpoch;
    public TaskAwaiter GetAwaiter() => _epoch.GetAwaiter();
}

Internally, EpochController binds quiescent activity and deterministic scopes into a single renewable completion boundary. Each epoch completes only when all concerns have finished.

Deterministic Testing

The unit test can now await behavior directly:

sbf.InputText = "abc";
await sbf; // waits for dwell to settle

using (sbf.DHostEpoch.GetToken())
{
    sbf.InputText = "def";
    // epoch remains open until scope exits
}

await sbf; // completes after both concerns finish

The await completes at:

max(quiescence completion, deterministic scope completion)

Summary

EpochCompletionSource turns time-based settling and scope-based lifetimes into a single awaitable concept. The result is code that behaves the same at runtime, but becomes precise, deterministic, and testable without ceremony.

This means that any external client, for test purposes or any other reason, can await an instance of this class and act with confidence on its temporal state without having to resort to polling, sleeps, or timing assumptions.