1# Linting & Concurrency
2 
3Use this when:
4 
5- SwiftLint flags `async_without_await` or other concurrency-related warnings.
6- You need to decide whether to suppress, fix, or reconfigure a concurrency lint rule.
7 
8Skip this file if:
9 
10- The issue is a compiler diagnostic, not a lint rule. Use `actors.md`, `sendable.md`, or `threading.md`.
11 
12Jump to:
13 
14- SwiftLint Concurrency Rules Overview
15- `async_without_await` Rule
16- Suppression Strategies
17 
18## SwiftLint Concurrency Rules Overview
19 
20SwiftLint provides several rules targeting async/await and concurrency patterns. Understanding when to fix vs. suppress is critical.
21 
22| Rule | Default | Purpose |
23|------|---------|---------|
24| `async_without_await` | warning | Flags `async` functions that never await |
25| `unowned_variable_capture` | warning | Warns about `unowned` in closures (risky in async) |
26| `class_delegate_protocol` | warning | Ensures delegates are class-bound (AnyObject) |
27| `weak_delegate` | warning | Delegates should be weak to avoid retain cycles |
28 
29## SwiftLint: `async_without_await`
30 
31- **Intent**: A declaration should not be `async` if it never awaits.
32- **Never "fix"** by inserting fake suspension (e.g. `await Task.yield()`, `await Task { ... }.value`). Those mask the real issue and add meaningless suspension points.
33- **Legit use of `Task.yield()`**: OK in tests or scheduling control when you truly need a yield; not as a lint workaround.
34 
35### Diagnose why the declaration is `async`
361) **Protocol requirement** — the protocol method/property is `async`.
372) **Override requirement** — base class API is `async`.
383) **`@concurrent` requirement** — stays `async` even without `await`.
394) **Accidental/legacy `async`** — no caller needs async semantics.
40 
41### Preferred fixes (order)
421) **Remove `async`** (and adjust call sites) when no async semantics are needed.
432) If `async` is required (protocol/override/@concurrent):
44   - Re-evaluate the upstream API if you own it (can it be non-async?).
45   - If you cannot change it, keep `async` and **narrowly suppress the rule** where appropriate (common for mocks/stubs/overrides).
46 
47### Suppression examples (keep scope tight)
48```swift
49// swiftlint:disable:next async_without_await
50func fetch() async { perform() }
51 
52// For a block:
53// swiftlint:disable async_without_await
54func makeMock() async { perform() }
55// swiftlint:enable async_without_await
56```
57 
58### Quick checklist
59- [ ] Confirm if `async` is truly required (protocol/override/@concurrent).
60- [ ] If not required, remove `async` and update callers.
61- [ ] If required, prefer localized suppression over dummy awaits.
62- [ ] Avoid adding new suspension points without intent.
63 
64## Compiler Warnings: Sendable & Isolation
65 
66The Swift compiler generates concurrency-related warnings based on strict concurrency checking level.
67 
68### Common Warning Patterns
69 
70**"Capture of non-sendable type"**
71```swift
72// Warning: Capture of 'self' with non-sendable type 'MyClass' in a `@Sendable` closure
73Task {
74    self.doWork() // 'self' is non-Sendable
75}
76```
77 
78**Fixes (in order of preference):**
791. Make the type `Sendable` if it's truly thread-safe
802. Use `@MainActor` isolation if it's UI-related
813. Capture only Sendable values instead of `self`
824. Use `@unchecked Sendable` with documented safety invariant (last resort)
83 
84**"Non-sendable result returned"**
85```swift
86// Warning: Non-sendable type 'MyResult' returned by implicitly async call
87let result = await actor.getData() // Returns non-Sendable type
88```
89 
90**Fixes:**
911. Make the return type Sendable
922. Return Sendable projections (IDs, copies of data)
933. Keep processing within the actor's isolation
94 
95### Actor Isolation Warnings
96 
97**"Main actor-isolated property accessed from non-isolated context"**
98```swift
99// Warning: Main actor-isolated property 'title' cannot be referenced from a non-isolated context
100func updateTitle() {
101    viewModel.title = "New" // viewModel is @MainActor
102}
103```
104 
105**Fixes:**
1061. Mark the calling function `@MainActor`
1072. Use `await MainActor.run { }` for one-off access
1083. Reconsider if the property truly needs @MainActor isolation
109 
110## Suppression Strategies
111 
112### When to Suppress vs. Fix
113 
114**Fix when:**
115- The warning identifies a real data race risk
116- The fix is straightforward (add Sendable, adjust isolation)
117- The code is new or actively maintained
118 
119**Suppress when:**
120- Protocol/inheritance requires the signature
121- Third-party code forces the pattern
122- Migration is in progress (with tracked ticket)
123 
124### Suppression Annotations
125 
126```swift
127// Suppress Sendable warnings for legacy imports
128@preconcurrency import LegacyFramework
129 
130// Suppress for a single declaration
131nonisolated(unsafe) var legacyCallback: (() -> Void)?
132 
133// Type-level suppression (use sparingly)
134struct LegacyWrapper: @unchecked Sendable {
135    // Document why this is safe
136    private let lock = NSLock()
137    private var value: Int
138}
139```
140 
141### Documentation Requirements
142 
143When using suppression annotations, document:
1441. **Why** the suppression is needed
1452. **What** invariant makes it safe
1463. **When** it can be removed (link to migration ticket)
147 
148```swift
149/// Thread-safe: Internal lock protects all mutations.
150/// TODO: Remove @unchecked when migrated to actor (JIRA-1234)
151final class ThreadSafeCache: @unchecked Sendable {
152    private let lock = NSLock()
153    private var storage: [String: Data] = [:]
154}
155```
156