Updating an app to use Swift concurrency

At a glance

Platform note: the catalog lists iOS, iPadOS, Mac Catalyst, and watchOS. In the project file, the shipping code lives in watchOS targets (SDKROOT = watchos, WATCHOS_DEPLOYMENT_TARGET = 8.0). The project-level SDKROOT = iphoneos setting applies to the watchapp2-container target, which has no Swift sources (Updated/Coffee Tracker.xcodeproj/project.pbxproj:215, Updated/Coffee Tracker.xcodeproj/project.pbxproj:500).

Project structure

Updating an app to use Swift concurrency/
├── Configuration/SampleCode.xcconfig
├── Starting Point/                       completion handlers + DispatchQueue
│   ├── Coffee Tracker.xcodeproj
│   ├── Coffee Tracker WatchKit App/      Info.plist and assets only
│   └── Coffee Tracker WatchKit Extension/
│       └── (same 11 Swift files as Updated)
└── Updated/                              async/await + actors
    ├── Coffee Tracker.xcodeproj          3 targets: container, watch app, extension
    ├── Coffee Tracker WatchKit App/      Info.plist and assets only
    └── Coffee Tracker WatchKit Extension/
        ├── CoffeeTrackerApp.swift        @main App + delegate adaptor
        ├── ExtensionDelegate.swift       background refresh handling
        ├── ContentView.swift             root view, scene-phase reactions
        ├── CoffeeTrackerView.swift       main screen
        ├── DrinkListView.swift           add-drink sheet
        ├── CoffeeData.swift              @MainActor model + private CoffeeDataStore actor
        ├── HealthKitController.swift     HealthKit actor
        ├── ComplicationController.swift  CLKComplicationDataSource
        ├── Drink.swift / DrinkType.swift value types
        ├── HostingController.swift       WKHostingController (not referenced)
        └── Info.plist                    principal-class wiring

Structure observations

• The two variants have the same file names and type names. The sample teaches by diff: compare Starting Point/…/CoffeeData.swift with Updated/…/CoffeeData.swift to see the migration.
• Only the extension target compiles Swift. The WatchKit App folder holds only Info.plist and assets (Updated/Coffee Tracker.xcodeproj/project.pbxproj:232, Updated/Coffee Tracker.xcodeproj/project.pbxproj:249).
• Info.plist sets the two framework entry classes by name. CLKComplicationPrincipalClass selects ComplicationController, and WKExtensionDelegateClassName selects ExtensionDelegate (Updated/Coffee Tracker WatchKit Extension/Info.plist:23, Updated/Coffee Tracker WatchKit Extension/Info.plist:39).
• HostingController is compiled but nothing in the source references it. The SwiftUI @main app supplies the UI instead (Updated/Coffee Tracker WatchKit Extension/HostingController.swift:11).
• In the Updated variant, CoffeeData.swift holds two types: the private persistence actor and the implicitly internal CoffeeData model (only its currentDrinks member is public private(set)). The file boundary keeps CoffeeDataStore hidden from the rest of the module.

Overall architecture

flowchart LR
    App["CoffeeTrackerApp (@main)"] --> Root["ContentView"]
    App -. adaptor .-> Delegate["ExtensionDelegate"]
    Root -- environmentObject --> Views["CoffeeTrackerView / DrinkListView"]
    Root --> Model["CoffeeData (@MainActor, shared)"]
    Complication["ComplicationController"] --> Model
    Delegate --> Model
    Model --> Store["CoffeeDataStore (actor)"]
    Model --> HK["HealthKitController (actor)"]
    HK -. weak model .-> Model
    HK --> HealthKit["HKHealthStore"]

Reference code

Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:98 — CoffeeData

@MainActor
class CoffeeData: ObservableObject {
    // ...
    static let shared = CoffeeData()
    lazy var healthKitController = HealthKitController(withModel: self)

    // An actor used to save and load the model data away from the main thread.
    private let store = CoffeeDataStore()

    // ...
    @Published public private(set) var currentDrinks: [Drink] = []
    // ...
}

Interpretation

Observed: three framework entry points reach the model through the same static CoffeeData.shared: the SwiftUI root view (Updated/Coffee Tracker WatchKit Extension/ContentView.swift:19), the complication data source (Updated/Coffee Tracker WatchKit Extension/ComplicationController.swift:13), and the background-refresh delegate (Updated/Coffee Tracker WatchKit Extension/ExtensionDelegate.swift:33). The model owns two actor collaborators. HealthKitController keeps a weak back-reference so it can push HealthKit changes into the model.

Inference: the singleton exists because ClockKit and WatchKit create ComplicationController and ExtensionDelegate from Info.plist class names, so SwiftUI cannot inject the model into them. The comment at Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:103 says the model “needs to be accessed both from the app extension and from the complication controller”.

Ownership and state

classDiagram
    CoffeeData *-- CoffeeDataStore : private let store
    CoffeeData *-- HealthKitController : lazy var
    HealthKitController o-- CoffeeData : weak model
    CoffeeTrackerApp *-- ExtensionDelegate : WKExtensionDelegateAdaptor
    ContentView o-- CoffeeData : shared
    CoffeeTrackerView --> CoffeeData : EnvironmentObject
    ComplicationController o-- CoffeeData : lazy var data

Ownership evidence

Updated/Coffee Tracker WatchKit Extension/HealthKitController.swift:26 — HealthKitController

actor HealthKitController {
    // ...
    // A weak link to the main model.
    private weak var model: CoffeeData?

    // Indicates whether the user has authroized access to their health data
    private lazy var isAuthorized = false

    // ...
    init(withModel model: CoffeeData) {
        self.model = model
    }
    // ...
}

Observed weak point: CoffeeData owns HealthKitController strongly, and the controller points back with weak. This breaks the reference cycle the two-way relationship would otherwise create.

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

Build settings: SWIFT_VERSION = 5.0, and the project file contains no strict-concurrency setting (Updated/Coffee Tracker.xcodeproj/project.pbxproj:498). The compiler therefore applies Swift 5 language-mode checking. Some cross-isolation accesses below compile without visible await, and the source does not show which SDK isolation makes them legal.

Not present in either variant: Task.detached, TaskGroup, AsyncSequence/for await, MainActor.run, nonisolated, Sendable annotations, locks, and RunLoop scheduling.

Reference code

Updated/Coffee Tracker WatchKit Extension/HealthKitController.swift:97 — queryHealthKit()

private func queryHealthKit() async throws -> ([HKSample]?, [HKDeletedObject]?, HKQueryAnchor?) {
    return try await withCheckedThrowingContinuation { continuation in
        // ...
        let query = HKAnchoredObjectQuery(
            type: caffeineType,
            predicate: datePredicate,
            anchor: anchor,
            limit: HKObjectQueryNoLimit) { (_, samples, deletedSamples, newAnchor, error) in

            // When the query ends, check for errors.
            if let error = error {
                continuation.resume(throwing: error)
            } else {
                continuation.resume(returning: (samples, deletedSamples, newAnchor))
            }

        }
        store.execute(query)
    }
}

Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:201 — addDrink(mgCaffeine:onDate:): synchronous main-actor mutation first, then an unretained task for the effects

public func addDrink(mgCaffeine: Double, onDate date: Date) {
    // ...
    currentDrinks = drinks

    // Save drink information to HealthKit.
    Task {
        await self.healthKitController.save(drink: drink)
        await self.drinksUpdated()
    }
}

Observed design shift: Starting Point saved from a didSet observer on currentDrinks. Updated removes the observer and calls await drinksUpdated() explicitly after each mutation (Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:219, Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:241, Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:263). A property observer cannot await, so the save effect moved into the async methods (inference).

Task lifetime: no Task handle is retained, so none can be cancelled. Each task runs until its awaited work completes. Inference: this is acceptable here because every task is short-lived I/O, but no owner can stop the work when the scene changes.

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

Class and protocol design

classDiagram
    class WKExtensionDelegate {
        <<protocol>>
    }
    class CLKComplicationDataSource {
        <<protocol>>
    }
    ExtensionDelegate ..|> WKExtensionDelegate
    ComplicationController ..|> CLKComplicationDataSource
    CoffeeData ..|> ObservableObject
    ExtensionDelegate --> CoffeeData
    ComplicationController --> CoffeeData

Reference code

Updated/Coffee Tracker WatchKit Extension/ComplicationController.swift:10 — ComplicationController

class ComplicationController: NSObject, CLKComplicationDataSource {

    // The Coffee Tracker app's data model
    lazy var data = CoffeeData.shared

    // ...
    // Return the current timeline entry.
    func currentTimelineEntry(for complication: CLKComplication) async -> CLKComplicationTimelineEntry? {
        createTimelineEntry(forComplication: complication, date: Date())
    }
    // ...
}

No local protocol is declared. All protocol conformances are to framework protocols, so the design is not protocol-oriented.

Access control

Reference code

Updated/Coffee Tracker WatchKit Extension/CoffeeData.swift:14 — CoffeeDataStore

private actor CoffeeDataStore {
    // ...
    // Use this value to determine whether you have changes that can be saved to disk.
    private var savedValue: [Drink] = []

    // Begin saving the drink data to disk.
    func save(_ currentDrinks: [Drink]) {
        // ...
    }
    // ...
}

Unmarked declarations elsewhere are implicit Swift internal, which in this single-target app means visible to every file in the extension.

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    participant WK as WatchKit
    participant Del as ExtensionDelegate
    participant HK as HealthKitController (actor)
    participant Model as CoffeeData (@MainActor)
    participant Store as CoffeeDataStore (actor)
    WK->>Del: handle(backgroundTasks)
    Del->>HK: Task { await loadNewDataFromHealthKit() }
    HK->>HK: await queryHealthKit() (continuation)
    HK->>Model: await updateModel(newDrinks:deletedDrinks:)
    Model->>Store: await drinksUpdated() → store.save
    HK-->>Del: success
    Del->>WK: setTaskCompletedWithSnapshot(success)

Reference code

Updated/Coffee Tracker WatchKit Extension/ExtensionDelegate.swift:20 — handle(_:)

    func handle(_ backgroundTasks: Set<WKRefreshBackgroundTask>) {
        // ...
        for task in backgroundTasks {
            // ...
            switch task {
            // Handle background refresh tasks.
            case let backgroundTask as WKApplicationRefreshBackgroundTask:

                Task {
                    // Check for updates from HealthKit.
                    let model = CoffeeData.shared

                    let success = await model.healthKitController.loadNewDataFromHealthKit()

                    if success {
                        // Schedule the next background update.
                        scheduleBackgroundRefreshTasks()
                        self.logger.debug("Background Task Completed Successfully!")
                    }

                    // Mark the task as ended, and request an updated snapshot, if necessary.
                    backgroundTask.setTaskCompletedWithSnapshot(success)
                }
            // ...
            default:
                task.setTaskCompletedWithSnapshot(false)
            }
        }
    }

Naming conventions

• Types: role suffixes describe framework roles. …App is the entry, …View a SwiftUI view, …Controller a framework-facing collaborator (HealthKitController is an actor and ComplicationController a data source, not view controllers), and …Delegate the WatchKit delegate. CoffeeDataStore is a private persistence actor, not an app-wide state store.
• Data: CoffeeData is the observable model, Drink a record, DrinkType a catalog enum.
• Methods: verb-first commands (addDrink(mgCaffeine:onDate:), requestAuthorization(), loadNewDataFromHealthKit(), scheduleBackgroundRefreshTasks()). Past-tense effect hooks (drinksUpdated()). Unit-bearing names (mgCaffeine, currentMGCaffeineString, totalCupsToday).
• Migration naming: the async API keeps the synchronous name and drops the completionHandler: parameter. The ClockKit async requirements drop the get…withHandler: prefix, so getCurrentTimelineEntry(for:withHandler:) becomes currentTimelineEntry(for:) (Starting Point/Coffee Tracker WatchKit Extension/ComplicationController.swift:39).
• Files: one primary type per file, named after the type. The exception is CoffeeData.swift, which also hosts the private actor and a fileprivate Array extension.

Architecture takeaways

• Isolate state, not threads. The migration replaced one serial queue and manual DispatchQueue.main hops with three explicit isolation domains: the main actor for UI state, CoffeeDataStore for disk state, and HealthKitController for HealthKit state.
• Make the UI model @MainActor and narrow its writers with private(set). This turned a runtime assert(Thread.main == …) into a compile-time requirement to await into the model.
• Use SDK async overloads where they exist, and wrap the remaining callback API with one checked continuation that resumes on every path.
• Effects previously hidden in didSet became explicit await drinksUpdated() calls, so the ordering of mutation, complication reload, and save is visible at each call site.
• Unstructured Task {} calls are fire-and-forget here. No owner retains or cancels them. A larger app would need an owner for task lifetime.

Source map

• Official Apple documentation