ersatztv/ErsatzTV.Application/Streaming/WorkAheadSlots.cs

namespace ErsatzTV.Application.Streaming;

/// <summary>
/// The process-wide pool of work-ahead slots shared by every HLS session (ersatztv#536).
/// </summary>
/// <remarks>
/// <para>
/// <c>workAheadSegmenterLimit</c> is a resource guarantee, not a tuning knob: it bounds how many
/// transcodes may run unthrottled (no <c>-readrate</c>) at once, and the QSV hardware-frame pool
/// sizing from ersatztv#529 assumes that bound holds.
/// </para>
/// <para>
/// Acquisition must therefore be atomic. The previous shape — <c>Volatile.Read(count) &lt; limit</c>
/// in the caller, <c>Interlocked.Increment</c> later inside the transcode — is a check-then-act
/// TOCTOU separated by at least one <c>await</c> (the limit is a DB-backed config read), so N
/// simultaneous tune-ins all observed <c>0 &lt; limit</c> and all ran unthrottled. Same class as
/// ersatztv#231 / #250.
/// </para>
/// </remarks>
public sealed class WorkAheadSlots
{
    private int _count;
    private int _unbalancedReleases;

    /// <summary>
    /// Gets the number of slots currently held. For diagnostics and tests only — never branch on
    /// this to decide whether to work ahead; that is exactly the race <see cref="TryAcquire" /> exists to close.
    /// </summary>
    public int Count => Volatile.Read(ref _count);

    /// <summary>
    /// Atomically claims one slot if fewer than <paramref name="limit" /> are held.
    /// </summary>
    /// <returns><c>true</c> when a slot was claimed; the caller then owns it and MUST
    /// <see cref="Release" /> it exactly once.</returns>
    public bool TryAcquire(int limit)
    {
        while (true)
        {
            int current = Volatile.Read(ref _count);
            if (current >= limit)
            {
                return false;
            }

            // only the thread whose compare-exchange observes the value it read wins the slot, so
            // the count can never transiently exceed the limit and two racers can never both claim
            if (Interlocked.CompareExchange(ref _count, current + 1, current) == current)
            {
                return true;
            }
        }
    }

    /// <summary>
    /// Gets the number of releases that were not matched by a successful acquire. Non-zero always
    /// means the ownership contract was broken somewhere (no false positives), so the value is a
    /// reliable "something is wrong" signal — but it can UNDER-count and zero does not prove
    /// correctness. It only increments when a release finds the pool already empty; an over-release
    /// that happens while the count is positive — e.g. one cancelling out a coexisting leak —
    /// decrements a real-looking slot and is never recorded, so the two bugs hide each other. This
    /// is inherent to a single counter; exact accounting would need per-owner tokens (ersatztv#539 §2).
    /// </summary>
    public int UnbalancedReleases => Volatile.Read(ref _unbalancedReleases);

    /// <summary>
    /// Returns a slot claimed by <see cref="TryAcquire" />. Only ever called by the owner of that slot.
    /// </summary>
    /// <returns>
    /// <c>true</c> when a held slot was returned; <c>false</c> when the pool was already empty, i.e.
    /// the release was unbalanced (also counted in <see cref="UnbalancedReleases" />). Callers should
    /// log the <c>false</c> case: it is the only in-band signal that the budget contract was broken.
    /// </returns>
    /// <remarks>
    /// Ownership is a discipline, not a token — the same call-once contract as `EntityLocker` (#231).
    /// The one failure this defends against is an unbalanced release inflating the budget: this pool
    /// is process-wide and lives for the life of the app, so a leaked slot would silently and
    /// permanently admit one extra unthrottled transcode, re-opening the #529 QSV pool exhaustion.
    /// It clamps at zero rather than throwing — the single caller releases from a `finally`, where a
    /// throw would swallow the real exception. Unlike a decrement-first-then-clamp shape, this never
    /// publishes a negative count even transiently, so a concurrent <see cref="TryAcquire" /> can
    /// never read the pool as having phantom room and over-admit (ersatztv#539 §1); and it records
    /// the unbalanced release synchronously here, rather than blaming a later, innocent release.
    /// </remarks>
    public bool Release()
    {
        while (true)
        {
            int current = Volatile.Read(ref _count);
            if (current <= 0)
            {
                Interlocked.Increment(ref _unbalancedReleases);
                return false;
            }

            if (Interlocked.CompareExchange(ref _count, current - 1, current) == current)
            {
                return true;
            }
        }
    }
}