JavaScriptEventLoop: Add opt-in yieldInterval for host responsiveness

Author: krodak

Sources/JavaScriptEventLoop/JavaScriptEventLoop+YieldInterval.swift

@@ -0,0 +1,110 @@
+// Support for `JavaScriptEventLoop.yieldInterval`: a clock that measures how long one drain of the
+// job queue has run, and a scheduler that continues the drain in a new JavaScript task.
+
+import JavaScriptKit
+import _Concurrency
+
+#if compiler(>=5.5)
+
+@available(macOS 14.0, iOS 17.0, watchOS 10.0, tvOS 17.0, *)
+extension JavaScriptEventLoop {
+
+    #if hasFeature(Embedded)
+    /// A point in time for measuring a drain of the job queue, in milliseconds of `performance.now()`.
+    typealias DrainInstant = Double
+
+    // `ContinuousClock` is unavailable in Embedded Swift, so use the JavaScript clock.
+    func drainClockNow() -> DrainInstant {
+        if performanceNow == nil {
+            let performance = JSObject.global.performance.object!
+            performanceNow = (performance, performance.now.function!)
+        }
+        return performanceNow!.now(this: performanceNow!.performance).number!
+    }
+
+    func hasRun(since start: DrainInstant, for interval: Duration) -> Bool {
+        let (seconds, attoseconds) = interval.components
+        let intervalMilliseconds = Double(seconds) * 1_000 + Double(attoseconds) / 1_000_000_000_000_000
+        return drainClockNow() - start >= intervalMilliseconds
+    }
+    #else
+    /// A point in time for measuring a drain of the job queue.
+    typealias DrainInstant = ContinuousClock.Instant
+
+    func drainClockNow() -> DrainInstant {
+        ContinuousClock.now
+    }
+
+    func hasRun(since start: DrainInstant, for interval: Duration) -> Bool {
+        start.duration(to: .now) >= interval
+    }
+    #endif
+
+    /// Runs `body` in a new JavaScript task, after the JavaScript event loop had a chance to run
+    /// other tasks. Uses `setImmediate` where available (Node.js, Bun), else a `MessageChannel`
+    /// message (browsers, Web Workers, Deno), else `setTimeout(body, 0)`.
+    func queueHostTask(_ body: @escaping () -> Void) {
+        if hostTaskScheduler == nil {
+            hostTaskScheduler = Self.makeHostTaskScheduler()
+        }
+        hostTaskScheduler!(body)
+    }
+
+    private static func makeHostTaskScheduler() -> (@escaping () -> Void) -> Void {
+        let global = JSObject.global
+        if let setImmediate = global.setImmediate.function {
+            return { body in
+                _ = setImmediate(
+                    JSOneshotClosure { _ in
+                        body()
+                        return .undefined
+                    }
+                )
+            }
+        }
+        if let messageChannel = global.MessageChannel.function {
+            // Unlike `setTimeout`, a message is not clamped to 4 ms when timers nest.
+            let channel = messageChannel.new(arguments: [JSValue]())
+            let sender = channel.port1.object!
+            let postMessage = sender.postMessage.function!
+            let pending = PendingHostTasks()
+            let receiver = JSClosure { _ in
+                pending.runAll()
+                return .undefined
+            }
+            channel.port2.object!.onmessage = .object(receiver)
+            return { body in
+                pending.bodies.append(body)
+                // The scheduler owns `receiver`, which the channel calls.
+                withExtendedLifetime(receiver) {
+                    _ = postMessage(this: sender, JSValue.undefined)
+                }
+            }
+        }
+        let setTimeout = global.setTimeout.function!
+        return { body in
+            _ = setTimeout(
+                JSOneshotClosure { _ in
+                    body()
+                    return .undefined
+                },
+                0
+            )
+        }
+    }
+}
+
+/// Bodies that wait for the `MessageChannel` message of `JavaScriptEventLoop.queueHostTask(_:)`.
+private final class PendingHostTasks {
+    var bodies: [() -> Void] = []
+
+    func runAll() {
+        let bodies = self.bodies
+        self.bodies = []
+        for body in bodies {
+            body()
+        }
+    }
+}
+
+#endif

Sources/JavaScriptEventLoop/JavaScriptEventLoop.swift

@@ -48,6 +48,45 @@ public final class JavaScriptEventLoop: SerialExecutor, @unchecked Sendable {
     /// A function that invokes a given closure after a specified number of milliseconds.
     public var setTimeout: (Double, @escaping () -> Void) -> Void
 
+    /// The longest time that this event loop runs queued Swift jobs before it lets the JavaScript
+    /// event loop run other tasks, such as rendering, input events, timers and messages.
+    ///
+    /// By default (`nil`), the event loop runs every queued job in one microtask, including jobs
+    /// that those jobs enqueue. A long chain of Swift async work then blocks the JavaScript event
+    /// loop until the chain is done. `Task.yield()` does not help, because the yielded task runs
+    /// again in the same microtask.
+    ///
+    /// When you set an interval, the event loop checks the time after each job. When the interval
+    /// has passed and more jobs are queued, it runs the remaining jobs in a new JavaScript task
+    /// (with `setImmediate`, a `MessageChannel` message or `setTimeout`, whichever is available).
+    /// Jobs that are enqueued in the meantime run in that task, in priority order. A job is never
+    /// interrupted, so a single job that runs longer than the interval still blocks the JavaScript
+    /// event loop for its whole duration.
+    ///
+    /// ```swift
+    /// JavaScriptEventLoop.installGlobalExecutor()
+    /// JavaScriptEventLoop.shared.yieldInterval = .milliseconds(16)
+    /// ```
+    ///
+    /// An interval trades latency for responsiveness. A job that is ready can wait while the
+    /// JavaScript event loop runs other tasks, and JavaScript code can run between any two Swift
+    /// jobs, not only while Swift code awaits JavaScript. A change takes effect after the current
+    /// job. Delayed jobs, such as the ones of `Task.sleep`, are not affected.
+    ///
+    /// In a multi-threaded environment, each thread has its own event loop. Set the interval on
+    /// ``shared`` on the thread that it applies to.
+    public var yieldInterval: Duration?
+
+    /// Schedules the rest of a drain of the job queue that stopped at ``yieldInterval``.
+    /// Created on first use.
+    var hostTaskScheduler: ((@escaping () -> Void) -> Void)?
+
+    #if hasFeature(Embedded)
+    /// `performance` and its `now` method. ``yieldInterval`` uses them to measure time where
+    /// `ContinuousClock` is unavailable. Created on first use.
+    var performanceNow: (performance: JSObject, now: JSFunction)?
+    #endif
+
     /// A mutable state to manage internal job queue
     /// Note that this should be guarded atomically when supporting multi-threaded environment.
     var queueState = QueueState()

Sources/JavaScriptEventLoop/JobQueue.swift

@@ -43,12 +43,29 @@ extension JavaScriptEventLoop {
     func runAllJobs() {
         assert(queueState.isSpinning)
 
+        // The clock is read only while `yieldInterval` is set. A job can set it during this
+        // drain; the time then counts from that job.
+        var start: DrainInstant? = yieldInterval == nil ? nil : drainClockNow()
         while let job = self.claimNextFromQueue() {
             #if compiler(>=5.9)
             job.runSynchronously(on: self.asUnownedSerialExecutor())
             #else
             job._runSynchronously(on: self.asUnownedSerialExecutor())
             #endif
+
+            if let yieldInterval, queueState.headJob != nil {
+                if let start {
+                    if hasRun(since: start, for: yieldInterval) {
+                        // Run the rest in a new JavaScript task. `isSpinning` stays true until
+                        // then, so jobs that are enqueued in between join the queue and do not
+                        // start another drain.
+                        queueHostTask { self.runAllJobs() }
+                        return
+                    }
+                } else {
+                    start = drainClockNow()
+                }
+            }
         }
 
         queueState.isSpinning = false

Sources/JavaScriptKit/Documentation.docc/Articles/JavaScript-Interop-Cheat-Sheet.md

@@ -373,4 +373,5 @@ let swiftPromise = JSPromise.async {
 - Use `JSPromise.async(body:)` (with `Void` or `JSValue` return type) to expose Swift `async/await` work to JavaScript callers.
 - To await JavaScript `Promise` from Swift, import `JavaScriptEventLoop`, call `JavaScriptEventLoop.installGlobalExecutor()` early, and use the `value` property.
 - The `value` property suspends until the promise resolves or rejects, rethrowing rejections as ``JSException``.
+- By default, Swift async work that is ready to run keeps running in one JavaScript task, so a long chain of jobs blocks rendering and input until it ends. Set `JavaScriptEventLoop.shared.yieldInterval` (for example, `.milliseconds(16)`) to let the JavaScript event loop run other tasks between Swift jobs.
 

Tests/JavaScriptEventLoopTests/JavaScriptEventLoopYieldIntervalTests.swift

@@ -0,0 +1,81 @@
+import JavaScriptEventLoop
+import JavaScriptKit
+import XCTest
+
+final class JavaScriptEventLoopYieldIntervalTests: XCTestCase {
+    final class Box<Value>: @unchecked Sendable {
+        var value: Value
+        init(_ value: Value) { self.value = value }
+    }
+
+    override func tearDown() {
+        JavaScriptEventLoop.shared.yieldInterval = nil
+        super.tearDown()
+    }
+
+    /// Spins for `milliseconds` without suspending.
+    static func busyWait(milliseconds: Int) {
+        let end = ContinuousClock.now + .milliseconds(milliseconds)
+        while ContinuousClock.now < end {}
+    }
+
+    /// Schedules a JavaScript timer, then runs `count` Swift tasks that each spin for
+    /// `milliseconds`. Returns, for each task in order, whether the timer had run when the task ended.
+    func timerRanAfterEachTask(count: Int, milliseconds: Int) async -> [Bool] {
+        let timerRan = Box(false)
+        _ = JSObject.global.setTimeout!(
+            JSOneshotClosure { _ in
+                timerRan.value = true
+                return .undefined
+            },
+            0
+        )
+        let observed = Box([Bool]())
+        let tasks = (0..<count).map { _ in
+            Task {
+                Self.busyWait(milliseconds: milliseconds)
+                observed.value.append(timerRan.value)
+            }
+        }
+        for task in tasks { await task.value }
+        return observed.value
+    }
+
+    func testYieldIntervalIsNilByDefault() {
+        XCTAssertNil(JavaScriptEventLoop.shared.yieldInterval)
+    }
+
+    func testJobsRunInOneDrainWithoutYieldInterval() async {
+        let observed = await timerRanAfterEachTask(count: 20, milliseconds: 2)
+        XCTAssertEqual(observed, Array(repeating: false, count: 20))
+    }
+
+    func testJavaScriptTasksRunBetweenJobsWithYieldInterval() async {
+        JavaScriptEventLoop.shared.yieldInterval = .milliseconds(5)
+        let observed = await timerRanAfterEachTask(count: 20, milliseconds: 2)
+        XCTAssertEqual(observed.first, false)
+        XCTAssertEqual(observed.last, true)
+    }
+
+    func testYieldIntervalAppliesToALaterDrain() async throws {
+        JavaScriptEventLoop.shared.yieldInterval = .milliseconds(5)
+        // End the current drain, so the work below runs in a new one.
+        try await Task.sleep(nanoseconds: 1_000_000)
+        let observed = await timerRanAfterEachTask(count: 20, milliseconds: 2)
+        XCTAssertEqual(observed.first, false)
+        XCTAssertEqual(observed.last, true)
+    }
+
+    func testJobsKeepTheirOrderAcrossYields() async {
+        JavaScriptEventLoop.shared.yieldInterval = .milliseconds(1)
+        let order = Box([Int]())
+        let tasks = (0..<20).map { index in
+            Task {
+                Self.busyWait(milliseconds: 1)
+                order.value.append(index)
+            }
+        }
+        for task in tasks { await task.value }
+        XCTAssertEqual(order.value, Array(0..<20))
+    }
+}