Merge pull request #20 from rian-be/develop

Feat: BenchmarkDotNet suites for render and player pipelines

Author: rian-be

Benchmarks/ChangeTrace.Benchmarks.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\ChangeTrace.csproj" />
+        <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
+    </ItemGroup>
+
+</Project>

Benchmarks/Player/Benchmarks/EventCursorBenchmarks.cs

@@ -0,0 +1,56 @@
+using BenchmarkDotNet.Attributes;
+using ChangeTrace.Player.Playback;
+
+namespace ChangeTrace.Benchmarks.Player;
+
+/// <summary>
+/// Benchmarks low-level timeline cursor navigation.
+/// </summary>
+/// <remarks>
+/// Measures binary seeking and forward draining over synthetic timeline events.
+/// These operations are used by player seeking and playback tick event emission.
+/// </remarks>
+[MemoryDiagnoser]
+[InProcess]
+[MinIterationTime(250)]
+public class EventCursorBenchmarks
+{
+    private PlayerBenchmarkFixture _fixture = null!;
+    private EventCursor _cursor = null!;
+
+    /// <summary>
+    /// Number of synthetic timeline events used by the cursor.
+    /// </summary>
+    [Params(1_000, 10_000, 100_000)]
+    public int EventCount { get; set; }
+
+    /// <summary>
+    /// Creates deterministic player benchmark state for the current event count.
+    /// </summary>
+    [GlobalSetup]
+    public void Setup()
+    {
+        _fixture = PlayerBenchmarkFixture.Create(EventCount);
+        _cursor = _fixture.CreateCursor();
+    }
+
+    /// <summary>
+    /// Seeks to the middle of the event stream using cursor binary search.
+    /// </summary>
+    [Benchmark]
+    public int SeekToMiddle()
+    {
+        _cursor.SeekTo(EventCount / 2.0);
+        return _cursor.Index;
+    }
+
+    /// <summary>
+    /// Drains all events forward from a fresh cursor.
+    /// </summary>
+    [Benchmark]
+    public int DrainForwardAll()
+    {
+        _cursor.ResetToStart();
+        return _cursor.DrainForward(EventCount).Count;
+    }
+}

Benchmarks/Player/Benchmarks/SeekableTimelineBenchmarks.cs

@@ -0,0 +1,59 @@
+using BenchmarkDotNet.Attributes;
+using ChangeTrace.Core.Models;
+using ChangeTrace.Player.Playback;
+
+namespace ChangeTrace.Benchmarks.Player;
+
+/// <summary>
+/// Benchmarks player seek operations.
+/// </summary>
+/// <remarks>
+/// Measures absolute and relative seek paths, including virtual clock snapping,
+/// cursor repositioning, and progress calculation.
+/// </remarks>
+[MemoryDiagnoser]
+[InProcess]
+[MinIterationTime(250)]
+public class SeekableTimelineBenchmarks
+{
+    private PlayerBenchmarkFixture _fixture = null!;
+    private SeekableTimeline _seekable = null!;
+    private Timestamp _middle = default;
+
+    /// <summary>
+    /// Number of synthetic timeline events used by seek benchmarks.
+    /// </summary>
+    [Params(1_000, 10_000, 100_000)]
+    public int EventCount { get; set; }
+
+    /// <summary>
+    /// Creates deterministic player benchmark state for the current event count.
+    /// </summary>
+    [GlobalSetup]
+    public void Setup()
+    {
+        _fixture = PlayerBenchmarkFixture.Create(EventCount);
+        _seekable = _fixture.CreateSeekable();
+        _middle = Timestamp.Create(EventCount / 2).Value;
+    }
+
+    /// <summary>
+    /// Seeks to the middle of the timeline using an absolute timestamp.
+    /// </summary>
+    [Benchmark]
+    public double SeekToMiddle()
+    {
+        _seekable.Seek(_middle);
+        return _seekable.Progress;
+    }
+
+    /// <summary>
+    /// Seeks relative to the current position and returns progress.
+    /// </summary>
+    [Benchmark]
+    public double SeekRelativeSmallDelta()
+    {
+        _seekable.SeekRelative(17);
+        return _seekable.Progress;
+    }
+}

Benchmarks/Player/Benchmarks/TimelinePlayerFactoryBenchmarks.cs

@@ -0,0 +1,43 @@
+using BenchmarkDotNet.Attributes;
+
+namespace ChangeTrace.Benchmarks.Player;
+
+/// <summary>
+/// Benchmarks creation of fully wired timeline players.
+/// </summary>
+/// <remarks>
+/// Covers factory wiring, timeline duration calculation, timeline normalization,
+/// cursor creation, seekable timeline creation, and transport setup.
+/// </remarks>
+[MemoryDiagnoser]
+[InProcess]
+[MinIterationTime(250)]
+public class TimelinePlayerFactoryBenchmarks
+{
+    private PlayerBenchmarkFixture _fixture = null!;
+
+    /// <summary>
+    /// Number of synthetic timeline events used to create the player.
+    /// </summary>
+    [Params(1_000, 10_000, 100_000)]
+    public int EventCount { get; set; }
+
+    /// <summary>
+    /// Creates deterministic player benchmark state for the current event count.
+    /// </summary>
+    [GlobalSetup]
+    public void Setup()
+        => _fixture = PlayerBenchmarkFixture.Create(EventCount);
+
+    /// <summary>
+    /// Creates and disposes a fully wired timeline player.
+    /// </summary>
+    [Benchmark]
+    public double CreateTimelinePlayer()
+    {
+        using var player = _fixture.CreatePlayerFactory()
+            .Create(PlayerBenchmarkFixture.CreateTimeline(EventCount));
+
+        return player.DurationSeconds;
+    }
+}

Benchmarks/Player/Benchmarks/TimelineStepperBenchmarks.cs

@@ -0,0 +1,46 @@
+using BenchmarkDotNet.Attributes;
+
+namespace ChangeTrace.Benchmarks.Player;
+
+/// <summary>
+/// Benchmarks single-event stepping through a timeline.
+/// </summary>
+/// <remarks>
+/// Measures the cost of repeatedly calling the player stepper until all events have
+/// been emitted. This covers cursor movement and virtual clock position snapping.
+/// </remarks>
+[MemoryDiagnoser]
+[InProcess]
+[MinIterationTime(250)]
+public class TimelineStepperBenchmarks
+{
+    private PlayerBenchmarkFixture _fixture = null!;
+
+    /// <summary>
+    /// Number of synthetic timeline events stepped through by the benchmark.
+    /// </summary>
+    [Params(1_000, 10_000, 100_000)]
+    public int EventCount { get; set; }
+
+    /// <summary>
+    /// Creates deterministic player benchmark state for the current event count.
+    /// </summary>
+    [GlobalSetup]
+    public void Setup()
+        => _fixture = PlayerBenchmarkFixture.Create(EventCount);
+
+    /// <summary>
+    /// Steps forward through all events in a fresh stepper.
+    /// </summary>
+    [Benchmark]
+    public int StepForwardThroughAllEvents()
+    {
+        var stepper = _fixture.CreateStepper();
+        var moved = 0;
+
+        while (stepper.StepForward().IsSuccess)
+            moved++;
+
+        return moved;
+    }
+}

Benchmarks/Player/Fixtures/PlayerBenchmarkFixture.cs

@@ -0,0 +1,137 @@
+using ChangeTrace.Core.Diagnostics;
+using ChangeTrace.Core.Events;
+using ChangeTrace.Core.Events.Info;
+using ChangeTrace.Core.Models;
+using ChangeTrace.Core.Timelines;
+using ChangeTrace.Player.Factory;
+using ChangeTrace.Player.Interfaces;
+using ChangeTrace.Player.Playback;
+
+namespace ChangeTrace.Benchmarks.Player;
+
+/// <summary>
+/// Shared deterministic fixture for player benchmarks.
+/// </summary>
+/// <remarks>
+/// Creates synthetic timelines and player components without starting the timer-driven
+/// playback transport, keeping benchmarks deterministic and CPU-bound.
+/// </remarks>
+internal sealed class PlayerBenchmarkFixture
+{
+    private readonly IReadOnlyList<TraceEvent> _events;
+
+    private PlayerBenchmarkFixture(
+        int eventCount,
+        Timeline timeline,
+        IReadOnlyList<TraceEvent> events)
+    {
+        EventCount = eventCount;
+        Timeline = timeline;
+        _events = events;
+    }
+
+    /// <summary>
+    /// Number of synthetic timeline events represented by the fixture.
+    /// </summary>
+    public int EventCount { get; }
+
+    /// <summary>
+    /// Synthetic timeline used by factory-level player benchmarks.
+    /// </summary>
+    public Timeline Timeline { get; }
+
+    /// <summary>
+    /// Builds a player benchmark fixture with normalized event playback times.
+    /// </summary>
+    /// <param name="eventCount">Number of synthetic timeline events to create.</param>
+    public static PlayerBenchmarkFixture Create(int eventCount)
+    {
+        var timeline = CreateTimeline(eventCount);
+        TimelineNormalizer.Normalize(timeline, targetDurationSeconds: eventCount);
+        return new PlayerBenchmarkFixture(eventCount, timeline, timeline.Events.ToArray());
+    }
+
+    /// <summary>
+    /// Creates a fresh event cursor over the fixture events.
+    /// </summary>
+    public EventCursor CreateCursor()
+        => new(_events);
+
+    /// <summary>
+    /// Creates a fresh stepper using a new cursor and virtual clock.
+    /// </summary>
+    public TimelineStepper CreateStepper()
+        => new(CreateCursor(), CreateClock());
+
+    /// <summary>
+    /// Creates a seekable timeline over a new cursor and virtual clock.
+    /// </summary>
+    public SeekableTimeline CreateSeekable()
+        => new(CreateClock(), CreateCursor(), EventCount);
+
+    /// <summary>
+    /// Creates a player factory with no-op diagnostics.
+    /// </summary>
+    public TimelinePlayerFactory CreatePlayerFactory()
+        => new(new NoopDiagnosticsProvider());
+
+    /// <summary>
+    /// Creates a raw synthetic timeline.
+    /// </summary>
+    /// <param name="eventCount">Number of events to create.</param>
+    public static Timeline CreateTimeline(int eventCount)
+    {
+        var repository = RepositoryId.Create("bench", "player").Value;
+        var timeline = new Timeline(repository);
+        var actor = ActorName.Create("benchmark-user").Value;
+        const long baseUnix = 1_700_000_000;
+
+        for (var i = 0; i < eventCount; i++)
+        {
+            var timestamp = Timestamp.Create(baseUnix + i).Value;
+            timeline.AddEvent(new TraceEvent(
+                new TraceEventCore(
+                    timestamp,
+                    actor,
+                    $"src/module-{i % 128}/file-{i}.cs")));
+        }
+
+        return timeline;
+    }
+
+    private static VirtualClock CreateClock()
+        => new(initialSpeed: 1.0, acceleration: 1.0);
+
+    private sealed class NoopDiagnosticsProvider : IDiagnosticsProvider
+    {
+        /// <inheritdoc />
+        public MemoryMetrics GetMemoryMetrics()
+            => new(0, 0, 0);
+
+        /// <inheritdoc />
+        public int[] GetGcCollections()
+            => [0, 0, 0];
+
+        /// <inheritdoc />
+        public RuntimeMetrics GetRuntimeMetrics()
+            => new(0, 0, 0, 0);
+
+        /// <inheritdoc />
+        public IReadOnlyDictionary<string, double> GetCustomMetrics()
+            => new Dictionary<string, double>();
+
+        /// <inheritdoc />
+        public void RecordMetric(string key, double value)
+        {
+        }
+
+        /// <inheritdoc />
+        public void RecordEvent(string category, string label)
+        {
+        }
+
+        /// <inheritdoc />
+        public IReadOnlyList<KeyValuePair<string, int>> GetTopEvents(string category, int count)
+            => [];
+    }
+}

Benchmarks/Program.cs

@@ -0,0 +1,5 @@
+using BenchmarkDotNet.Running;
+
+BenchmarkSwitcher
+    .FromAssembly(typeof(Program).Assembly)
+    .Run(args);