Improve docs, update deps, fix key sort logic (#401)

* Improve docs, update deps, fix key sort logic

Expanded README with detailed usage, API, and troubleshooting sections. Updated NuGet dependencies in test and main projects. Fixed KeyedOperation sorting to prioritize unkeyed operations correctly. Improved cancellation token handling in OperationQueueExtensions. Minor solution and XML doc updates.

* Remove Splat as unused

* Update OperationQueueExtensions.cs

Author: ChrisPulman

README.md

@@ -24,51 +24,163 @@ Then, you try to manage issuing less requests by hand, and it becomes a
 spaghetti mess as different parts of your app reach into each other to try to
 figure out who's doing what. Let's figure out a better way.
 
-### So many words, gimme the examples
-
-```cs
-var wc = new WebClient();
-var opQueue = new OperationQueue(2 /*at a time*/);
-
-// Download a bunch of images
-var foo = opQueue.Enqueue(1, 
-    () => wc.DownloadFile("https://example.com/foo.jpg", "foo.jpg"));
-var bar = opQueue.Enqueue(1, 
-    () => wc.DownloadFile("https://example.com/bar.jpg", "bar.jpg"));
-var baz = opQueue.Enqueue(1, 
-    () => wc.DownloadFile("https://example.com/baz.jpg", "baz.jpg"));
-var bamf = opQueue.Enqueue(1, 
-    () => wc.DownloadFile("https://example.com/bamf.jpg", "bamf.jpg"));
-
-// We'll be downloading the images two at a time, even though we started 
-// them all at once
-await Task.WaitAll(foo, bar, baz, bamf);
+## Key features
+
+- Bounded concurrency with a priority-aware semaphore
+- Priority scheduling (higher number runs first)
+- Key-based serialization (only one operation per key runs at a time)
+- Pause/resume with reference counting
+- Cancellation via CancellationToken or IObservable
+- Task and IObservable friendly API
+
+## Install
+
+- NuGet: `dotnet add package Punchclock`
+
+## Quick start
+
+```csharp
+using Punchclock;
+using System.Net.Http;
+
+var queue = new OperationQueue(maximumConcurrent: 2);
+var http = new HttpClient();
+
+// Fire a bunch of downloads – only two will run at a time
+var t1 = queue.Enqueue(1, () => http.GetStringAsync("https://example.com/a"));
+var t2 = queue.Enqueue(1, () => http.GetStringAsync("https://example.com/b"));
+var t3 = queue.Enqueue(1, () => http.GetStringAsync("https://example.com/c"));
+await Task.WhenAll(t1, t2, t3);
+```
+
+## Priorities
+
+- Higher numbers win. A priority 10 operation will preempt priority 1 when a slot opens.
+
+```csharp
+await queue.Enqueue(10, () => http.GetStringAsync("https://example.com/urgent"));
+```
+
+## Keys: serialize related work
+
+- Use a key to ensure only one operation for that key runs at a time.
+- Useful to avoid thundering herds against the same resource.
+
+```csharp
+// These will run one-after-another because they share the same key
+var k1 = queue.Enqueue(1, key: "user:42", () => LoadUserAsync(42));
+var k2 = queue.Enqueue(1, key: "user:42", () => LoadUserPostsAsync(42));
+await Task.WhenAll(k1, k2);
 ```
 
-Now, in a completely different part of your app, if you need something right
-away, you can specify it via the priority:
+## Cancellation
+
+- Via CancellationToken:
+
+```csharp
+using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(2));
+await queue.Enqueue(1, key: "img:1", () => DownloadImageAsync("/1"), cts.Token);
+```
+
+- Via IObservable cancellation signal:
+
+```csharp
+var cancel = new Subject<Unit>();
+var obs = queue.EnqueueObservableOperation(1, "slow", cancel, () => Expensive().ToObservable());
+cancel.OnNext(Unit.Default); // cancels if not yet running or in-flight
+```
+
+## Pause and resume
+
+```csharp
+var gate = queue.PauseQueue();
+// enqueue work while paused; nothing executes yet
+// ...
+gate.Dispose(); // resumes and drains respecting priority/keys
+```
+
+## Adjust concurrency at runtime
+
+```csharp
+queue.SetMaximumConcurrent(8); // increases throughput
+```
+
+## Shutting down
+
+```csharp
+await queue.ShutdownQueue(); // completes when outstanding work finishes
+```
 
-```cs
-// This file is super important, we don't care if it cuts in line in front
-// of some images or other stuff
-var wc = new WebClient();
-await opQueue.Enqueue(10 /* It's Important */, 
-    () => wc.DownloadFileTaskAsync("http://example.com/cool.txt", "./cool.txt"));
+## API overview
+
+- OperationQueue
+  - ctor(int maximumConcurrent = 4)
+  - IObservable<T> EnqueueObservableOperation<T>(int priority, Func<IObservable<T>>)
+  - IObservable<T> EnqueueObservableOperation<T>(int priority, string key, Func<IObservable<T>>)
+  - IObservable<T> EnqueueObservableOperation<T, TDontCare>(int priority, string key, IObservable<TDontCare> cancel, Func<IObservable<T>>)
+  - IDisposable PauseQueue()
+  - void SetMaximumConcurrent(int maximumConcurrent)
+  - IObservable<Unit> ShutdownQueue()
+
+- OperationQueueExtensions
+  - Task Enqueue(int priority, Func<Task>)
+  - Task<T> Enqueue<T>(int priority, Func<Task<T>>)
+  - Task Enqueue(int priority, string key, Func<Task>)
+  - Task<T> Enqueue<T>(int priority, string key, Func<Task<T>>)
+  - Overloads with CancellationToken for all of the above
+
+## Best practices
+
+- Prefer Task-based Enqueue APIs in application code; use observable APIs when composing with Rx.
+- Use descriptive keys for shared resources (e.g., "user:{id}", "file:{path}").
+- Keep operations idempotent and short; long operations block concurrency slots.
+- Use higher priorities sparingly; they jump the queue when a slot opens.
+- PauseQueue is ref-counted; always dispose the returned handle exactly once.
+- For cancellation via token, reuse CTS per user action to cancel pending work quickly.
+
+## Advanced notes
+
+- Unkeyed work is prioritized ahead of keyed work internally to keep the pipeline flowing; keys are serialized per group.
+- The semaphore releases when an operation completes, errors, or is canceled.
+- Cancellation before evaluation prevents invoking the supplied function.
+
+## Full examples
+
+- Image downloader with keys and priorities
+
+```csharp
+var queue = new OperationQueue(3);
+
+Task Download(string url, string dest, int pri, string key) =>
+    queue.Enqueue(pri, key, async () =>
+    {
+        using var http = new HttpClient();
+        var bytes = await http.GetByteArrayAsync(url);
+        await File.WriteAllBytesAsync(dest, bytes);
+    });
+
+var tasks = new[]
+{
+    Download("https://example.com/a.jpg", "a.jpg", 1, "img"),
+    Download("https://example.com/b.jpg", "b.jpg", 1, "img"),
+    queue.Enqueue(5, () => Task.Delay(100)), // higher priority misc work
+};
+await Task.WhenAll(tasks);
 ```
 
-## What else can this library do
+## Troubleshooting
 
-* Cancellation via CancellationTokens or via Observables
-* Ensure certain operations don't run concurrently via a key
-* Queue pause / resume
+- Nothing runs? Ensure you didn't leave the queue paused. Dispose the token from PauseQueue.
+- Starvation? Check if you assigned very high priorities to long-running tasks.
+- Deadlock-like behavior with keys? Remember keyed operations are strictly serialized; avoid long critical sections.
 
 ## Contribute
 
 Punchclock is developed under an OSI-approved open source license, making it freely usable and distributable, even for commercial use. Because of our Open Collective model for funding and transparency, we are able to funnel support and funds through to our contributors and community. We ❤ the people who are involved in this project, and we’d love to have you on board, especially if you are just getting started or have never contributed to open-source before.
 
 So here's to you, lovely person who wants to join us — this is how you can support us:
 
-* [Responding to questions on StackOverflow](https://stackoverflow.com/questions/tagged/punchclock)
-* [Passing on knowledge and teaching the next generation of developers](https://ericsink.com/entries/dont_use_rxui.html)
-* Submitting documentation updates where you see fit or lacking.
-* Making contributions to the code base.
+- [Responding to questions on StackOverflow](https://stackoverflow.com/questions/tagged/punchclock)
+- [Passing on knowledge and teaching the next generation of developers](https://ericsink.com/entries/dont_use_rxui.html)
+- Submitting documentation updates where you see fit or lacking.
+- Making contributions to the code base.

src/Punchclock.Tests/Punchclock.Tests.csproj

@@ -6,9 +6,8 @@
 
 	<ItemGroup>
 		<PackageReference Include="DynamicData" Version="9.4.1" />
-		<PackageReference Include="splat" Version="15.*" />
 		<PackageReference Include="PublicApiGenerator" Version="11.4.6" />
-		<PackageReference Include="Verify.Xunit" Version="30.7.3" />
+		<PackageReference Include="Verify.Xunit" Version="30.10.0" />
 		<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
 		<PackageReference Include="xunit" Version="2.9.3" />
 		<PackageReference Include="xunit.runner.console" Version="2.9.3" />

src/Punchclock.sln

@@ -1,5 +1,5 @@
 Microsoft Visual Studio Solution File, Format Version 12.00
-# 17
+# Visual Studio Version 17
 VisualStudioVersion = 17.3.32922.545
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Punchclock", "Punchclock\Punchclock.csproj", "{D3D5E08E-2DAA-4C14-BDF1-C15BD81247F5}"
@@ -11,6 +11,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Items", "Items", "{E035091F
 		analyzers.ruleset = analyzers.ruleset
 		analyzers.tests.ruleset = analyzers.tests.ruleset
 		Directory.build.props = Directory.build.props
+		..\LICENSE = ..\LICENSE
 		..\README.md = ..\README.md
 		stylecop.json = stylecop.json
 		..\version.json = ..\version.json

src/Punchclock/KeyedOperation.cs

@@ -34,7 +34,8 @@ public int CompareTo(KeyedOperation other)
         // up concurrency slots
         if (KeyIsDefault != other.KeyIsDefault)
         {
-            return KeyIsDefault ? 1 : -1;
+            // If this is non-keyed (default), it should sort before keyed -> return -1
+            return KeyIsDefault ? -1 : 1;
         }
 
         return other.Priority.CompareTo(Priority);

src/Punchclock/OperationQueue.cs

@@ -15,19 +15,23 @@
 namespace Punchclock;
 
 /// <summary>
+/// <para>
 /// OperationQueue is the core of PunchClock, and represents a scheduler for
 /// deferred actions, such as network requests. This scheduler supports
 /// scheduling via priorities, as well as serializing requests that access
 /// the same data.
-///
+/// </para>
+/// <para>
 /// The queue allows a fixed number of concurrent in-flight operations at a
 /// time. When there are available "slots", items are dispatched as they come
 /// in. When the slots are full, the queueing policy starts to apply.
-///
+/// </para>
+/// <para>
 /// The queue, similar to Akavache's KeyedOperationQueue, also allows keys to
 /// be specified to serialize operations - if you have three "foo" items, they
 /// will wait in line and only one "foo" can run. However, a "bar" and "baz"
 /// item can run at the same time as a "foo" item.
+/// </para>
 /// </summary>
 public class OperationQueue : IDisposable
 {

src/Punchclock/OperationQueueExtensions.cs

@@ -5,8 +5,8 @@
 
 using System;
 using System.Reactive;
+using System.Reactive.Disposables;
 using System.Reactive.Linq;
-using System.Reactive.Subjects;
 using System.Reactive.Threading.Tasks;
 using System.Threading;
 using System.Threading.Tasks;
@@ -135,20 +135,19 @@ public static Task Enqueue(this OperationQueue operationQueue, int priority, Fun
             .ToTask();
     }
 
-    private static IObservable<Unit> ConvertTokenToObservable(CancellationToken token)
-    {
-        var cancel = new AsyncSubject<Unit>();
-
-        if (token.IsCancellationRequested)
-        {
-            return Observable.Throw<Unit>(new ArgumentException("Token is already cancelled"));
-        }
-
-        token.Register(() =>
+    private static IObservable<Unit> ConvertTokenToObservable(CancellationToken token) =>
+        Observable.Create<Unit>(observer =>
         {
-            cancel.OnNext(Unit.Default);
-            cancel.OnCompleted();
+            if (token.IsCancellationRequested)
+            {
+                observer.OnError(new ArgumentException("Token is already cancelled", nameof(token)));
+                return Disposable.Empty;
+            }
+
+            return token.Register(() =>
+            {
+                observer.OnNext(Unit.Default);
+                observer.OnCompleted();
+            });
         });
-        return cancel;
-    }
 }

src/Punchclock/Punchclock.csproj

@@ -7,7 +7,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="System.Reactive" Version="6.0.1" />
+    <PackageReference Include="System.Reactive" Version="6.0.2" />
   </ItemGroup>
 
 </Project>