KMP Compose Metal Render-Loop Frame Synchronization Fence

--- description: KMP Compose Metal Render-Loop Frame Synchronization Fence - Decouples Kotlin StateFlow emissions from Apple ProMotion CADisplayLink and Metal render loops in Compose Multiplatform iOS targets. Prevents main-thread UI hitching and frame drops by establishing a lock-free atomic snapshot fence between high-frequency Coroutine state updates and CAMetalDrawable presentation cycles. globs: **/iosMain/**/*.kt, **/commonMain/**/*.kt, **/*.ios.kt, **/metal/**/*.kt, **/rendering/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-metal-render-loop-frame-fence-guardrail" --- # KMP Compose Metal Render-Loop Frame Synchronization Fence > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronous Main-Thread StateFlow Collection Blocking CAMetalLayer Render Passes During ProMotion 120Hz VSync ## System Constraints You are a Principal Software Architect specializing in Kotlin Multiplatform and low-level iOS graphics subsystems. Your task is to enforce strict lock-free frame-fencing boundaries between Kotlin Coroutines/StateFlow emissions and native Apple Metal/CADisplayLink render passes. Ensure zero hitching under 120Hz ProMotion displays by eliminating synchronous recomposition and lock contention on the UIKit/Metal main runloop. ## Strict Guidelines - Engineers MUST ALWAYS isolate Kotlin StateFlow state propagation from native CADisplayLink ticks using an atomic lock-free snapshot buffer (e.g., AtomicReference or double-buffered slot). - Engineers MUST NOT synchronously collect StateFlow emissions inside the CADisplayLink render callback or directly invoke CAMetalDrawable render passes from background Coroutine dispatchers. - Engineers MUST configure CADisplayLink frame pacing explicitly with CAFrameRateRange matching native 60Hz/120Hz ProMotion capabilities without stalling the Skiko/Metal presentation command buffer. - Code SHOULD offload state transformation and heavy payload mapping to Dispatchers.Default, reserving the final atomic exchange for the immediate Metal render-fence boundary. - Components NEVER hold mutual exclusion locks (NSLock, synchronized, Mutex) across the boundary where CAMetalDrawable acquisition or MTLCommandBuffer commit occurs. ## Bad vs Good Implementations ### Decoupling StateFlow from CADisplayLink Render Pass with Atomic Fence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Collecting StateFlow directly on Dispatchers.Main and performing render commands synchronously competes with CADisplayLink. This introduces micro-stutter when state updates arrive faster than the 120Hz refresh interval or when garbage collection/recomposition blocks CAMetalLayer.nextDrawable(). ```kotlin // BAD: Direct collection on Dispatchers.Main blocks CADisplayLink frame cycle and starves CAMetalDrawable class MetalComposeBridge(private val stateFlow: StateFlow<UiRenderState>) { private var displayLink: CADisplayLink? = null private val scope = CoroutineScope(Dispatchers.Main) fun attach(layer: CAMetalLayer) { // Synchronous observation on Main dispatcher directly triggers heavy recomposition // during native VSync windows, causing hitching and missed ProMotion 120Hz deadlines scope.launch { stateFlow.collect { state -> val drawable = layer.nextDrawable() ?: return@collect renderDirectlyToMetal(state, drawable) } } } private fun renderDirectlyToMetal(state: UiRenderState, drawable: CAMetalDrawable) { // Heavy rendering synchronously blocking UIKit main thread } } ``` #### Production Standard (Correct) > **Standard**: State updates are decoupled from the display tick using an atomic frame fence (`latestFrameState`). Kotlin coroutines push updates concurrently on `Dispatchers.Default`, while `CADisplayLink` pulls the latest available frame on vsync without locking or causing main-thread starvation. ```kotlin // GOOD: Atomic lock-free snapshot buffer decoupling StateFlow updates from CADisplayLink ticks import kotlinx.atomicfu.atomic import platform.QuartzCore.* class MetalComposeBridge( private val stateFlow: StateFlow<UiRenderState>, private val scope: CoroutineScope ) { private val latestFrameState = atomic<UiRenderState?>(null) private var displayLink: CADisplayLink? = null fun attach(layer: CAMetalLayer) { // Offload state emissions to background, atomically updating the render fence scope.launch(Dispatchers.Default) { stateFlow.collect { state -> latestFrameState.value = state } } // Bind CADisplayLink with explicit ProMotion frame rate ranges displayLink = CADisplayLink.displayLinkWithTarget( target = this, selector = platform.objc.sel_registerName("stepFrame:") ).apply { setFrameRateRange(CAFrameRateRangeMake(minimum = 60f, maximum = 120f, preferred = 120f)) addToRunLoop(NSRunLoop.mainRunLoop, NSRunLoopCommonModes) } } @OptIn(kotlinx.cinterop.BetaInteropApi::class) @platform.objc.ObjCAction fun stepFrame(link: CADisplayLink) { // Consume the atomic snapshot without holding locks or stalling the presentation pipeline val frameSnapshot = latestFrameState.getAndSet(null) ?: return renderToMetal(frameSnapshot) } private fun renderToMetal(state: UiRenderState) { // Render current frame snapshot safely into CAMetalCommandBuffer } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Compose Metal Render-Loop Frame Synchronization Fence

KMP Compose Metal Render-Loop Frame Synchronization Fence defines an industrial-grade behavioral standard for mobile engineering. Decouples Kotlin StateFlow emissions from Apple ProMotion CADisplayLink and Metal render loops in Compose Multiplatform iOS targets. Prevents main-thread UI hitching and frame drops by establishing a lock-free atomic snapshot fence between high-frequency Coroutine state updates and CAMetalDrawable presentation cycles. 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: Synchronous Main-Thread StateFlow Collection Blocking CAMetalLayer Render Passes During ProMotion 120Hz VSync 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	Synchronous Main-Thread StateFlow Collection Blocking CAMetalLayer Render Passes During ProMotion 120Hz VSync	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 isolate Kotlin StateFlow state propagation from native CADisplayLink ticks using an atomic lock-free snapshot buffer (e.g., AtomicReference or double-buffered slot).

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.