Files
Chronos/tests/Titano.Core.Tests/Decoding/FrameWindowTests.cs
T
Claude 555d17742c feat(imaging): frame window with read-ahead, budget and float32 spill
FrameWindow keeps frames from position-Behind to position+Ahead,
decodes ahead on background tasks within the memory budget, drops
frames that leave the window and spills in-window frames farthest from
the position to a delete-on-close temp file of float32 planes (renders
stay bit-identical under memory pressure). The budget check and load
start share one lock; leases pin frames; disposal waits for decodes,
releases every buffer and deletes the spill file even after
cancellation. Tests assert a hard three-frame bound for 40 and 400
frames and an identical spill-file size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-02 11:27:16 +00:00

198 lines
7.9 KiB
C#

using Titano.Core.Imaging;
using Titano.Testing;
namespace Titano.Core.Tests.Decoding;
/// <summary><see cref="FrameWindow"/>: memory bound independent of sequence length, spill round trip, read-ahead,
/// cancellation and deterministic disposal (BRIEF §8.4, §20.4 memory and cancellation gates).</summary>
public sealed class FrameWindowTests(TestContext context)
{
private const int Size = 64;
private const long FrameBytes = Size * Size * 3 * sizeof(float);
/// <summary>Synthetic loader whose frames encode their index; records every buffer it hands out.</summary>
private sealed class Source
{
private readonly List<ImageBuffer> _made = [];
public int Loads;
public TimeSpan Delay;
public async ValueTask<ImageBuffer> 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;
}
/// <summary>Loader-made buffers not yet disposed (independent of the window's own counters).</summary>
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]);
}
/// <summary>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.</summary>
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<OperationCanceledException>(async () => await pending);
}
finally
{
await window.DisposeAsync();
}
Assert.FileMissing(spill!);
Assert.Equal(0, source.Live());
await Assert.ThrowsAsync<OperationCanceledException>(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<ImageBuffer> 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<InvalidDataException>(async () => await window.GetAsync(2));
using var retried = await window.GetAsync(2);
Assert.Equal(2f, retried.Image[0, 0, 0]);
}
}