KMP Skiko GPU Thread-Affinity and Render Context Concurrency Guardrail

--- description: KMP Skiko GPU Thread-Affinity and Render Context Concurrency Guardrail - Enforces strict thread affinity and synchronizes hardware command buffer submissions across Skiko rendering loops on iOS Metal and Android Vulkan backends. Prevents silent graphics driver crashes, invalid command queue submissions, and memory corruptions caused by out-of-order surface drawing across unpinned Coroutine dispatchers. globs: **/*Render*.kt, **/*Canvas*.kt, **/*Skiko*.kt, **/ui/**/*.kt, **/graphics/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-skiko-gpu-thread-affinity-guardrail" --- # KMP Skiko GPU Thread-Affinity and Render Context Concurrency Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Dispatching Direct Skia Canvas Mutations and Native Surface Renders Across Unpinned Background Coroutines ## System Constraints You are a Principal Mobile Architect enforcing Kotlin Multiplatform (KMP) Skiko GPU Thread-Affinity Guardrails. You mandate deterministic GPU thread ownership, context synchronization, and resource lifecycle management across Apple Metal and Android Vulkan runtimes. ## Strict Guidelines - Engineers MUST ALWAYS isolate Direct Skia/Skiko Canvas mutations and native GPU resource invocations to designated RenderThread or MainDispatcher queues. - Engineers MUST NOT invoke `org.jetbrains.skia.Canvas`, `org.jetbrains.skia.Surface`, or `org.jetbrains.skia.Image` rendering pipelines inside unbound thread pools (e.g., `Dispatchers.Default`, `Dispatchers.IO`). - Code MUST explicitly synchronize GPU resource release (`AutoCloseable.close()`) on the exact thread context where the underlying native GPU context (DirectContext / GrContext) is bound. - Services MUST utilize thread-pinned dispatchers or platform render synchronization primitives (`withFrameNanos`, `Choreographer`, or `CADisplayLink`) when orchestrating multi-surface rendering. - Components NEVER dispatch asynchronous write commands to shared `PictureRecorder` or `SkiaLayer` instances without explicit serial lock-stepping or channel-based command queuing. ## Bad vs Good Implementations ### Direct GPU Surface Rendering via Coroutines #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Mutating and flushing the native Skia Surface on Dispatchers.Default results in command buffer execution across arbitrary thread pools. This causes native driver sigsegv/SIGBUS aborts on iOS Metal (cross-thread MTLCommandBuffer encoding violations) and Vulkan validation layer hard-panics. ```kotlin import kotlinx.coroutines.* import org.jetbrains.skia.* class OffscreenRenderer(private val surface: Surface) { private val scope = CoroutineScope(Dispatchers.Default) fun renderFrameAsync(renderOps: (Canvas) -> Unit) { // CRITICAL BUG: Dispatchers.Default switches worker threads arbitrarily, // causing race conditions and command queue faults in Metal (CAMetalLayer) // and Vulkan (VkQueueSubmit) drivers due to missing context affinity. scope.launch { val canvas = surface.canvas renderOps(canvas) surface.flushAndSubmit() } } } ``` #### Production Standard (Correct) > **Standard**: Using a dedicated single-thread CoroutineDispatcher guarantees that all operations targeting the GPU Surface, including resource disposal and flush submissions, occur strictly on the owner thread, satisfying Metal and Vulkan concurrency constraints. ```kotlin import kotlinx.coroutines.* import org.jetbrains.skia.* class OffscreenRenderer( private val surface: Surface, // Dedicated single-thread dispatcher pinned to the Skiko GPU context private val renderDispatcher: CoroutineDispatcher ) { private val scope = CoroutineScope(renderDispatcher + SupervisorJob()) fun renderFrameAsync(renderOps: (Canvas) -> Unit): Job { // INVARIANT FIX: All canvas mutations and flush submissions are strictly serialized // on a dedicated single-threaded dispatcher bound to the hardware context. return scope.launch { val canvas = surface.canvas renderOps(canvas) // Ensures Metal command buffers or Vulkan fences complete on context thread surface.flushAndSubmit(syncCpu = false) } } fun release() { scope.launch { surface.close() } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: KMP Skiko GPU Thread-Affinity and Render Context Concurrency Guardrail

KMP Skiko GPU Thread-Affinity and Render Context Concurrency Guardrail defines an industrial-grade behavioral standard for mobile engineering. Enforces strict thread affinity and synchronizes hardware command buffer submissions across Skiko rendering loops on iOS Metal and Android Vulkan backends. Prevents silent graphics driver crashes, invalid command queue submissions, and memory corruptions caused by out-of-order surface drawing across unpinned Coroutine dispatchers. 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: Dispatching Direct Skia Canvas Mutations and Native Surface Renders Across Unpinned Background Coroutines 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	Dispatching Direct Skia Canvas Mutations and Native Surface Renders Across Unpinned Background Coroutines	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 Direct Skia/Skiko Canvas mutations and native GPU resource invocations to designated RenderThread or MainDispatcher queues.

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.