Example Executable (#23)

* Example Executable

This is a concept of an example-hosting executable. It includes some static variable usage to help get a feel for how something like this could be structured.

I really wanted to construct a `Package.swift` that could build the executable with three possible configurations:

- Swift 5 compiler (5 mode)
- Swift 6 compiler (5 mode)
- Swift 6 compiler (6 mode)

This turned out to be pretty tricky to pull off, but I have it working. SPM will not let you use the same path for multiple targets, but I also was able to avoid duplicating the code by using symlinks.

* Boundary crossing examples

* Package better-suited to examples

* More isolation crossing examples

* remove some test code that snuck in

* Correct implicit Sendable conformance comment

* Highlight RBI

* Use 6.0 tools

* whitespace *sobs*

* add todo about withCheckedContinuation usage

* Rmove use of 'globally isolated'

* Improve wording of not-Sendable-when-public

* move indentation to spaces

Author: mattmassicotte

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version: 5.10
+// swift-tools-version: 6.0
 
 import PackageDescription
 
@@ -14,31 +14,31 @@ let package = Package(
     ],
     products: [
         .library(
-            name: "FullyMigratedModule",
-            targets: [
-                "FullyMigratedModule",
-                "MigrationInProgressModule",
-            ]
+            name: "Library",
+            targets: ["Library"]
         ),
+        .executable(name: "swift5_examples", targets: ["Swift5Examples"]),
+        .executable(name: "swift6_examples", targets: ["Swift6Examples"]),
     ],
     targets: [
         .target(
-            name: "FullyMigratedModule"
+            name: "Library"
         ),
         .target(
-            name: "MigrationInProgressModule",
-            dependencies: ["FullyMigratedModule"]
+            name: "ObjCLibrary",
+            publicHeadersPath: "."
+        ),
+        .executableTarget(
+            name: "Swift5Examples",
+            dependencies: ["Library"],
+            swiftSettings: [
+                .swiftLanguageVersion(.v5)
+            ]
         ),
+        .executableTarget(
+            name: "Swift6Examples",
+            dependencies: ["Library"]
+        )
     ],
-    swiftLanguageVersions: [.v5]
+    swiftLanguageVersions: [.v6]
 )
-
-let swiftSettings: [SwiftSetting] = [
-    .enableExperimentalFeature("StrictConcurrency")
-]
-
-for target in package.targets {
-    var settings = target.swiftSettings ?? []
-    settings.append(contentsOf: swiftSettings)
-    target.swiftSettings = settings
-}

[email protected]

@@ -0,0 +1,104 @@
+import Library
+
+// MARK: Core Example Problem
+
+/// A `MainActor`-isolated function that accepts non-`Sendable` parameters.
+@MainActor
+func applyBackground(_ color: ColorComponents) {
+}
+
+#if swift(<6.0)
+/// A non-isolated function  that accepts non-`Sendable` parameters.
+func updateStyle(backgroundColor: ColorComponents) async {
+    // the `backgroundColor` parameter is being moved from the
+    // non-isolated domain to the `MainActor` here.
+    //
+    // Swift 5 Warning: passing argument of non-sendable type 'ColorComponents' into main actor-isolated context may introduce data races
+    // Swift 6 Error: sending 'backgroundColor' risks causing data races
+    await applyBackground(backgroundColor)
+}
+#endif
+
+// MARK: Latent Isolation
+
+/// MainActor-isolated function that accepts non-`Sendable` parameters.
+@MainActor
+func isolatedFunction_updateStyle(backgroundColor: ColorComponents) async {
+    // This is safe because backgroundColor cannot change domains. It also
+    // now no longer necessary to await the call to `applyBackground`.
+    applyBackground(backgroundColor)
+}
+
+// MARK: Explicit Sendable
+
+/// An overload used by `sendable_updateStyle` to match types.
+@MainActor
+func applyBackground(_ color: SendableColorComponents) {
+}
+
+/// The Sendable variant is safe to pass across isolation domains.
+func sendable_updateStyle(backgroundColor: SendableColorComponents) async {
+    await applyBackground(backgroundColor)
+}
+
+// MARK: Computed Value
+
+/// A Sendable function is used to compute the value in a different isolation domain.
+func computedValue_updateStyle(using backgroundColorProvider: @Sendable () -> ColorComponents) async {
+#if swift(<6.0)
+    // pass backgroundColorProvider into the MainActor here
+    await MainActor.run {
+        // invoke it in this domain to actually create the needed value
+        let components = backgroundColorProvider()
+        applyBackground(components)
+    }
+#else
+    // The Swift 6 compiler can automatically determine this value is
+    // being transferred in a safe way
+    let components = backgroundColorProvider()
+    await applyBackground(components)
+#endif
+}
+
+// MARK: Global Isolation
+/// An overload used by `globalActorIsolated_updateStyle` to match types.
+@MainActor
+func applyBackground(_ color: GlobalActorIsolatedColorComponents) {
+}
+
+/// MainActor-isolated function that accepts non-`Sendable` parameters.
+@MainActor
+func globalActorIsolated_updateStyle(backgroundColor: GlobalActorIsolatedColorComponents) async {
+    // This is safe because backgroundColor cannot change domains. It also
+    // now no longer necessary to await the call to `applyBackground`.
+    applyBackground(backgroundColor)
+}
+
+func exerciseBoundaryCrossingExamples() async {
+    print("Isolation Boundary Crossing Examples")
+    
+#if swift(<6.0)
+    print("  - updateStyle(backgroundColor:) passing its argument unsafely")
+#endif
+
+    print("  - using ColorComponents only from the main actor")
+    let t1 = Task { @MainActor in
+        let components = ColorComponents()
+
+        await isolatedFunction_updateStyle(backgroundColor: components)
+    }
+
+    await t1.value
+
+    print("  - using preconcurrency_updateStyle to deal with non-Sendable argument")
+
+    print("  - using a Sendable closure to defer creation")
+    await computedValue_updateStyle(using: {
+        ColorComponents()
+    })
+
+    print("  - using a globally-isolated type")
+    let components = await GlobalActorIsolatedColorComponents()
+
+    await globalActorIsolated_updateStyle(backgroundColor: components)
+}

Sources/Examples/Boundaries.swift

@@ -0,0 +1,13 @@
+import Dispatch
+
+extension DispatchQueue {
+    /// Returns once any pending work has been completed.
+    func pendingWorkComplete() async {
+        // TODO: update to withCheckedContinuation https://github.com/apple/swift/issues/74206
+        await withUnsafeContinuation { continuation in
+            self.async(flags: .barrier) {
+                continuation.resume()
+            }
+        }
+    }
+}

Sources/Examples/DispatchQueue+PendingWork.swift

@@ -0,0 +1,59 @@
+import Dispatch
+
+#if swift(<6.0)
+/// An unsafe global variable.
+///
+/// See swift-6-concurrency-migration-guide/commonproblems/#Sendable-Types
+var supportedStyleCount = 42
+#endif
+
+/// Version of `supportedStyleCount` that uses global-actor isolation.
+@MainActor
+var globallyIsolated_supportedStyleCount = 42
+
+/// Version of `supportedStyleCount` that uses immutability.
+let constant_supportedStyleCount = 42
+
+/// Version of `supportedStyleCount` that uses manual synchronization via `sharedQueue`
+nonisolated(unsafe) var queueProtected_supportedStyleCount = 42
+
+/// A non-isolated async function used to exercise all of the global mutable state examples.
+func exerciseGlobalExamples() async {
+    print("Global Variable Examples")
+#if swift(<6.0)
+    // Here is how we access `supportedStyleCount` concurrently in an unsafe way
+    for _ in 0..<10 {
+        DispatchQueue.global().async {
+            supportedStyleCount += 1
+        }
+    }
+
+    print("  - accessing supportedStyleCount unsafely:", supportedStyleCount)
+
+    await DispatchQueue.global().pendingWorkComplete()
+#endif
+    
+    print("  - accessing globallyIsolated_supportedStyleCount")
+    // establish a MainActor context to access the globally-isolated version
+    await MainActor.run {
+        globallyIsolated_supportedStyleCount += 1
+    }
+
+    // freely access the immutable version from any isolation domain
+    print("  - accessing constant_supportedStyleCount when non-isolated: ", constant_supportedStyleCount)
+
+    await MainActor.run {
+        print("  - accessing constant_supportedStyleCount from MainActor: ", constant_supportedStyleCount)
+    }
+
+    // access the manually-synchronized version... carefully
+    manualSerialQueue.async {
+        queueProtected_supportedStyleCount += 1
+    }
+
+    manualSerialQueue.async {
+        print("  - accessing queueProtected_supportedStyleCount: ", queueProtected_supportedStyleCount)
+    }
+
+    await manualSerialQueue.pendingWorkComplete()
+}

Sources/Examples/Globals.swift

@@ -0,0 +1,8 @@
+@preconcurrency import Library
+
+/// A non-isolated function  that accepts non-`Sendable` parameters.
+func preconcurrency_updateStyle(backgroundColor: ColorComponents) async {
+    // Swift 5: no diagnostics
+    // Swift 6 Warning: sending 'backgroundColor' risks causing data races
+    await applyBackground(backgroundColor)
+}

Sources/Examples/PreconcurrencyImport.swift

@@ -0,0 +1,8 @@
+import Dispatch
+
+/// A Serial queue uses for manual synchronization
+let manualSerialQueue = DispatchQueue(label: "com.apple.SwiftMigrationGuide")
+
+// Note: top-level code provides an asynchronous MainActor-isolated context
+await exerciseGlobalExamples()
+await exerciseBoundaryCrossingExamples()

Sources/Examples/main.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+/// An example of a struct with only `Sendable` properties.
+///
+/// This type is **not** Sendable because it is public. If we want a public type to be `Sendable`, we must annotate it explicitly.
+public struct ColorComponents {
+    public let red: Float
+    public let green: Float
+    public let blue: Float
+
+    public init(red: Float, green: Float, blue: Float) {
+        self.red = red
+        self.green = green
+        self.blue = blue
+    }
+
+    public init() {
+        self.red = 1.0
+        self.green = 1.0
+        self.blue = 1.0
+    }
+}
+
+/// Explicitly-Sendable variant of `ColorComponents`.
+public struct SendableColorComponents : Sendable {
+    public let red: Float = 1.0
+    public let green: Float = 1.0
+    public let blue: Float = 1.0
+
+    public init() {}
+}
+
+@MainActor
+public struct GlobalActorIsolatedColorComponents : Sendable {
+    public let red: Float = 1.0
+    public let green: Float = 1.0
+    public let blue: Float = 1.0
+
+    public init() {}
+}

Sources/FullyMigratedModule/FullyMigratedModule.swift

@@ -0,0 +1,10 @@
+@import Foundation;
+
+@interface OCMPattern : NSObject
+
+@end
+
+NS_SWIFT_UI_ACTOR
+@interface PCMPatternStore : NSObject
+
+@end

Sources/Library/Library.swift

@@ -0,0 +1,11 @@
+#import <Foundation/Foundation.h>
+
+#import "ObjCLibrary.h"
+
+@implementation OCMPattern
+
+@end
+
+@implementation PCMPatternStore
+
+@end

Sources/MigrationInProgressModule/MigrationInProgressModule.swift

@@ -0,0 +1 @@
+Examples

Sources/ObjCLibrary/ObjCLibrary.h

@@ -0,0 +1 @@
+Examples