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
198 lines
7.9 KiB
C#
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]);
|
|
}
|
|
}
|