HellionChat/HellionChat/Util/DbOperationGate.cs

namespace HellionChat.Util;

// Which long-running database operation currently owns the store.
internal enum DbOperation
{
    None,
    RetentionSweep,
    Export,
    Cleanup,
    Clear,

    // Read-only, but they hold the store long enough to matter: the preview
    // scans every row, the metadata read takes the read lock, and maintenance
    // rewrites the file without touching a single row.
    Preview,
    Maintenance,
}

// One gate for every operation that holds the message store for longer than a
// frame. Generalises the retention-sweep lock, which already did exactly this
// for a single case.
//
// The reason it has to cover all of them together, not one each: an export holds
// a reader open for as long as it writes, and VACUUM needs the database to
// itself. Since v1.12.0 that reader sits on its own connection, so the clash
// surfaces as SQLITE_BUSY and a five-second timeout rather than the immediate
// SQLITE_ERROR a shared connection produced -- but a VACUUM that gives up after
// five seconds still fails, and it fails after the DELETE has committed. The
// rows are gone and the file is not compacted. PerformMaintenance runs VACUUM,
// REINDEX and ANALYZE as one batch, so the latter two never run either.
//
// Serialising the operations removes the question instead of tuning timeouts
// around it.
//
// Pure state machine, no ImGui and no database, so the build suite can pin the
// transitions without standing up either.
internal sealed class DbOperationGate
{
    private readonly object _lock = new();

    // Volatile because the draw thread reads it every frame to decide which
    // buttons are disabled, and must never block on the lock to do so -- that
    // would freeze the game for the length of a VACUUM.
    private volatile DbOperation _current = DbOperation.None;

    internal DbOperation Current => _current;

    // Bumped whenever an operation that could have changed rows finishes. A
    // cleanup preview snapshots it and treats a mismatch as stale: after a
    // retention sweep or a wipe its numbers describe a database that is gone,
    // and the comparison against the config alone cannot see that.
    private long _revision;

    internal long Revision => Interlocked.Read(ref _revision);

    // Which operations can change what a preview counted. Getting this wrong in
    // the permissive direction only costs a needless recount; getting it wrong
    // the other way lets somebody confirm a number that is no longer true.
    //
    // The preview itself must not be in here, and that is not a detail: it takes
    // the gate, so counting its own release would mark every preview stale the
    // instant it finished and the apply button would never appear.
    private static bool Mutates(DbOperation operation) =>
        operation is DbOperation.RetentionSweep or DbOperation.Cleanup or DbOperation.Clear;

    internal bool IsBusy => _current != DbOperation.None;

    // False when another operation already owns the store. Callers must not
    // queue or wait: everything here is user-initiated, and a queued wipe that
    // fires minutes later is worse than one that refuses.
    internal bool TryBegin(DbOperation operation)
    {
        if (operation == DbOperation.None)
            throw new ArgumentOutOfRangeException(
                nameof(operation),
                "None is the idle state, not an operation to begin."
            );

        lock (_lock)
        {
            if (_current != DbOperation.None)
                return false;

            _current = operation;
            return true;
        }
    }

    // Releases only what the caller acquired. Idempotent for that caller, and a
    // no-op for anyone else -- a worker whose TryBegin was refused still runs its
    // finally, and a blind reset there would hand away the lock of whichever
    // operation actually holds it. That is worse than no gate: the refused
    // worker walks away believing it did nothing while a VACUUM starts under
    // somebody's open reader.
    internal void End(DbOperation operation)
    {
        lock (_lock)
        {
            if (_current != operation)
                return;

            _current = DbOperation.None;
            if (Mutates(operation))
                Interlocked.Increment(ref _revision);
        }
    }
}