Compose Multiplatform Metal/Vulkan Surface Allocation Fence Synchronization

--- description: Compose Multiplatform Metal/Vulkan Surface Allocation Fence Synchronization - Prevents GPU VRAM exhaustion, command buffer deadlocks, and layout hitching in Compose Multiplatform by enforcing explicit native surface synchronization fences. Decouples native surface disposal from platform garbage collection cycles across iOS (Metal/CAMetalLayer) and Android (Vulkan/ANativeWindow) through deterministic drain and disposal gates. globs: **/*.kt, **/iosMain/**/*.kt, **/androidMain/**/*.kt, **/*Surface*.kt, **/*Renderer*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/compose-multiplatform-metal-vulkan-surface-allocation-fence" --- # Compose Multiplatform Metal/Vulkan Surface Allocation Fence Synchronization > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Relying on Managed Heap Garbage Collection to Deallocate Native Metal and Vulkan Surface Backbuffers ## System Constraints You are a Principal Graphics and Mobile Systems Architect enforcing Compose Multiplatform Metal/Vulkan Surface Allocation Fence invariants. You must prevent memory exhaustion, GPU pipeline stalls, and composition hitches caused by asynchronously collected native render surfaces. ## Strict Guidelines - Engineers MUST ALWAYS synchronize surface destruction with explicit GPU pipeline fences (e.g., waiting on in-flight command buffers in Metal or draining queues via vkQueueWaitIdle in Vulkan) prior to freeing native surface backing memory. - Engineers MUST NOT rely on JVM GC finalizers, Kotlin/Native ARC/tracing sweepers, or cleaner tasks to reclaim Vulkan swapchains or Metal CAMetalLayer resources. - Code MUST deterministicly unbind and fence native surface handles inside Compose's DisposableEffect(Unit) or equivalent platform-lifecycle hooks before emitting replacement surfaces during configuration changes or navigation transitions. - Services MUST throttle resize and recomposition passes to the display refresh interval to prevent surface allocation bursts from overwhelming the GPU memory allocator. - Components NEVER invoke native surface deallocation while frame presentation is active or GPU fences remain unsignaled. ## Bad vs Good Implementations ### Native Surface Lifecycle Fence in Compose Multiplatform #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to explicitly drain in-flight GPU commands and fence native surface destruction ties GPU VRAM reclamation to the non-deterministic managed garbage collector. During recompositions or layout resizes, old swapchains and framebuffers pile up in memory, causing VRAM exhaustion and pipeline deadlocks. ```kotlin // BAD: Implicit deallocation dependent on GC/ARC. Rapid recomposition leaks VRAM. @Composable fun RenderCanvas(modifier: Modifier = Modifier) { val nativeSurface = remember { PlatformSurfaceAllocator.acquire() } // On disposal or resize, the reference simply drops from the composition. // Native CAMetalLayer/VkSwapchainKHR remains resident until garbage collection runs, // exhausting swapchain images and causing dropped frames or OOM. Canvas(modifier = modifier) { nativeSurface.draw(this) } } ``` #### Production Standard (Correct) > **Standard**: Explicitly invalidating the surface and blocking native disposal on a hardware fence (awaitGpuIdleFence) guarantees that GPU work is retired before deallocating backbuffers, preventing Vulkan VK_ERROR_DEVICE_LOST or Metal CAMetalLayer allocation deadlocks. ```kotlin // GOOD: Deterministic GPU drain fence tied to Compose DisposableEffect @Composable fun RenderCanvas(modifier: Modifier = Modifier) { val surfaceHolder = remember { PlatformSurfaceAllocator.acquire() } DisposableEffect(surfaceHolder) { onDispose { // 1. Mark surface invalid to halt incoming draw calls surfaceHolder.invalidate() // 2. Synchronous GPU drain fence: block until Metal command buffers or Vulkan queues complete surfaceHolder.awaitGpuIdleFence() // 3. Immediately free underlying CAMetalLayer/ANativeWindow swapchain surfaceHolder.releaseImmediate() } } Canvas(modifier = modifier) { if (surfaceHolder.isValid) { surfaceHolder.draw(this) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Compose Multiplatform Metal/Vulkan Surface Allocation Fence Synchronization

Compose Multiplatform Metal/Vulkan Surface Allocation Fence Synchronization defines an industrial-grade behavioral standard for mobile engineering. Prevents GPU VRAM exhaustion, command buffer deadlocks, and layout hitching in Compose Multiplatform by enforcing explicit native surface synchronization fences. Decouples native surface disposal from platform garbage collection cycles across iOS (Metal/CAMetalLayer) and Android (Vulkan/ANativeWindow) through deterministic drain and disposal gates. 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: Relying on Managed Heap Garbage Collection to Deallocate Native Metal and Vulkan Surface Backbuffers 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	Relying on Managed Heap Garbage Collection to Deallocate Native Metal and Vulkan Surface Backbuffers	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 synchronize surface destruction with explicit GPU pipeline fences (e.g., waiting on in-flight command buffers in Metal or draining queues via vkQueueWaitIdle in Vulkan) prior to freeing native surface backing memory.

Engineers MUST ALWAYS synchronize surface destruction with explicit GPU pipeline fences (e.g., waiting on in-flight command buffers in Metal or draining queues via vkQueueWaitIdle in Vulkan) prior to freeing native surface backing memory.

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.