Implement AsyncTrigger

`AsyncTrigger` is intended for suspending asynchronous tasks that should proceed only after a one-time resuming event.

Author: erikbasargin

Package.swift

@@ -21,6 +21,9 @@ let package = Package(
         .target(
             name: "AsyncMaterializedSequence"
         ),
+        .target(
+            name: "AsyncTrigger"
+        ),
         .target(
             name: "TestingSupport",
             dependencies: [
@@ -40,6 +43,13 @@ let package = Package(
                 "TestingSupport",
             ]
         ),
+        .testTarget(
+            name: "AsyncTriggerTests",
+            dependencies: [
+                "AsyncTrigger",
+                "TestingSupport",
+            ]
+        ),
         .testTarget(
             name: "TestingSupportTests",
             dependencies: [

Sources/AsyncTrigger/AsyncTrigger.swift

@@ -0,0 +1,89 @@
+import AsyncAlgorithms
+
+/// `AsyncTrigger` is intended for suspending asynchronous tasks that should proceed only after a one-time resuming event.
+///
+/// ### Usage
+///
+/// ```swift
+/// let trigger = AsyncTrigger()
+///
+/// // These tasks will suspend until the trigger is fired.
+/// let task1 = Task {
+///     await trigger()
+/// }
+/// let task2 = Task {
+///     await trigger()
+/// }
+///
+/// trigger.fire() // Resumes all awaiting tasks
+///
+/// let result1 = await task1.value // .triggered
+/// let result2 = await task2.value // .triggered
+/// ```
+///
+/// If a task is cancelled before the trigger fires, it returns `.cancelled`:
+/// ```swift
+/// let trigger = AsyncTrigger()
+/// let task = Task {
+///     await trigger()
+/// }
+/// task.cancel()
+/// let result = await task.value // .cancelled
+/// ```
+///
+/// `AsyncTrigger` can also be used as an `AsyncSequence`:
+/// ```swift
+/// let trigger = AsyncTrigger()
+/// async let result = trigger.reduce(into: [], { $0.append($1) })
+/// trigger.fire()
+/// let output = await result // [.triggered]
+/// ```
+@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
+public struct AsyncTrigger: Sendable {
+    
+    public enum Result: Sendable, Equatable {
+        case triggered
+        case cancelled
+    }
+
+    private let channel = AsyncChannel<Never>()
+
+    public init() {}
+
+    /// Immediately resumes all the suspended operations.
+    public func fire() {
+        channel.finish()
+    }
+
+    @discardableResult
+    public func callAsFunction() async -> Result {
+        var iterator = makeAsyncIterator()
+        // Although next() can return nil, AsyncTrigger.Iterator guarantees that the first value cannot be nil.
+        return await iterator.next()!
+    }
+}
+
+@available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
+extension AsyncTrigger: AsyncSequence {
+    
+    public struct Iterator: AsyncIteratorProtocol {
+        
+        var base: AsyncChannel<Never>.AsyncIterator
+        var hasFired: Bool = false
+        
+        public mutating func next() async -> AsyncTrigger.Result? {
+            guard !hasFired else { return nil }
+            
+            _ = await base.next()
+            hasFired = true
+            return Task.isCancelled ? .cancelled : .triggered
+        }
+    }
+    
+    public func makeAsyncIterator() -> Iterator {
+        Iterator(base: channel.makeAsyncIterator())
+    }
+}
+
+@available(*, unavailable)
+extension AsyncTrigger.Iterator: Sendable {}

Tests/AsyncTriggerTests/AsyncTriggerTests.swift

@@ -0,0 +1,45 @@
+import AsyncTrigger
+import Testing
+import TestingSupport
+
+struct AsyncTriggerTests {
+    
+    @Test func trigger_resumes_consumers_when_fire_is_called() async throws {
+        let trigger = AsyncTrigger()
+        
+        async let work1 = trigger()
+        async let work2 = trigger()
+        
+        trigger.fire()
+        
+        await #expect((work1, work2) == (.triggered, .triggered))
+    }
+    
+    @Test func trigger_resumes_consumers_immediately_given_trigger_is_fired() async throws {
+        let trigger = AsyncTrigger()
+        trigger.fire()
+        
+        async let work1 = trigger()
+        async let work2 = trigger()
+        
+        await #expect((work1, work2) == (.triggered, .triggered))
+    }
+    
+    @Test func trigger_consumer_resumes_when_task_is_cancelled() async throws {
+        let trigger = AsyncTrigger()
+        let work = Task(operation: trigger.callAsFunction)
+        
+        work.cancel()
+        
+        await #expect(work.value == .cancelled)
+    }
+    
+    @Test func trigger_is_async_sequence() async throws {
+        let trigger = AsyncTrigger()
+        async let work = trigger.reduce(into: [], { $0.append($1) })
+        
+        trigger.fire()
+        
+        await #expect(work == [.triggered])
+    }
+}