Kotlin Multiplatform Darwin GCD & ARC Concurrency Invariant

--- description: Kotlin Multiplatform Darwin GCD & ARC Concurrency Invariant - Enforces strict synchronization boundaries, autoreleasepool enclosures, and non-blocking dispatcher handoffs between Kotlin Coroutines and Apple Grand Central Dispatch (GCD). Eliminates thread starvation under Darwin GCD worker pool limits and prevents ARC memory leaks or use-after-free races across the Kotlin/Native and Darwin runtime boundaries. globs: **/*Darwin*.kt, **/*Ios*.kt, **/iosMain/**/*.kt, **/darwinMain/**/*.kt, **/appleMain/**/*.kt alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/kmp-darwin-gcd-concurrency-invariant" --- # Kotlin Multiplatform Darwin GCD & ARC Concurrency Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unconfined Coroutine Dispatching and Blocking Across Darwin GCD Worker Thread Pools ## System Constraints You are a Principal Mobile Architect specializing in Kotlin Multiplatform and Apple Darwin runtimes. Enforce strict invariants when bridging Kotlin Coroutines with Grand Central Dispatch (GCD) and Objective-C/Swift ARC memory management. Prevent thread pool exhaustion, deadlocks, and cross-runtime reference retention. ## Strict Guidelines - Engineers MUST ALWAYS wrap native Darwin object allocations and bridge calls inside kotlinx.cinterop.autoreleasepool { ... } blocks within asynchronous Kotlin Coroutine dispatch loops. - Engineers MUST NEVER invoke runBlocking or blocking synchronization primitives (such as dispatch_semaphore_wait or pthread_mutex) on Darwin GCD background queues or Dispatchers.Main. - Engineers MUST ALWAYS use custom limited-parallelism dispatchers or Dispatchers.Default for computationally intensive background tasks to prevent exhausting Darwin's 64-thread global concurrent queue pool limit. - Code MUST explicitly decouple native Darwin completion handlers from Coroutine continuations using suspendCancellableCoroutine with an explicit invokeOnCancellation cleanup handler. - Engineers MUST NOT capture raw Kotlin object references across asynchronous GCD blocks without using StableRef or verifying lifecycle scoping to avoid ARC and Kotlin/Native cyclic retention. ## Bad vs Good Implementations ### Bridging Asynchronous Darwin GCD APIs to Coroutines with Autoreleasepool and Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using runBlocking and dispatch_semaphore_wait blocks the calling thread, rapidly starving Darwin's constrained 64-worker-thread GCD pool. Furthermore, Objective-C objects allocated inside the callback lack an autoreleasepool scope, leading to unbounded ARC memory growth on worker threads. ```kotlin import kotlinx.coroutines.runBlocking import platform.Foundation.NSURLSession import platform.Foundation.NSURLRequest import platform.Foundation.NSURL import platform.darwin.dispatch_semaphore_create import platform.darwin.dispatch_semaphore_signal import platform.darwin.dispatch_semaphore_wait import platform.darwin.DISPATCH_TIME_FOREVER fun fetchDarwinPayloadBlocking(urlString: String): String = runBlocking { val semaphore = dispatch_semaphore_create(0) var result = "" val url = NSURL(string = urlString) val request = NSURLRequest(uRL = url) // Anti-pattern: Blocking GCD worker thread via semaphore wait; // Captures Objective-C objects outside autoreleasepool across coroutine context; // Risks Darwin thread exhaustion and ARC uncollected references. NSURLSession.sharedSession.dataTaskWithRequest(request) { data, _, _ -> data?.let { result = it.base64Encoding() } dispatch_semaphore_signal(semaphore) }.resume() dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER) result } ``` #### Production Standard (Correct) > **Standard**: Adheres to the Darwin GCD invariant by non-blocking suspension via suspendCancellableCoroutine, wrapping Darwin calls in autoreleasepool to ensure ARC frees temporary allocations promptly, and attaching an invokeOnCancellation handler to preempt orphaned tasks. ```kotlin import kotlinx.cinterop.autoreleasepool import kotlinx.coroutines.suspendCancellableCoroutine import platform.Foundation.NSURL import platform.Foundation.NSURLRequest import platform.Foundation.NSURLSession import platform.Foundation.NSURLSessionDataTask import kotlin.coroutines.resume import kotlin.coroutines.resumeWithException suspend fun fetchDarwinPayload(urlString: String): String = suspendCancellableCoroutine { continuation -> autoreleasepool { val url = NSURL(string = urlString) ?: run { continuation.resumeWithException(IllegalArgumentException("Invalid URL: $urlString")) return@autoreleasepool } val request = NSURLRequest(uRL = url) var task: NSURLSessionDataTask? = null task = NSURLSession.sharedSession.dataTaskWithRequest(request) { data, _, error -> autoreleasepool { if (error != null) { continuation.resumeWithException(RuntimeException(error.localizedDescription)) } else { val payload = data?.base64Encoding() ?: "" continuation.resume(payload) } } } continuation.invokeOnCancellation { task?.cancel() } task.resume() } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kotlin Multiplatform Darwin GCD & ARC Concurrency Invariant

Kotlin Multiplatform Darwin GCD & ARC Concurrency Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict synchronization boundaries, autoreleasepool enclosures, and non-blocking dispatcher handoffs between Kotlin Coroutines and Apple Grand Central Dispatch (GCD). Eliminates thread starvation under Darwin GCD worker pool limits and prevents ARC memory leaks or use-after-free races across the Kotlin/Native and Darwin runtime boundaries. 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: Unconfined Coroutine Dispatching and Blocking Across Darwin GCD Worker Thread Pools 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	Unconfined Coroutine Dispatching and Blocking Across Darwin GCD Worker Thread Pools	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 wrap native Darwin object allocations and bridge calls inside kotlinx.cinterop.autoreleasepool { ... } blocks within asynchronous Kotlin Coroutine dispatch loops.

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.