[docs] Provide more documentation on custom executors with global actors

It could be confusing to adopters who were led to believe by the types
that they should "just" implement the sharedUnownedExecutor property,
but insead they have to implement the unownedExecutor on the specific
actor type.

Adding documentation clarify this as well as a simple test that
exercises this explicitly; We seem to have much coverage of main actor,
but not so much of custom executor global actors.

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