Swift Concurrency Migration Guide

Adding @MainActor to protocols, types, or functions is generally source and ABI incompatible.

Protocols and types

Annotating a protocol or type with @MainActor is incompatible because the annotation can be inferred throughout client code (subclasses, extensions, etc.).

To resolve: Apply @preconcurrency to the declaration. However, if the annotation is inferred on extension methods in client code, @preconcurrency might not preserve ABI. In those cases, you may need to explicitly mark extension methods as nonisolated in the client library.

// In the client library, if P is retroactively @MainActor:
extension P {
  nonisolated public func onChange(action: @escaping @Sendable () -> Void)
}

Function declarations and types

Adding @MainActor to a function or a function type is incompatible.

To resolve: Apply @preconcurrency to the enclosing function declaration.

// Source and ABI incompatible
@MainActor public func runOnMain()

// Resolved with @preconcurrency
@preconcurrency @MainActor
public func runOnMain() { ... }

There are four primary ways to make a type Sendable:

1. Global Isolation: Mark the type with an actor (e.g., @MainActor). Accesses from other domains must be asynchronous.
2. Actors: Actors have implicit Sendable conformance. They provide their own isolation domain, allowing them to work with non-Sendable types internally.
3. Manual Synchronization: Use @unchecked Sendable for types that use existing synchronization primitives like DispatchQueue or locks.
4. Retroactive Conformance: Use extension Type: @retroactive @unchecked Sendable for types in dependencies. Use with extreme caution as it can break API contracts if the type isn't actually thread-safe.

// Manual Synchronization
class Style: @unchecked Sendable {
    private var background: ColorComponents
    private let queue: DispatchQueue
}

// Retroactive Conformance
extension ColorComponents: @retroactive @unchecked Sendable {}

Adding Sendable conformance to types and generic requirements has different impacts on compatibility.

Conformances on concrete types

Adding Sendable to a concrete type (including conditional conformances) is typically source and ABI compatible.

// Source and ABI compatible
public struct S: Sendable

Generic requirements

Adding a Sendable requirement to a generic type or function is source and ABI incompatible because it restricts the types clients can pass.

To resolve: Use @preconcurrency on the declaration to downgrade failures to warnings and preserve ABI.

// Source and ABI incompatible
public func generic<T> where T: Sendable

// Resolved with @preconcurrency
@preconcurrency
public func generic<T> where T: Sendable { ... }

Function types

Adding @Sendable to a function type is source and ABI incompatible.

To resolve: Apply @preconcurrency to the enclosing function declaration.

// Source and ABI incompatible
public func performConcurrently(completion: @escaping @Sendable () -> Void)

// Resolved with @preconcurrency
@preconcurrency
public func performConcurrently(completion: @escaping @Sendable () -> Void) { ... }

Swift uses isolation inference to establish isolation implicitly based on context.

Classes

• Subclasses: A subclass always inherits the same isolation as its parent. This isolation cannot be changed by the subclass.
• Members: The static isolation of a type is automatically inferred for its properties and methods.

Protocols

Protocol conformance can affect isolation depending on how it is applied:

• Type-level conformance: The inferred isolation applies to the entire type.
• Extension-level conformance: The inferred isolation only applies within the specific extension.
• Requirement-level isolation: Protocol requirements themselves can be marked with isolation (e.g., @MainActor func eat()).

Function Types and Closures

• Closures: By default, closures are isolated to the same context in which they are formed. This allows them to capture state or call isolated methods from the surrounding context.
• Task Inheritance: The Task initializer captures the static isolation of its enclosing scope. A task will inherit the isolation of its context (e.g., MainActor) unless an explicit global actor is provided.

@MainActor
class Animal {
    let name: String
    func eat(food: Pineapple) {}
}

class Chicken: Animal {} // Chicken is also @MainActor

@MainActor
protocol Feedable {
    func eat(food: Pineapple)
}

class Chicken: Feedable {} // Entire type is @MainActor

extension Pirate: Feedable {} // Only the extension is @MainActor

@MainActor
func eat(food: Pineapple) {
    Task {
        // Inherits MainActor isolation
        Chicken.prizedHen.eat(food: food)
    }

    Task { @MyGlobalActor in
        // Explicitly isolated to MyGlobalActor
    }
}

The sending keyword manages how non-sendable values are transferred across isolation boundaries.

Result types

Adding sending to a return type lifts restrictions in client code and is source and ABI compatible.

// Source and ABI compatible
public func getValue() -> sending NotSendable

Parameter types

Adding sending to a parameter is more restrictive for the caller and is source and ABI incompatible.

// Source and ABI incompatible
public func takeValue(_: sending NotSendable)

Replacing @Sendable with sending

Replacing an existing @Sendable closure parameter with sending is source compatible but ABI incompatible because it changes name mangling.

To resolve: Use @_silgen_name to preserve mangling. For all functions except initializers, use __shared sending to preserve the ownership convention.

// For standard functions
public func takeValue(_: __shared sending NotSendable)

// For initializers (no extra modifier needed)
public class C {
  public init(ns: sending NotSendable)
}