Merge pull request #74319 from ktoso/wip-global-custom-exec-docs

Author: ktoso

stdlib/public/Concurrency/GlobalActor.swift

@@ -22,6 +22,25 @@ import Swift
 /// such a declaration from another actor (or from nonisolated code),
 /// synchronization is performed through the shared actor instance to ensure
 /// mutually-exclusive access to the declaration.
+///
+/// ## Custom Actor Executors
+/// A global actor use a custom executor if it needs to customize its execution
+/// semantics, for example, by making sure all of its invocations are run on a
+/// specific thread or dispatch queue.
+///
+/// This is done the same way as with normal non-global actors, by declaring a
+/// ``Actor/unownedExecutor`` nonisolated property in the ``ActorType``
+/// underlying this global actor.
+///
+/// It is *not* necessary to override the ``sharedUnownedExecutor`` static
+/// property of the global actor, as its default implementation already
+/// delegates to the ``shared.unownedExecutor``, which is the most reasonable
+/// and correct implementation of this protocol requirement.
+///
+/// You can find out more about custom executors, by referring to the
+/// ``SerialExecutor`` protocol's documentation.
+///
+/// - SeeAlso: ``SerialExecutor``
 @available(SwiftStdlib 5.1, *)
 public protocol GlobalActor {
   /// The type of the shared actor instance that will be used to provide
@@ -36,10 +55,22 @@ public protocol GlobalActor {
   /// instance.
   static var shared: ActorType { get }
 
-  /// The shared executor instance that will be used to provide
-  /// mutually-exclusive access for the global actor.
+  /// Shorthand for referring to the `shared.unownedExecutor` of this global actor.
+  ///
+  /// When declaring a global actor with a custom executor, prefer to implement
+  /// the underlying actor's ``Actor/unownedExecutor`` property, and leave this
+  /// `sharedUnownedExecutor` default implementation in-place as it will simply
+  /// delegate to the `shared.unownedExecutor`.
+  ///
+  /// The value of this property must be equivalent to `shared.unownedExecutor`,
+  /// as may be used by the Swift concurrency runtime or explicit user code. with
+  /// that assumption in mind.
+  ///
+  /// Returning different executors for different invocations of this computed
+  /// property is also illegal, as it could lead to inconsistent synchronization
+  /// of the underlying actor.
   ///
-  /// The value of this property must be equivalent to `shared.unownedExecutor`.
+  /// - SeeAlso: ``SerialExecutor``
   static var sharedUnownedExecutor: UnownedSerialExecutor { get }
 }
 

test/Concurrency/Runtime/custom_executors.swift

@@ -27,6 +27,8 @@ actor Custom {
   }
 
   func report() async {
+    simple.preconditionIsolated() // we're supposed to be on the same executor as 'simple'
+
     print("custom.count == \(count)")
     count += 1
 

test/Concurrency/Runtime/custom_executors_globalActor.swift

@@ -0,0 +1,101 @@
+// RUN: %target-run-simple-swift( %import-libdispatch -strict-concurrency=complete -parse-as-library) | %FileCheck %s
+
+// REQUIRES: concurrency
+// REQUIRES: executable_test
+// REQUIRES: libdispatch
+// UNSUPPORTED: freestanding
+
+// UNSUPPORTED: back_deployment_runtime
+// REQUIRES: concurrency_runtime
+
+import Dispatch
+
+let globalQueue = DispatchQueue(label: "SimpleQueue")
+
+@available(SwiftStdlib 6.0, *)
+final class NaiveQueueExecutor: SerialExecutor {
+  public func enqueue(_ unowned: UnownedJob) {
+    globalQueue.sync {
+      unowned.runSynchronously(on: self.asUnownedSerialExecutor())
+    }
+  }
+
+  public func asUnownedSerialExecutor() -> UnownedSerialExecutor {
+    return UnownedSerialExecutor(ordinary: self)
+  }
+
+  func checkIsolated() {
+    // ok
+  }
+}
+
+@available(SwiftStdlib 6.0, *)
+actor Simple {
+  var count = 0
+  let exec = NaiveQueueExecutor()
+
+  func report() {
+    print("simple.count == \(count)")
+    count += 1
+  }
+
+  nonisolated var unownedExecutor: UnownedSerialExecutor {
+    print("Simple.unownedExecutor")
+    return exec.asUnownedSerialExecutor()
+  }
+}
+
+@globalActor
+@available(SwiftStdlib 6.0, *)
+actor MyGlobalActor {
+  static let simple = Simple()
+  static let shared = MyGlobalActor()
+
+  static var sharedUnownedExecutor: UnownedSerialExecutor {
+    print("MyGlobalActor.sharedUnownedExecutor")
+    return simple.unownedExecutor
+  }
+  nonisolated var unownedExecutor: UnownedSerialExecutor {
+    print("MyGlobalActor.unownedExecutor")
+    return Self.simple.unownedExecutor
+  }
+}
+
+@MyGlobalActor
+@available(SwiftStdlib 6.0, *)
+final class Custom {
+  var count = 0
+  let simple = MyGlobalActor.simple
+
+  nonisolated var unownedExecutor: UnownedSerialExecutor {
+    return simple.unownedExecutor
+  }
+
+  func report() async {
+    simple.preconditionIsolated()
+
+    print("custom.count == \(count)")
+    count += 1
+
+    await simple.report()
+  }
+}
+
+@available(SwiftStdlib 6.0, *)
+@main struct Main {
+  static func main() async {
+    print("begin")
+    let actor = Custom()
+    await actor.report()
+    print("end")
+  }
+}
+
+// CHECK:      begin
+// CHECK-NEXT: MyGlobalActor.unownedExecutor
+// CHECK-NEXT: Simple.unownedExecutor
+// CHECK-NEXT: Simple.unownedExecutor
+// CHECK-NEXT: custom.count == 0
+// CHECK-NEXT: Simple.unownedExecutor
+// CHECK-NEXT: simple.count == 0
+// CHECK-NEXT: end