Replace SetEnding and ending state with Clear.

Author: sharpjs

DependencyQueue.Tests/DependencyQueueTests.cs

@@ -218,18 +218,6 @@ public void Enqueue_DuplicateEntry()
         queue.ShouldHaveTopic("a", providedBy: [entryA0, entryA1]);
     }
 
-    [Test]
-    public void Enqueue_Ending()
-    {
-        using var queue = new Queue();
-
-        queue.SetEnding();
-
-        Should.Throw<InvalidOperationException>(
-            () => queue.Enqueue("a", value: new())
-        );
-    }
-
     [Test]
     public void Enqueue_Disposed()
     {
@@ -315,18 +303,6 @@ public void Validate_Cycle_Indirect()
         error.RequiredTopic.Name.ShouldBe("a");
     }
 
-    [Test]
-    public void Validate_Ending()
-    {
-        using var queue = new Queue();
-
-        queue.SetEnding();
-
-        // TODO: Error?
-        // Allowed but not very useful
-        queue.Validate().ShouldBeEmpty();
-    }
-
     [Test]
     public void Validate_Disposed()
     {
@@ -359,23 +335,6 @@ public void Dequeue_Empty()
         queue.Dequeue().ShouldBeNull();
     }
 
-    [Test]
-    public void Dequeue_Ending()
-    {
-        using var queue = new Queue();
-
-        var entry = queue.Enqueue("a", value: new());
-
-        queue.ShouldBeValid();
-        queue.SetEnding();
-
-        queue.Dequeue().ShouldBeNull();
-
-        queue.ShouldHaveReadyEntries(entry);
-        queue.ShouldHaveTopicCount(1);
-        queue.ShouldHaveTopic("a", providedBy: [entry]);
-    }
-
     [Test]
     public void Dequeue_Disposed()
     {
@@ -563,23 +522,6 @@ public async Task DequeueAsync_Initial()
         (await queue.DequeueAsync()).ShouldBeNull();
     }
 
-    [Test]
-    public async Task DequeueAsync_Ending()
-    {
-        using var queue = new Queue();
-
-        var entry = queue.Enqueue("a", value: new());
-
-        queue.ShouldBeValid();
-        queue.SetEnding();
-
-        (await queue.DequeueAsync()).ShouldBeNull();
-
-        queue.ShouldHaveReadyEntries(entry);
-        queue.ShouldHaveTopicCount(1);
-        queue.ShouldHaveTopic("a", providedBy: [entry]);
-    }
-
     [Test]
     public async Task DequeueAsync_Disposed()
     {
@@ -767,21 +709,6 @@ public void Complete_NullEntry()
         e.ParamName.ShouldBe("entry");
     }
 
-    [Test]
-    public void Complete_Ending()
-    {
-        using var queue = new Queue();
-
-        var entry = queue.Enqueue("a", value: new());
-
-        queue.ShouldBeValid();
-        queue.Dequeue().ShouldBeSameAs(entry);
-        queue.SetEnding();
-
-        // Allowed
-        queue.Complete(entry);
-    }
-
     [Test]
     public void Complete_Disposed()
     {
@@ -867,6 +794,33 @@ public void Complete_NotEnqueued()
         queue.ShouldHaveTopic("y", providedBy: [entryY]);
     }
 
+    [Test]
+    public void Clear_Ok()
+    {
+        using var queue = new Queue();
+
+        var entry = queue.Enqueue("a", value: new());
+
+        queue.ShouldBeValid();
+        queue.Clear();
+
+        queue.ShouldNotHaveReadyEntries();
+        queue.ShouldHaveTopicCount(0);
+        queue.Dequeue().ShouldBeNull();
+    }
+
+    [Test]
+    public void Clear_Disposed()
+    {
+        var queue = new Queue();
+
+        queue.Dispose();
+
+        Should.Throw<ObjectDisposedException>(
+            () => queue.Clear()
+        );
+    }
+
     [Test]
     public void Dispose_Managed()
     {

DependencyQueue/DependencyQueue.cs

@@ -28,9 +28,6 @@ public class DependencyQueue<T> : IDisposable
     // Whether queue state is valid
     private bool _isValid;
 
-    // Whether queue processing is terminating
-    private bool _isEnding;
-
     /// <summary>
     ///   Initializes a new <see cref="DependencyQueue{T}"/> instance,
     ///   optionally with the specified topic name comparer.
@@ -159,9 +156,6 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
 
         using var @lock = _monitor.Acquire();
 
-        if (_isEnding)
-            throw Errors.QueueEnded();
-
         foreach (var name in entry.Provides)
             GetOrAddTopic(name).ProvidedBy.Add(entry);
 
@@ -233,10 +227,6 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
 
         for (;;)
         {
-            // Check if processing is ending
-            if (_isEnding)
-                return null;
-
             // Check if all topics (and thus all entries) are completed
             if (_topics.Count is 0)
                 return null;
@@ -357,10 +347,6 @@ internal void Enqueue(DependencyQueueEntry<T> entry)
 
         for (;;)
         {
-            // Check if processing is ending
-            if (_isEnding)
-                return null;
-
             // Check if all topics (and thus all entries) are completed
             if (_topics.Count is 0)
                 return null;
@@ -468,20 +454,19 @@ public void Complete(DependencyQueueEntry<T> entry)
     }
 
     /// <summary>
-    ///   Transitions the queue to the ending state.
+    ///   Removes all entries from the queue.
     /// </summary>
     /// <remarks>
-    ///   <para>
-    ///     In the ending state, no new entries can be enqueued, and dequeue
-    ///     operations return <see langword="null"/>.
-    ///   </para>
-    ///   <para>
-    ///     This method is thread-safe.
-    ///   </para>
+    ///   This method is thread-safe.
     /// </remarks>
-    public void SetEnding()
+    public void Clear()
     {
-        _isEnding = true;
+        using var @lock = _monitor.Acquire();
+
+        _ready .Clear();
+        _topics.Clear();
+        _isValid = true;
+
         _monitor.PulseAll();
     }
 

DependencyQueue/Errors.cs

@@ -26,9 +26,6 @@ internal static Exception ObjectDisposed(string? name)
     internal static Exception CollectionEmpty()
         => new InvalidOperationException("The collection is empty.");
 
-    internal static Exception QueueEnded()
-        => new InvalidOperationException("The queue is ended and does not accept new entries.");
-
     internal static Exception EnumeratorNoCurrentItem()
         => new InvalidOperationException(
             "The enumerator is positioned before the first element " +

README.md

@@ -103,16 +103,16 @@ constructor.
 
 ### Validation
 
-Upon construction or after enqueueing an item, a `DependencyQueue<T>` instance
-is in an unvalidated state.  Before any items can be dequeued, the queue must
-be validated.  Do that by calling `Validate()`.
+After enqueueing an item, a `DependencyQueue<T>` instance is in an unvalidated
+state.  Before any items can be dequeued, the queue must be validated.  Do that
+by calling `Validate()`.
 
 ```csharp
 var errors = queue.Validate();
 ```
 
 If the queue is valid, `Validate()` returns an empty list of error objects.
-Otherwiws, the list describes the problems found.
+Otherwise, the list describes the problems found.
 
 The web of dependencies between entries — the 'dependency graph' — can be
 invalid in two ways.
@@ -126,17 +126,15 @@ invalid in two ways.
 
 ### Dequeueing Items
 
-There are several ways to dequeue items from a `DependencyQueue<T>` instance.
-All of them require the queue to be valid.
-
-The simplest way is to call `TryDequeue()` or `TryDequeueAsync()`, which return
-the next entry in the queue or null if the queue is empty.
+To dequeue entries from a validated queue, call one of the dequeue methods
+`Dequeue()` or `DequeueAsync()`.  Both methods yield the next entry in the
+queue, or `null` if the queue is empty.
 
 ```csharp
-var entry = queue.TryDequeue();
+var entry = queue.Dequeue();
 ```
 ```csharp
-await var entry = queue.TryDequeueAsync(cancellation: cancellationToken);
+var entry = await queue.DequeueAsync(cancellation: cancellationToken);
 ```
 
 The item is available in the `Value` property of the returned entry.
@@ -148,19 +146,19 @@ call `Complete()` to inform the queue.
 queue.Complete(entry);
 ```
 
-`TryDequeue()`, `TryDequeueAsync()`, and `Complete()` are thread-safe.  For
-full thread safety information, see the [Thread Safety](#thread-safety) section
+`Dequeue()`, `DequeueAsync()`, and `Complete()` are thread-safe.  For full
+thread safety information, see the [Thread Safety](#thread-safety) section
 below.
 
-All dequeue methods support an optional predicate parameter.  If the caller
+The dequeue methods support an optional predicate parameter.  If the caller
 provides a predicate, the queue tests each ready-to-dequeue item against the
 predicate and yields the first entry for which the predicate returns `true`.
 If the predicate does not return `true` for any ready-to-dequeue item, then
 the dequeue method blocks until an item becomes available that does satisfy the
 predicate.
 
 ```csharp
-await var entry = queue.TryDequeueAsync(
+var entry = await queue.DequeueAsync(
     item => MyCustomPredicate(item),
     cancellationToken
 );
@@ -188,26 +186,19 @@ _ = view.Topics["Foo"].RequiredBy;      // Entries that require topic "Foo"
 
 ### States
 
-A `DependencyQueue<T>` instance has four possible states:
+A `DependencyQueue<T>` instance has three possible states:
 
 - **Unvalidated:**
   - The queue has not been validated or was found to be invalid.
   - Items can be enqueued.
   - Dequeue methods will throw `InvalidOperationException`.
-  - Call `Validate()`  to transition to the **Valid**    state.
-  - Call `SetEnding()` to transition to the **Ending**   state.
-  - Call `Dispose()`   to transition to the **Disposed** state.
+  - Call `Validate()` or `Clear()` to transition to the **Valid**    state.
+  - Call `Dispose()`               to transition to the **Disposed** state.
 - **Valid:**
   - The queue was found to be valid.
   - Items can be dequeued.
   - Enqueuing a new item transitions back to the **Unvalidated** state.
-  - Call `SetEnding()` to transition to the **Ending**   state.
-  - Call `Dispose()`   to transition to the **Disposed** state.
-- **Ending:**
-  - Queue processing is ending early.
-  - Items can be enqueued, but will be ignored.
-  - Dequeue methods will return `null` immediately.
-  - Call `Dispose()`   to transition to the **Disposed** state.
+  - Call `Dispose()` to transition to the **Disposed** state.
 - **Disposed:**
   - The queue has been disposed and is no longer unsable.
   - Most methods will throw `ObjectDisposedException`.
@@ -224,15 +215,15 @@ Most methods of `DependencyQueue<T>` are thread-safe.  Specifically:
 
 - The `Validate()` method is thread-safe.
 
-- The dequeue methods (`TryDequeue()`, `TryDequeueAsync()`, and `Complete()`)
+- The dequeue methods (`Dequeue()`, `DequeueAsync()`, and `Complete()`)
   are thread-safe.
 
 - The inspection methods (`Inspect()` and `InspectAsync()`) are thread-safe, as
   are the objects they return.
 
-- The `SetEnding()` method is thread-safe.
+- The `Clear()` method is thread-safe.
 
-- The `Dispose()` is <strong>Not</strong> thread-safe.
+- The `Dispose()` method is <strong>NOT</strong> thread-safe.
 
 ## Examples
 
@@ -286,7 +277,7 @@ if (errors.Any())
     throw new InvalidBurgerException(errors);
 
 // Now build the burger
-while (queue.TryDequeue() is { } entry)
+while (queue.Dequeue() is { } entry)
 {
     Console.WriteLine($"Executing: {entry.Name}");