KMP Skiko Metal Render Thread Darwin Main Queue Synchronization

--- description: KMP Skiko Metal Render Thread Darwin Main Queue Synchronization - Enforces strict synchronization boundaries between Kotlin Multiplatform Skiko Metal drawing routines and Darwin's Grand Central Dispatch (GCD) main queue. Failure to isolate and properly interop with the main thread during CAMetalLayer transactions causes GPU command buffer stalling, UI thread deadlock, and hitch rates exceeding 60 FPS cadences on iOS. globs: **/*Actual.kt, **/iosMain/**/*.kt, **/skiko/**/*.kt, **/metal/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skiko-darwin-metal-queue-sync" --- # KMP Skiko Metal Render Thread Darwin Main Queue Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Direct CAMetalLayer Drawing or Synchronous Main Thread Blocking from Skiko Render Loop ## System Constraints You are a Principal Mobile Architect enforcing strict thread boundaries and dispatch invariants between JetBrains Skiko (Metal backend) and Darwin Grand Central Dispatch (GCD) in Kotlin Multiplatform iOS applications. You ensure all CAMetalLayer lifecycle operations, CADisplayLink interactions, and frame dispatch routines avoid main thread deadlock, memory inversion, and Metal command buffer race conditions. ## Strict Guidelines - Engineers MUST ALWAYS dispatch CAMetalLayer frame buffer queries and presentation requests consistently within Darwin's native dispatch_async(dispatch_get_main_queue()) or coordinated Skiko RenderDelegate boundaries. - Engineers MUST NOT execute dispatch_sync against dispatch_get_main_queue() from Skiko background rendering loops or Metal command buffer completion handlers, as this triggers irrecoverable OS-level priority inversion deadlocks. - Engineers MUST verify NSThread.isMainThread before invoking Skiko rendering context mutation or layer resizing, delegating to dispatch_async when called from background coroutines or worker threads. - Code MUST capture CAMetalDrawable references strictly inside the render pass boundary and invoke presentDrawable asynchronously on the scheduled command buffer rather than holding lock-guarded drawable references. - Services MUST ensure that display synchronization through CADisplayLink is invalidated and decoupled on Darwin main queue dealloc to prevent dangling callbacks into destroyed Skia drawing contexts. ## Bad vs Good Implementations ### Coordinating Skiko Metal Frame Submission with Darwin Main Queue #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using dispatch_sync to acquire CAMetalDrawable or trigger Skia updates locks the Skiko render thread while Darwin's main queue may be waiting on GPU resources or handling user input, leading to hard OS deadlocks and watchdog kills. ```kotlin import platform.darwin.dispatch_sync import platform.darwin.dispatch_get_main_queue import org.jetbrains.skiko.SkiaLayer import platform.QuartzCore.CAMetalLayer class MetalRenderBridge(private val layer: SkiaLayer, private val metalLayer: CAMetalLayer) { fun onFrameAvailable() { // CRITICAL ANTI-PATTERN: Synchronously dispatching to Darwin main queue // from Skiko's internal render thread causes immediate UI thread deadlock // if UIKit is awaiting a frame layout or presentation lock. dispatch_sync(dispatch_get_main_queue()) { val drawable = metalLayer.nextDrawable() if (drawable != null) { layer.update(drawable) } } } } ``` #### Production Standard (Correct) > **Standard**: Checks if the thread is already Darwin main; otherwise uses dispatch_async to ensure Skiko render calls do not block the worker thread while safely interacting with CAMetalLayer on the main runloop. ```kotlin import platform.darwin.dispatch_async import platform.darwin.dispatch_get_main_queue import platform.Foundation.NSThread import org.jetbrains.skiko.SkiaLayer import platform.QuartzCore.CAMetalLayer class MetalRenderBridge(private val layer: SkiaLayer, private val metalLayer: CAMetalLayer) { fun onFrameAvailable() { // PRODUCTION INVARIANT: Check execution context. Never block the caller. // Dispatch asynchronously to Darwin's main queue when cross-thread coordination is necessary. if (NSThread.isMainThread) { renderDirectly() } else { dispatch_async(dispatch_get_main_queue()) { renderDirectly() } } } private fun renderDirectly() { // MetalLayer presentation is bound to the render thread lifecycle safely val drawable = metalLayer.nextDrawable() ?: return layer.update(drawable) } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Skiko Metal Render Thread Darwin Main Queue Synchronization

KMP Skiko Metal Render Thread Darwin Main Queue Synchronization defines an industrial-grade behavioral standard for mobile engineering. Enforces strict synchronization boundaries between Kotlin Multiplatform Skiko Metal drawing routines and Darwin's Grand Central Dispatch (GCD) main queue. Failure to isolate and properly interop with the main thread during CAMetalLayer transactions causes GPU command buffer stalling, UI thread deadlock, and hitch rates exceeding 60 FPS cadences on iOS. 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: Direct CAMetalLayer Drawing or Synchronous Main Thread Blocking from Skiko Render Loop 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	Direct CAMetalLayer Drawing or Synchronous Main Thread Blocking from Skiko Render Loop	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 ALWAYS dispatch CAMetalLayer frame buffer queries and presentation requests consistently within Darwin's native dispatch_async(dispatch_get_main_queue()) or coordinated Skiko RenderDelegate boundaries.

Engineers MUST ALWAYS dispatch CAMetalLayer frame buffer queries and presentation requests consistently within Darwin's native dispatch_async(dispatch_get_main_queue()) or coordinated Skiko RenderDelegate boundaries.

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.