Validate automatically on dequeue.

Author: sharpjs

DependencyQueue.Tests/DependencyQueueTests.cs

@@ -327,23 +327,11 @@ public void Validate_Disposed()
         );
     }
 
-    [Test]
-    public void Dequeue_NotValidated()
-    {
-        using var queue = new Queue();
-
-        Should.Throw<InvalidOperationException>(
-            () => queue.Dequeue()
-        );
-    }
-
     [Test]
     public void Dequeue_Empty()
     {
         using var queue = new Queue();
 
-        queue.ShouldBeValid();
-
         queue.Dequeue().ShouldBeNull();
     }
 
@@ -359,6 +347,23 @@ public void Dequeue_Disposed()
         );
     }
 
+    [Test]
+    public void Dequeue_Invalid()
+    {
+        using var queue = new Queue();
+
+        var entry = queue.Enqueue("a", value: new(), requires: ["b"]);
+
+        var e = Should.Throw<InvalidDependencyQueueException>(
+            () => queue.Dequeue()
+        );
+
+        e.Errors
+            .ShouldHaveSingleItem()
+            .ShouldBeOfType<DependencyQueueUnprovidedTopicError<Value>>()
+            .Topic.Name.ShouldBe("b");
+    }
+
     [Test]
     public void Dequeue_Ok()
     {
@@ -367,7 +372,6 @@ public void Dequeue_Ok()
         var entry = queue.Enqueue("a", value: new());
 
         queue.ShouldBeValid();
-
         queue.ShouldHaveReadyEntries([entry]);
         queue.ShouldHaveTopicCount(1);
         queue.ShouldHaveTopic("a", providedBy: [entry]);
@@ -389,8 +393,6 @@ public void Dequeue_WaitForRequiredEntries()
         var entryB1 = queue.Enqueue("b1", value: new(), provides: ["b"]);
         var entryC  = queue.Enqueue("c",  value: new());
 
-        queue.ShouldBeValid();
-
         queue.Dequeue().ShouldBeSameAs(entryB0);
         queue.Dequeue().ShouldBeSameAs(entryB1);
         queue.Dequeue().ShouldBeSameAs(entryC);
@@ -449,8 +451,6 @@ public void Dequeue_WithPredicate()
 
         var entry = queue.Enqueue("a", value: new());
 
-        queue.ShouldBeValid();
-
         var testedValues = new ConcurrentQueue<Value>();
 
         bool ReturnTrueOnSecondInvocation(Value value)
@@ -482,8 +482,6 @@ public void Dequeue_Exhausted()
         var entryA = queue.Enqueue("a", value: new(), requires: ["b"]);
         var entryB = queue.Enqueue("b", value: new());
 
-        queue.ShouldBeValid();
-
         queue.Dequeue().ShouldBeSameAs(entryB);
 
         var stopwatch       = new Stopwatch();
@@ -514,23 +512,11 @@ void CompleteEntryB()
         queue.ShouldHaveTopicCount(0);
     }
 
-    [Test]
-    public async Task DequeueAsync_NotValidated()
-    {
-        using var queue = new Queue();
-
-        await Should.ThrowAsync<InvalidOperationException>(
-            () => queue.DequeueAsync()
-        );
-    }
-
     [Test]
     public async Task DequeueAsync_Initial()
     {
         using var queue = new Queue();
 
-        queue.ShouldBeValid();
-
         (await queue.DequeueAsync()).ShouldBeNull();
     }
 
@@ -548,15 +534,30 @@ await Should.ThrowAsync<ObjectDisposedException>(
         );
     }
 
+    [Test]
+    public async Task DequeueAsync_Invalid()
+    {
+        using var queue = new Queue();
+
+        var entry = queue.Enqueue("a", value: new(), requires: ["b"]);
+
+        var e = await Should.ThrowAsync<InvalidDependencyQueueException>(
+            () => queue.DequeueAsync()
+        );
+
+        e.Errors
+            .ShouldHaveSingleItem()
+            .ShouldBeOfType<DependencyQueueUnprovidedTopicError<Value>>()
+            .Topic.Name.ShouldBe("b");
+    }
+
     [Test]
     public async Task DequeueAsync_Ok()
     {
         using var queue = new Queue();
 
         var entry = queue.Enqueue("a", value: new());
 
-        queue.ShouldBeValid();
-
         (await queue.DequeueAsync()).ShouldBeSameAs(entry);
 
         queue.ShouldNotHaveReadyEntries();                  // removed when dequeued
@@ -574,8 +575,6 @@ public async Task DequeueAsync_WaitForRequiredEntries()
         var entryB1 = queue.Enqueue("b1", value: new(), provides: ["b"]);
         var entryC  = queue.Enqueue("c",  value: new());
 
-        queue.ShouldBeValid();
-
         (await queue.DequeueAsync()).ShouldBeSameAs(entryB0);
         (await queue.DequeueAsync()).ShouldBeSameAs(entryB1);
         (await queue.DequeueAsync()).ShouldBeSameAs(entryC);
@@ -640,8 +639,6 @@ public async Task DequeueAsync_WithPredicate()
 
         var entry = queue.Enqueue("a", value: new());
 
-        queue.ShouldBeValid();
-
         var testedValues = new ConcurrentQueue<Value>();
 
         bool ReturnTrueOnSecondInvocation(Value value)
@@ -673,8 +670,6 @@ public async Task DequeueAsync_Exhausted()
         var entryA = queue.Enqueue("a", value: new(), requires: ["b"]);
         var entryB = queue.Enqueue("b", value: new());
 
-        queue.ShouldBeValid();
-
         (await queue.DequeueAsync()).ShouldBeSameAs(entryB);
 
         var stopwatch       = new Stopwatch();
@@ -728,7 +723,6 @@ public void Complete_Disposed()
 
         var entry = queue.Enqueue("a", value: new());
 
-        queue.ShouldBeValid();
         queue.Dequeue().ShouldBeSameAs(entry);
         queue.Dispose();
 

DependencyQueue.Tests/InvalidDependencyQueueExceptionTests.cs

@@ -0,0 +1,34 @@
+// Copyright Subatomix Research Inc.
+// SPDX-License-Identifier: MIT
+
+namespace DependencyQueue;
+
+[TestFixture]
+public class InvalidDependencyQueueExceptionTests
+{
+    [Test]
+    public void Construct_NullErrors()
+    {
+        Should.Throw<ArgumentNullException>(
+            () => new InvalidDependencyQueueException(null!)
+        );
+    }
+
+    [Test]
+    public void Errors_Get()
+    {
+        var topicA = new DependencyQueueTopic<Value>("a");
+        var topicB = new DependencyQueueTopic<Value>("b");
+        var entryC = new DependencyQueueEntry<Value>("c", value: new(), StringComparer.Ordinal);
+
+        var errors = new DependencyQueueError[]
+        {
+            new DependencyQueueUnprovidedTopicError<Value>(topicA),
+            new DependencyQueueCycleError<Value>(entryC, topicB)
+        };
+
+        var exception = new InvalidDependencyQueueException(errors);
+
+        exception.Errors.ShouldBeSameAs(errors);
+    }
+}

DependencyQueue/DependencyQueue.cs

@@ -25,8 +25,11 @@ public class DependencyQueue<T> : IDisposable
     // Thing that an execution context must lock exclusively to access queue state
     private readonly AsyncMonitor _monitor;
 
-    // Whether queue state is valid
-    private bool _isValid;
+    // Whether the dependency graph is valid, invalid, or of unknown validity
+    private Validity _validity;
+
+    // Possible values of _validity
+    private enum Validity { Unknown = 0, Invalid = -1, Valid = +1 }
 
     /// <summary>
     ///   Initializes a new <see cref="DependencyQueue{T}"/> instance,
@@ -40,9 +43,10 @@ public class DependencyQueue<T> : IDisposable
     /// </param>
     public DependencyQueue(StringComparer? comparer = null)
     {
-        _ready   = new();
-        _topics  = new(_comparer = comparer ?? StringComparer.Ordinal);
-        _monitor = new();
+        _ready    = new();
+        _topics   = new(_comparer = comparer ?? StringComparer.Ordinal);
+        _monitor  = new();
+        _validity = Validity.Valid;
     }
 
     /// <summary>
@@ -165,7 +169,8 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
         if (entry.Requires.Count == 0)
             _ready.Enqueue(entry);
 
-        _isValid = false;
+        _validity = Validity.Unknown;
+        _monitor.PulseAll();
     }
 
     /// <summary>
@@ -184,6 +189,12 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     /// </returns>
     /// <remarks>
     ///   <para>
+    ///     If <see cref="Validate"/> has not been invoked since the most
+    ///     recent modification of the queue, this method automatically
+    ///     validates the queue.  If the queue is invalid, this method throws
+    ///     <see cref="InvalidDependencyQueueException"/>.
+    ///   </para>
+    ///   <para>
     ///     This method returns only when an entry is dequeued from the queue
     ///     or when no more entries remain to dequeue.
     ///   </para>
@@ -207,9 +218,10 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     ///     This method is thread-safe.
     ///   </para>
     /// </remarks>
-    /// <exception cref="InvalidOperationException">
-    ///   The queue state is invalid or has not been validated.  Use the
-    ///   <see cref="Validate"/> method and correct any errors it returns.
+    /// <exception cref="InvalidDependencyQueueException">
+    ///   The dependency graph is invalid.  The
+    ///   <see cref="InvalidDependencyQueueException.Errors"/> collection
+    ///   contains the errors found during validation.
     /// </exception>
     /// <exception cref="ObjectDisposedException">
     ///   The queue has been disposed.
@@ -222,8 +234,7 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
 
         using var @lock = _monitor.Acquire();
 
-        if (!_isValid)
-            throw Errors.NotValid();
+        RequireValid();
 
         for (;;)
         {
@@ -257,6 +268,12 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     /// </returns>
     /// <remarks>
     ///   <para>
+    ///     If <see cref="Validate"/> has not been invoked since the most
+    ///     recent modification of the queue, this method automatically
+    ///     validates the queue.  If the queue is invalid, this method throws
+    ///     <see cref="InvalidDependencyQueueException"/>.
+    ///   </para>
+    ///   <para>
     ///     This method returns only when an entry is dequeued from the queue
     ///     or when no more entries remain to dequeue.
     ///   </para>
@@ -270,9 +287,10 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     ///     This method is thread-safe.
     ///   </para>
     /// </remarks>
-    /// <exception cref="InvalidOperationException">
-    ///   The queue state is invalid or has not been validated.  Use the
-    ///   <see cref="Validate"/> method and correct any errors it returns.
+    /// <exception cref="InvalidDependencyQueueException">
+    ///   The dependency graph is invalid.  The
+    ///   <see cref="InvalidDependencyQueueException.Errors"/> collection
+    ///   contains the errors found during validation.
     /// </exception>
     /// <exception cref="ObjectDisposedException">
     ///   The queue has been disposed.
@@ -302,6 +320,12 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     /// </returns>
     /// <remarks>
     ///   <para>
+    ///     If <see cref="Validate"/> has not been invoked since the most
+    ///     recent modification of the queue, this method automatically
+    ///     validates the queue.  If the queue is invalid, this method throws
+    ///     <see cref="InvalidDependencyQueueException"/>.
+    ///   </para>
+    ///   <para>
     ///     This method returns only when an entry is dequeued from the queue
     ///     or when no more entries remain to dequeue.
     ///   </para>
@@ -325,9 +349,10 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
     ///     This method is thread-safe.
     ///   </para>
     /// </remarks>
-    /// <exception cref="InvalidOperationException">
-    ///   The queue state is invalid or has not been validated.  Use the
-    ///   <see cref="Validate"/> method and correct any errors it returns.
+    /// <exception cref="InvalidDependencyQueueException">
+    ///   The dependency graph is invalid.  The
+    ///   <see cref="InvalidDependencyQueueException.Errors"/> collection
+    ///   contains the errors found during validation.
     /// </exception>
     /// <exception cref="ObjectDisposedException">
     ///   The queue has been disposed.
@@ -342,8 +367,7 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
 
         using var @lock = await _monitor.AcquireAsync(cancellation);
 
-        if (!_isValid)
-            throw Errors.NotValid();
+        RequireValid();
 
         for (;;)
         {
@@ -465,7 +489,7 @@ public void Clear()
 
         _ready .Clear();
         _topics.Clear();
-        _isValid = true;
+        _validity = Validity.Valid;
 
         _monitor.PulseAll();
     }
@@ -490,10 +514,27 @@ private DependencyQueueTopic<T> GetOrAddTopic(string name)
     /// </remarks>
     public IReadOnlyList<DependencyQueueError> Validate()
     {
-        var errors = new List<DependencyQueueError>();
-
         using var @lock = _monitor.Acquire();
 
+        return ValidateCore();
+    }
+
+    private void RequireValid()
+    {
+        if (_validity is Validity.Valid)
+            return;
+
+        var errors = ValidateCore();
+
+        if (errors.Count is 0)
+            return;
+
+        throw Errors.QueueInvalid(errors);
+    }
+
+    private IReadOnlyList<DependencyQueueError> ValidateCore()
+    {
+        var errors  = new List<DependencyQueueError>();
         var visited = new Dictionary<string, bool>(_topics.Count, _comparer);
 
         foreach (var topic in _topics.Values)
@@ -504,7 +545,9 @@ public IReadOnlyList<DependencyQueueError> Validate()
                 DetectCycles(null, topic, visited, errors);
         }
 
-        _isValid = errors.Count == 0;
+        _validity = errors.Count is 0
+            ? Validity.Valid
+            : Validity.Invalid;
 
         return errors;
     }