KMP Skiko Metal/Vulkan Frame Pacing and Mutex Synchronization Standard

--- description: KMP Skiko Metal/Vulkan Frame Pacing and Mutex Synchronization Standard - Enforces strict isolation between native frame-pacing mechanisms (CADisplayLink/Choreographer) and Skiko rendering mutexes in Compose Multiplatform. Prevents main-thread priority inversion and deadlocks by prohibiting synchronous waits on GPU drawables or command buffer completion inside lock-holding native vsync callbacks. globs: **/*.ios.kt, **/*.skiko.kt, iosApp/**/*.swift, iosApp/**/*.{m,mm}, **/graphics/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skiko-metal-vulkan-frame-pacing-mutex-standard" --- # KMP Skiko Metal/Vulkan Frame Pacing and Mutex Synchronization Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronously blocking CADisplayLink or Main RunLoop on Skiko Render Mutexes and GPU Surface Acquisition ## System Constraints You are a Principal Graphics and Concurrency Engineer enforcing Skiko, Metal, and Vulkan frame-pacing invariants in Compose Multiplatform. You mandate zero blocking waits on native display-link threads, non-reentrant graphics mutex decoupling, and lockless vsync state signaling to prevent UI deadlocks and frame stutter. ## Strict Guidelines - Engineers MUST NEVER acquire Skiko rendering mutexes synchronously inside the CADisplayLink or Choreographer callback on the main thread. - Engineers MUST decouple display vsync triggers from command buffer execution using bounded ring-buffers or atomic swap-chains with a maximum backpressure depth of 2 frames. - Code MUST NEVER perform synchronous CAMetalDrawable acquisition (nextDrawable()) while holding an application-level state or layout lock. - Services MUST dispatch Skiko render passes to a dedicated, high-priority serial rendering queue rather than executing raw OpenGL/Metal/Vulkan pipeline dispatches on the main thread dispatch queue. - Components NEVER block thread execution waiting on MTLCommandBuffer.waitUntilCompleted() or VkQueueWaitIdle() within any thread servicing user interactions or native UI event loops. ## Bad vs Good Implementations ### Decoupling CADisplayLink VSync from Skiko Metal Surface Render Loop #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing GPU commands synchronously on the main thread within CADisplayLink holding an NSLock causes severe frame dropping. Calling waitUntilCompleted() freezes the main runloop until the GPU pipeline finishes, creating priority inversions and potential deadlocks with UIKit/AppKit. ```kotlin // BAD: CADisplayLink callback synchronously claims Skiko mutex and blocks on Metal drawable class SkikoMetalFrameRenderer(private val layer: CAMetalLayer) { private val renderLock = NSLock() @ObjCAction fun onDisplayLinkStep() { renderLock.lock() // Blocks Main RunLoop if background pass is in progress val drawable = layer.nextDrawable() ?: return run { renderLock.unlock() } val commandBuffer = commandQueue.commandBuffer() ?: return // Synchronously executes rendering on main thread while holding state lock drawContent(drawable) commandBuffer.presentDrawable(drawable) commandBuffer.commit() commandBuffer.waitUntilCompleted() // FATAL: Deadlocks UI thread waiting for GPU fence renderLock.unlock() } } ``` #### Production Standard (Correct) > **Standard**: Decouples the CADisplayLink vsync trigger from GPU submission using an atomic guard and a dedicated serial render queue. Frame acquisition is non-blocking, and waitUntilCompleted() is avoided, keeping the main runloop responsive. ```kotlin // GOOD: VSync signals atomic dirty state; rendering runs on isolated serial queue with non-blocking drawable acquisition class SkikoMetalFrameRenderer( private val layer: CAMetalLayer, private val renderScope: CoroutineScope ) { private val isFrameScheduled = atomic(false) private val renderDispatcher = newSingleThreadContext("SkikoRenderQueue") @ObjCAction fun onDisplayLinkStep() { // Signal vsync without acquiring graphics locks or blocking main thread if (isFrameScheduled.compareAndSet(expect = false, update = true)) { renderScope.launch(renderDispatcher) { try { renderFrame() } finally { isFrameScheduled.value = false } } } } private fun renderFrame() { autoreleasepool { // Asynchronously acquire drawable; drop frame cleanly if backpressure occurs val drawable = layer.nextDrawable() ?: return@autoreleasepool val commandBuffer = commandQueue.commandBuffer() ?: return@autoreleasepool drawContent(drawable) commandBuffer.presentDrawable(drawable) commandBuffer.commit() // Hand off to GPU asynchronously without waiting for fence } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Skiko Metal/Vulkan Frame Pacing and Mutex Synchronization Standard

KMP Skiko Metal/Vulkan Frame Pacing and Mutex Synchronization Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict isolation between native frame-pacing mechanisms (CADisplayLink/Choreographer) and Skiko rendering mutexes in Compose Multiplatform. Prevents main-thread priority inversion and deadlocks by prohibiting synchronous waits on GPU drawables or command buffer completion inside lock-holding native vsync callbacks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Synchronously blocking CADisplayLink or Main RunLoop on Skiko Render Mutexes and GPU Surface Acquisition Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Synchronously blocking CADisplayLink or Main RunLoop on Skiko Render Mutexes and GPU Surface Acquisition	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST NEVER acquire Skiko rendering mutexes synchronously inside the CADisplayLink or Choreographer callback on the main thread.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.