Compose Multiplatform Skiko Metal Render Thread Synchronization Guardrail

--- description: Compose Multiplatform Skiko Metal Render Thread Synchronization Guardrail - Enforces strict non-blocking mutual exclusion and asynchronous dispatch between native iOS UIKit run loops and the Skiko Metal rendering pipeline in Compose Multiplatform. Eliminates catastrophic CADisplayLink deadlocks, CAMetalLayer drawable timeouts, and frame-pacing degradation caused by synchronous main-thread reentrancy. globs: **/iosMain/**/*.kt, **/appleMain/**/*.kt, **/*Ios.kt, **/*ViewController.kt, **/platform/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-compose-skiko-ios-render-thread-synchronization" --- # Compose Multiplatform Skiko Metal Render Thread Synchronization Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Synchronous Main-Thread Blocking and Reentrant Layout Within Skiko CADisplayLink Render Cycles ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Compose Multiplatform rendering internals. Your role is to enforce strict thread synchronization invariants between Skiko's Metal redrawer and Apple's UIKit/CoreAnimation run loops. Never permit synchronous blocking (such as runBlocking, dispatch_sync, or CATransaction.flush) within rendering contexts or UIKitView interop layers on iOS, as these cause irreducible deadlocks with CAMetalLayer drawable acquisition and frame pacing collapses. ## Strict Guidelines - Engineers MUST ALWAYS isolate native UIKit view mutations from the Skiko redraw loop by scheduling non-blocking updates via Dispatchers.Main.immediate or dispatch_async. - Engineers MUST NOT execute runBlocking, dispatch_sync, or CATransaction.flush() inside UIKitView factory, update blocks, or custom Skiko SkiaLayer render callbacks. - Components NEVER trigger synchronous view hierarchy measurements (e.g., layoutIfNeeded()) directly within Compose rendering phases on iOS target platforms. - Code SHOULD decouple high-frequency native gesture and display-link updates from Compose state using conflated channels or state flows to prevent Skiko Metal command buffer exhaustion. - Services MUST ensure that ComposeUIViewController teardown, background transitions, and view-controller dismissals synchronously detach Metal redraw hooks before destroying backing native layers. ## Bad vs Good Implementations ### UIKit Interop Layer Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing runBlocking on Dispatchers.Main combined with CATransaction.flush() during the view hierarchy construction or update cycle blocks Skiko's MetalRedrawer from acquiring the next CAMetalDrawable. This triggers an unrecoverable priority-inversion deadlock on the iOS main run loop. ```kotlin import androidx.compose.runtime.Composable import androidx.compose.ui.Modifier import androidx.compose.ui.interop.UIKitView import kotlinx.cinterop.ExperimentalForeignApi import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.runBlocking import platform.MapKit.MKMapView import platform.QuartzCore.CATransaction @OptIn(ExperimentalForeignApi::class) @Composable fun MapComponent(isTracking: Boolean, modifier: Modifier = Modifier) { UIKitView( factory = { val map = MKMapView() // DEADLOCK: Blocking the Skiko Metal redraw thread with synchronous main-queue synchronization runBlocking(Dispatchers.Main) { map.showsUserLocation = isTracking CATransaction.flush() // Freezes CADisplayLink and prevents CAMetalLayer drawable return } map }, modifier = modifier, update = { view -> // Synchronous forced layout directly during the Skiko frame presentation phase view.layoutIfNeeded() } ) } ``` #### Production Standard (Correct) > **Standard**: Updates are dispatched non-blockingly using Dispatchers.Main.immediate, and layout passes are requested via setNeedsLayout() rather than forced synchronously with layoutIfNeeded(). This allows the Skiko MetalRedrawer to complete its drawable presentation cycle without lock contention. ```kotlin import androidx.compose.runtime.Composable import androidx.compose.runtime.rememberCoroutineScope import androidx.compose.ui.Modifier import androidx.compose.ui.interop.UIKitView import kotlinx.cinterop.ExperimentalForeignApi import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.launch import platform.MapKit.MKMapView @OptIn(ExperimentalForeignApi::class) @Composable fun MapComponent(isTracking: Boolean, modifier: Modifier = Modifier) { val scope = rememberCoroutineScope() UIKitView( factory = { MKMapView().apply { showsUserLocation = isTracking } }, modifier = modifier, update = { view -> // Safely defer property updates and layout requests to the next main loop turn scope.launch(Dispatchers.Main.immediate) { if (view.showsUserLocation != isTracking) { view.showsUserLocation = isTracking } view.setNeedsLayout() // Asynchronous mark; does not halt Metal command buffer pipeline } }, onRelease = { view -> view.delegate = null view.removeFromSuperview() } ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Skiko Metal Render Thread Synchronization Guardrail

Compose Multiplatform Skiko Metal Render Thread Synchronization Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict non-blocking mutual exclusion and asynchronous dispatch between native iOS UIKit run loops and the Skiko Metal rendering pipeline in Compose Multiplatform. Eliminates catastrophic CADisplayLink deadlocks, CAMetalLayer drawable timeouts, and frame-pacing degradation caused by synchronous main-thread reentrancy. 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 Blocking and Reentrant Layout Within Skiko CADisplayLink Render Cycles 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 Blocking and Reentrant Layout Within Skiko CADisplayLink Render Cycles	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 native UIKit view mutations from the Skiko redraw loop by scheduling non-blocking updates via Dispatchers.Main.immediate or dispatch_async.

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.