using Titano.Core.Imaging; using Titano.Testing; namespace Titano.Core.Tests.Decoding; /// : memory bound independent of sequence length, spill round trip, read-ahead, /// cancellation and deterministic disposal (BRIEF §8.4, §20.4 memory and cancellation gates). public sealed class FrameWindowTests(TestContext context) { private const int Size = 64; private const long FrameBytes = Size * Size * 3 * sizeof(float); /// Synthetic loader whose frames encode their index; records every buffer it hands out. private sealed class Source { private readonly List _made = []; public int Loads; public TimeSpan Delay; public async ValueTask Load(int index, CancellationToken cancellationToken) { Interlocked.Increment(ref Loads); if (Delay > TimeSpan.Zero) await Task.Delay(Delay, cancellationToken); var image = new ImageBuffer(Size, Size, 3, clear: false); image.Data.Fill(index); image[1, 5, 7] = index + 0.25f; lock (_made) _made.Add(image); return image; } /// Loader-made buffers not yet disposed (independent of the window's own counters). public int Live() { lock (_made) { var live = 0; foreach (var b in _made) { try { _ = b.Storage; live++; } catch (ObjectDisposedException) { } } return live; } } } private static void AssertFrame(FrameLease lease) { Assert.Equal((float)lease.Index, lease.Image[0, 10, 10]); Assert.Equal(lease.Index + 0.25f, lease.Image[1, 5, 7]); } /// Render loop: each step moves the window and reads the frame plus its three predecessors — four frames /// needed per step against a three-frame budget, so in-window frames must be spilled and read back. private async Task<(FrameWindowStatistics Stats, int PeakLive, string? Spill)> Render(int frames, string spillDirectory) { var source = new Source(); var options = new FrameWindowOptions { Behind = 3, Ahead = 4, MemoryBudget = 3 * FrameBytes, SpillDirectory = spillDirectory }; var peakLive = 0; FrameWindowStatistics stats; string? spill; await using (var window = new FrameWindow(frames, source.Load, options)) { for (var i = 0; i < frames; i++) { window.MoveTo(i); using (var current = await window.GetAsync(i)) AssertFrame(current); for (var back = 1; back <= 3 && i - back >= 0; back++) { using var previous = await window.GetAsync(i - back); AssertFrame(previous); } peakLive = int.Max(peakLive, source.Live()); Assert.LessOrEqual(window.Statistics.LiveBytes, options.MemoryBudget); } stats = window.Statistics; spill = window.SpillPath; Assert.FileExists(spill!); } Assert.Equal(0, source.Live()); return (stats, peakLive, spill); } [Test] [Timeout(30_000)] public async Task PeakMemoryIsBoundedAndIndependentOfSequenceLength() { var dir = context.CreateTempDirectory(); var shortRun = await Render(40, dir); var longRun = await Render(400, dir); context.Log($"40 frames: {shortRun.Stats}, peak live {shortRun.PeakLive}; 400 frames: {longRun.Stats}, peak live {longRun.PeakLive}"); foreach (var run in new[] { shortRun, longRun }) { Assert.LessOrEqual(run.Stats.PeakLiveBytes, 3 * FrameBytes); Assert.LessOrEqual(run.PeakLive, 3); Assert.Greater(run.Stats.SpillWrites, 0); Assert.Greater(run.Stats.SpillReads, 0); // Spill extents are reused: only frames inside the window (3 behind + current + 4 ahead) are ever on disk. Assert.LessOrEqual(run.Stats.SpillFileBytes, 8 * FrameBytes); Assert.FileMissing(run.Spill!); } Assert.Equal(shortRun.Stats.PeakLiveBytes, longRun.Stats.PeakLiveBytes); Assert.Equal(shortRun.PeakLive, longRun.PeakLive); Assert.LessOrEqual(longRun.Stats.SpillFileBytes, shortRun.Stats.SpillFileBytes); } [Test] [Timeout(10_000)] public async Task ReadAheadDecodesInTheBackground() { var source = new Source(); await using var window = new FrameWindow(100, source.Load, new FrameWindowOptions { Ahead = 3, MemoryBudget = 10 * FrameBytes }); window.MoveTo(0); using (var first = await window.GetAsync(0)) AssertFrame(first); var deadline = DateTime.UtcNow.AddSeconds(5); while (source.Loads < 4 && DateTime.UtcNow < deadline) await Task.Delay(5); Assert.Equal(4, source.Loads); using var ahead = await window.GetAsync(3); AssertFrame(ahead); Assert.Equal(4, source.Loads); } [Test] [Timeout(10_000)] public async Task CancellationLeavesNoSpillFileAndNoUnobservedErrors() { var unobserved = 0; void OnUnobserved(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved); TaskScheduler.UnobservedTaskException += OnUnobserved; try { var dir = context.CreateTempDirectory(); var source = new Source(); string? spill; using var cts = new CancellationTokenSource(); var window = new FrameWindow(50, source.Load, new FrameWindowOptions { Behind = 3, Ahead = 2, MemoryBudget = 2 * FrameBytes, SpillDirectory = dir }); try { for (var i = 0; i < 6; i++) { window.MoveTo(i); using var a = await window.GetAsync(i); if (i > 0) { using var b = await window.GetAsync(i - 1); } } spill = window.SpillPath; Assert.NotNull(spill); Assert.FileExists(spill!); source.Delay = TimeSpan.FromSeconds(30); window.MoveTo(20); var pending = window.GetAsync(20, cts.Token); cts.CancelAfter(50); await Assert.ThrowsAsync(async () => await pending); } finally { await window.DisposeAsync(); } Assert.FileMissing(spill!); Assert.Equal(0, source.Live()); await Assert.ThrowsAsync(async () => await window.GetAsync(1)); } finally { GC.Collect(); GC.WaitForPendingFinalizers(); TaskScheduler.UnobservedTaskException -= OnUnobserved; } Assert.Equal(0, unobserved); } [Test] public async Task LoaderFailuresSurfaceAndCanBeRetried() { var attempts = 0; async ValueTask Flaky(int index, CancellationToken ct) { await Task.Yield(); if (index == 2 && Interlocked.Increment(ref attempts) == 1) throw new InvalidDataException("bad frame"); var image = new ImageBuffer(8, 8, 3); image.Data.Fill(index); return image; } await using var window = new FrameWindow(5, Flaky, new FrameWindowOptions { Ahead = 0 }); await Assert.ThrowsAsync(async () => await window.GetAsync(2)); using var retried = await window.GetAsync(2); Assert.Equal(2f, retried.Image[0, 0, 0]); } }