Include an queue-backed actor example (#101)

* Include an queue-backed actor example

* Comment out asUnownedSerialExecutor until compiler bug is addressed

Author: mattmassicotte

Guide.docc/IncrementalAdoption.md

@@ -254,6 +254,30 @@ class PersonalTransportation {
 }
 ```
 
+## Integrating DispatchSerialQueue with Actors
+
+By default, the mechanism actors use to schedule and execute work
+is system-defined.
+However you can override this to provide a custom implementation.
+The `DispatchSerialQueue` type includes built-in support for this facility.
+
+```swift
+actor LandingSite {
+    private let queue = DispatchSerialQueue(label: "something")
+
+    nonisolated var unownedExecutor: UnownedSerialExecutor {
+        queue.asUnownedSerialExecutor()
+    }
+
+    func acceptTransport(_ transport: PersonalTransportation) {
+        // this function will be running on queue
+    }
+}
+```
+
+This can be useful if you want to migrate a type towards the actor model
+while maintaining compatibility with code that depends on `DispatchQueue`.
+
 ## Backwards Compatibility
 
 It's important to keep in mind that static isolation, being part of the type
@@ -332,6 +356,7 @@ NS_SWIFT_ASYNC_NAME
 NS_SWIFT_ASYNC_NOTHROW
 NS_SWIFT_UNAVAILABLE_FROM_ASYNC(msg)
 ```
+
 ### Dealing with missing isolation annotations in Objective-C libraries
 
 While the SDKs and other Objective-C libraries make progress in adopting Swift concurrency,

Package.swift

@@ -34,15 +34,15 @@ let package = Package(
         ),
         .executableTarget(
             name: "Swift5Examples",
-            dependencies: ["Library"],
+            dependencies:  ["Library", "ObjCLibrary"],
             swiftSettings: [
                 .swiftLanguageVersion(.v5),
                 .enableUpcomingFeature("StrictConcurrency"),
             ]
         ),
         .executableTarget(
             name: "Swift6Examples",
-            dependencies: ["Library"]
+            dependencies: ["Library", "ObjCLibrary"]
         )
     ]
 )

Sources/Examples/IncrementalMigration.swift

@@ -0,0 +1,34 @@
+import Dispatch
+import ObjCLibrary
+
+/// Example that backs an actor with a queue.
+///
+/// > Note: `DispatchSerialQueue`'s initializer was only made available in more recent OS versions.
+@available(macOS 14.0, iOS 17.0, macCatalyst 17.0, tvOS 17.0, watchOS 10.0, *)
+actor LandingSite {
+    private let queue = DispatchSerialQueue(label: "SerialQueue")
+
+	// this currently failed to build because of the @available usage, rdar://116684282
+//    nonisolated var unownedExecutor: UnownedSerialExecutor {
+//        queue.asUnownedSerialExecutor()
+//    }
+
+    func acceptTransport(_ transport: JPKJetPack) {
+        // this function will be running on queue
+    }
+}
+
+func exerciseIncrementalMigrationExamples() async {
+    print("Incremental Migration Examples")
+
+    if #available(macOS 14.0, iOS 17.0, macCatalyst 17.0, tvOS 17.0, watchOS 10.0, *) {
+        print("  - using an actor with a DispatchSerialQueue executor")
+        let site = LandingSite()
+
+        let transport = JPKJetPack()
+
+        await site.acceptTransport(transport)
+        await site.acceptTransport(transport)
+        await site.acceptTransport(transport)
+    }
+}

Sources/Examples/main.swift

@@ -7,3 +7,4 @@ let manualSerialQueue = DispatchQueue(label: "com.apple.SwiftMigrationGuide")
 await exerciseGlobalExamples()
 await exerciseBoundaryCrossingExamples()
 await exerciseConformanceMismatchExamples()
+await exerciseIncrementalMigrationExamples()