Add README and inline documentation for AsyncCoalescingQueue

Author: dannys42

README.md

@@ -6,11 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 
-AsyncSerialQueue is a simple library to provide [serial queue](https://www.avanderlee.com/swift/concurrent-serial-dispatchqueue/)-like capability using [Swift Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/).  Tasks placed in an AsyncSerialQueue are guaranteed to execute sequentially.
+`AsyncSerialQueue` is a library provides some useful patterns using Swift Concurrency:
+
+`AsyncSerialQueue` is a class provides [serial queue](https://www.avanderlee.com/swift/concurrent-serial-dispatchqueue/)-like capability using [Swift Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/).  Tasks placed in an `AsyncSerialQueue` are guaranteed to execute sequentially.
+
+`AsyncCoalescingQueue` is a companion class that has properties similar to [DispatchSource](https://www.mikeash.com/pyblog/friday-qa-2009-09-11-intro-to-grand-central-dispatch-part-iii-dispatch-sources.html).
 
 AsyncSerialQueue is currently only available on Apple platforms (i.e. not on Linux).  This is because of the need for locking and Swift [currently does not have a standard cross-platform locking mechnism](https://forums.swift.org/t/shared-mutable-state-sendable-and-locks/64336).
 
 
+# `AsyncSerialQueue`
+
 ## Example
 
 ### Simple Example
@@ -100,3 +106,42 @@ func example() async {
 
 In this case, `apple` will never appear before `2`.  And `example()` will not return until `2` is printed.
 
+
+# `AsyncCoalescingQueue`
+
+## Example
+
+The following code:
+
+```swift
+let coalescingQueue = AsyncCoalescingQueue()
+
+coalescingQueue.run {
+    try? await Task.sleep(for: .seconds(5))
+    print("Run 1")
+}
+coalescingQueue.run {
+    try? await Task.sleep(for: .seconds(5))
+    print("Run 2")
+}
+coalescingQueue.run {
+    try? await Task.sleep(for: .seconds(5))
+    print("Run 3")
+}
+coalescingQueue.run {
+    try? await Task.sleep(for: .seconds(5))
+    print("Run 4")
+}
+coalescingQueue.run {
+    try? await Task.sleep(for: .seconds(5))
+    print("Run 5")
+}
+```
+Will output the following:
+
+```
+Run 1
+Run 5
+```
+
+And take 10 seconds to complete executing.

Sources/AsyncSerialQueue/AsyncCoalescingQueue.swift

@@ -8,22 +8,42 @@
 import Foundation
 import os
 
-/// Provides behavior similar to DispatchSource using Swift Concurrency
+/// ``AsyncCoalescingQueue`` provides behavior similar to DispatchSource using Swift Concurrency
+/// When the queue is idle, the first task queued is guaranteed to run.  Subsequent tasks will only execute when the queue is idle.  If more the one task is pending execution, only the last one will execute.
+///
+/// For example, if executing:
+/// ```swift
+///   let coalescingQueue = AsyncCoalescingQueue()
+///   coalescingQueue.run { await slowFunction(1) }
+///   coalescingQueue.run { await slowFunction(2) }
+///   coalescingQueue.run { await slowFunction(3) }
+///   coalescingQueue.run { await slowFunction(4) }
+/// ```
+/// This is equivalent to:
+/// ```swift
+///     await slowFunction(1)
+///     await slowFunction(4)
+/// ```
 public class AsyncCoalescingQueue: @unchecked Sendable {
     public let label: String?
     private let serialQueue: AsyncSerialQueue
 
     private let taskList = TaskList()
     private let priority: TaskPriority?
 
+    /// Initialize a new ``AsyncCoalescingQueue`` instance
+    /// - Parameters:
+    ///   - label: An optional string that can be used to identify the queue
+    ///   - priority: Optional ``TaskPriority`` used when executing tasks
     public init(label: String? = nil, priority: TaskPriority? = nil) {
         self.label = label
         self.priority = priority
         self.serialQueue = AsyncSerialQueue(label: label, priority: priority)
     }
-    
+
     /// Attempt to execute a given block.
-    /// Will not attempt to execute more than 2 in-flight blocks.
+    /// The block will not be executed if a new block is queued before it runs.
+    /// Subsequent blocks are guaranteed to not run at the same time.
     /// - Parameter block: block to execute
     public func run(_ block: @escaping () async -> Void) {
         self.serialQueue.async {
@@ -34,6 +54,7 @@ public class AsyncCoalescingQueue: @unchecked Sendable {
         }
     }
 
+    /// Wait for all pending blocks to execute.
     public func wait() async {
         await self.serialQueue.sync {
             while await self.taskList.isEmpty == false {
@@ -42,14 +63,18 @@ public class AsyncCoalescingQueue: @unchecked Sendable {
             }
         }
     }
+}
+
+// MARK: - Private
+fileprivate extension AsyncCoalescingQueue {
 
-    private func triggerProcessNextTask() {
+    func triggerProcessNextTask() {
         Task(priority: self.priority) {
             await self.processNextTask()
         }
     }
 
-    private func processNextTask() async {
+    func processNextTask() async {
         if await self.taskList.isAnyTaskRunning {
             return
         }
@@ -62,7 +87,7 @@ public class AsyncCoalescingQueue: @unchecked Sendable {
         case .running:
             break
         case .waiting:
-            Task {
+            Task(priority: self.priority) {
                 await task.run()
 
                 await self.processNextTask()