mohitmujawdiya/swift-concurrency

Swift Concurrency Patterns

MainActor Rules

1. @MainActor on the class level for AppDelegate and any class that primarily interacts with UI. This means all methods and properties are MainActor-isolated by default — no need for per-method annotations.

2. Never nest @MainActor inside @MainActor. If a class is @MainActor, its methods don't need the annotation again. Adding it is noise.

3. Callbacks from non-MainActor contexts:

   // CORRECT — dispatches to MainActor from any thread
   client.onEvent = { [weak self] value in
       Task { @MainActor in self?.viewModel.update(value) }
   }
   
   // WRONG — mixing DispatchQueue with MainActor
   client.onEvent = { [weak self] value in
       DispatchQueue.main.async { self?.viewModel.update(value) }
   }
   

Sendable & Thread Safety

4. @unchecked Sendable requires a documented locking strategy. Every mutable property must be protected by a named lock.

   final class AudioCapture: @unchecked Sendable {
       private let lock = NSLock()
       private var _onAudioChunk: ((Data) -> Void)?  // Protected by lock
   
       var onAudioChunk: ((Data) -> Void)? {
           get { lock.withLock { _onAudioChunk } }
           set { lock.withLock { _onAudioChunk = newValue } }
       }
   }
   

5. Read-then-act must be atomic. Don't read a locked value and then use it outside the lock if another thread could change it. Capture the values you need in a single lock acquisition:

   // CORRECT — single lock acquisition
   let callbacks = lock.withLock { (_onAudioChunk, _onAudioLevel) }
   callbacks.0?(data)
   callbacks.1?(level)
   
   // WRONG — two separate lock acquisitions, state could change between them
   let chunk = lock.withLock { _onAudioChunk }
   let level = lock.withLock { _onAudioLevel }
   

6. Callback closures on @unchecked Sendable types should be marked @Sendable where they'll be called from background threads. This enforces that captured values are Sendable.

Task Management

7. Background tasks from methods should use [weak self] to prevent retain cycles:

   Task { [weak self] in await self?.receiveLoop() }
   

8. Don't fire-and-forget important Tasks. If a Task's failure matters, capture it and handle errors. For WebSocket receive loops, the loop itself handles errors internally.

Async Lifecycle

9. Teardown before setup. When startSession is called, first clean up any existing session (stop audio, disconnect WebSocket) before creating new ones. This prevents resource leaks on reconnection.

10. URLSession must be invalidated on cleanup. Unlike most objects, URLSession retains its delegate and won't deallocate without invalidateAndCancel().