Add a synthetic test for metal failing to render a frame

Author: migueldeicaza

Sources/SwiftTerm/Apple/Metal/MetalTerminalRenderer.swift

@@ -302,6 +302,16 @@ final class MetalTerminalRenderer: NSObject, MTKViewDelegate {
         self.sampler = sampler
         self.terminalView = terminalView
         super.init()
+#if DEBUG
+        // This fault models a command buffer that does not release the frame
+        // permit. Every draw then uses the real semaphore refusal path.
+        if ProcessInfo.processInfo.environment["SWIFTTERM_TEST_METAL_FRAME_PERMIT_HELD"] == "1" {
+            _ = frameSemaphore.wait(timeout: .now())
+            // A real command buffer retains this semaphore in its completion
+            // handler. Keep the same lifetime when this fault is active.
+            _ = Unmanaged.passRetained(frameSemaphore)
+        }
+#endif
     }
 
     deinit {

Tools/RenderBench/README.md

@@ -0,0 +1,29 @@
+# RenderBench
+
+RenderBench puts a real SwiftTerm terminal view in a macOS window. It feeds
+deterministic terminal data without a shell or a PTY.
+
+## Reproduce a stalled Metal renderer
+
+Run this command:
+
+```sh
+cd Tools/RenderBench
+swift run RenderBench --scenario stalled-frame --seconds 10
+```
+
+The scenario uses a debug-only fault. It holds the Metal frame permit before
+the first draw. This state models a command buffer whose completion handler did
+not release the permit.
+
+The terminal model continues to accept dense, colored output. Each output
+update requests a display. Each draw enters the semaphore refusal path and
+returns before it creates a command buffer. The pane stays black because no
+completion handler can consume `pendingRedraw`.
+
+The process prints the number of accepted updates. The window must remain black
+for the full run. A renderer fix must let a later draw present the colored
+terminal data without a call to `setUseMetal(false)` and `setUseMetal(true)`.
+
+The `stalled-frame` scenario requires a debug build. Other scenarios also
+support release builds.

Tools/RenderBench/Sources/RenderBench/main.swift

@@ -7,14 +7,18 @@
 //  byte-identical input and their profiles are directly comparable.
 //
 //  Usage:
-//    RenderBench [--metal] [--seconds N] [--scenario dense|medium|scroll|arabic|arabic-line]
+//    RenderBench [--metal] [--seconds N]
+//                [--scenario dense|medium|scroll|arabic|arabic-line|stalled-frame]
 //
 //  Scenarios:
 //    dense   every cell gets its own truecolor foreground and background
 //            (vtebench dense_cells shape: many one-cell attribute runs)
 //    medium  a color change every 8 cells (longer runs, fewer segments)
 //    scroll  plain ASCII lines that scroll the screen
 //    arabic  scrolling Arabic words (exercises the BiDi shaping path)
+//    stalled-frame
+//            hold the Metal frame permit before the first draw, then feed
+//            terminal output. The pane stays black while the model changes.
 //
 //  Profile it with Instruments:
 //    swift build -c release
@@ -40,15 +44,26 @@ while let argument = argIterator.next() {
     case "--scenario":
         scenario = argIterator.next() ?? scenario
     default:
-        print("usage: RenderBench [--metal] [--seconds N] [--scenario dense|medium|scroll|arabic|arabic-line]")
+        print("usage: RenderBench [--metal] [--seconds N] " +
+              "[--scenario dense|medium|scroll|arabic|arabic-line|stalled-frame]")
         exit(1)
     }
 }
-guard ["dense", "medium", "scroll", "arabic", "arabic-line"].contains(scenario) else {
+guard ["dense", "medium", "scroll", "arabic", "arabic-line", "stalled-frame"].contains(scenario) else {
     print("unknown scenario: \(scenario)")
     exit(1)
 }
 
+if scenario == "stalled-frame" {
+#if DEBUG
+    useMetal = true
+    setenv("SWIFTTERM_TEST_METAL_FRAME_PERMIT_HELD", "1", 1)
+#else
+    print("stalled-frame requires a debug build")
+    exit(1)
+#endif
+}
+
 /// Deterministic generator so every run feeds identical bytes.
 struct SplitMix64 {
     var state: UInt64
@@ -96,6 +111,8 @@ final class FrameSource {
             return scrollChunk(cols: cols, rows: rows)
         case "arabic-line":
             return arabicLine()
+        case "stalled-frame":
+            return coloredFrame(cols: cols, rows: rows, runLength: 1)
         default:
             return arabicChunk(rows: rows)
         }
@@ -183,6 +200,10 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         window.title = "RenderBench: \(scenario)\(useMetal ? " (Metal)" : " (CG)")"
         terminalView = TerminalView(frame: window.contentView!.bounds)
         terminalView.terminalDelegate = terminalViewDelegate
+        window.contentView!.addSubview(terminalView)
+        window.makeKeyAndOrderFront(nil)
+        NSApp.activate(ignoringOtherApps: true)
+
         if useMetal {
             do {
                 try terminalView.setUseMetal(true)
@@ -191,13 +212,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
                 exit(1)
             }
         }
-        window.contentView!.addSubview(terminalView)
-        window.makeKeyAndOrderFront(nil)
-        NSApp.activate(ignoringOtherApps: true)
 
         let t = terminalView.getTerminal()
         print("renderer=\(useMetal ? "metal" : "cg") scenario=\(scenario) " +
               "cols=\(t.cols) rows=\(t.rows) seconds=\(seconds)")
+        if scenario == "stalled-frame" {
+            print("FAULT ACTIVE: the Metal frame permit is held before the first draw.")
+            print("EXPECTED: the pane stays black while the terminal accepts synthetic output.")
+        }
         startTime = CFAbsoluteTimeGetCurrent()
         DispatchQueue.main.async { self.tick() }
     }
@@ -220,6 +242,10 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         }
         if elapsed >= seconds {
             report(elapsed: elapsed, prefix: "TOTAL")
+            if scenario == "stalled-frame" {
+                print("REPRODUCED: the terminal accepted \(frameCount) updates, " +
+                      "but every Metal draw was refused.")
+            }
             exit(0)
         }
         DispatchQueue.main.async { self.tick() }