bring back optional TaskExecutor param; introduce global var executor

Author: ktoso

stdlib/public/Concurrency/CMakeLists.txt

@@ -107,6 +107,7 @@ set(SWIFT_RUNTIME_CONCURRENCY_SWIFT_SOURCES
   AsyncThrowingMapSequence.swift
   AsyncThrowingPrefixWhileSequence.swift
   GlobalActor.swift
+  GlobalConcurrentExecutor.swift
   MainActor.swift
   PartialAsyncTask.swift
   SourceCompatibilityShims.swift

stdlib/public/Concurrency/Executor.swift

@@ -113,8 +113,8 @@ public protocol SerialExecutor: Executor {
 /// requirements.
 ///
 /// By setting a task executor preference, either with a
-/// ``_withTaskExecutor(_:operation:)``, creating a task with a preference
-/// (`Task(_on:)`, or `group.addTask(on:)`), the task and all of its child
+/// ``_withTaskExecutorPreference(_:operation:)``, creating a task with a preference
+/// (`Task(_executorPreference:)`, or `group.addTask(executorPreference:)`), the task and all of its child
 /// tasks (unless a new preference is set) will be preferring to execute on
 /// the provided task executor.
 ///
@@ -375,9 +375,8 @@ internal func _task_serialExecutor_getExecutorRef<E>(_ executor: E) -> Builtin.E
 @_unavailableInEmbedded
 @available(SwiftStdlib 9999, *)
 @_silgen_name("_task_executor_getTaskExecutorRef")
-internal func _task_executor_getTaskExecutorRef<E>(_ executor: E) -> Builtin.Executor
-    where E: _TaskExecutor {
-  return executor.asUnownedTaskExecutor().executor
+internal func _task_executor_getTaskExecutorRef(_ taskExecutor: any _TaskExecutor) -> Builtin.Executor {
+  return taskExecutor.asUnownedTaskExecutor().executor
 }
 
 // Used by the concurrency runtime

stdlib/public/Concurrency/GlobalConcurrentExecutor.swift

@@ -0,0 +1,65 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Swift
+@_implementationOnly import _SwiftConcurrencyShims
+
+// None of _TaskExecutor APIs are available in task-to-thread concurrency model.
+#if !SWIFT_STDLIB_TASK_TO_THREAD_MODEL_CONCURRENCY
+
+/// The global concurrent executor that is used by default for Swift Concurrency
+/// tasks.
+///
+/// The executor's implementation is platform dependent.
+/// By default it uses a fixed size pool of threads and should not be used for
+/// blocking operations which do not guarantee forward progress as doing so may
+/// prevent other tasks from being executed and render the system unresponsive.
+///
+/// You may pass this executor explicitly to a ``Task`` initializer as a task
+/// executor preference, in order to ensure and document that task be executed
+/// on the global executor, instead e.g. inheriting the enclosing actor's
+/// executor. Refer to ``_withTaskExecutorPreference(_:operation:)`` for a
+/// detailed discussion of task executor preferences.
+///
+/// Customizing the global concurrent executor is currently not supported.
+@available(SwiftStdlib 9999, *)
+public var globalConcurrentExecutor: any _TaskExecutor {
+  get {
+    _DefaultGlobalConcurrentExecutor.shared
+  }
+  // TODO: introduce a set {} once we are ready to allow customizing the
+  //       default global executor. This should be done the same for main actor
+}
+
+/// A task executor which enqueues all work on the default global concurrent
+/// thread pool that is used as the default executor for Swift concurrency
+/// tasks.
+@available(SwiftStdlib 9999, *)
+internal final class _DefaultGlobalConcurrentExecutor: _TaskExecutor {
+  public static let shared: _DefaultGlobalConcurrentExecutor = .init()
+
+  private init() {}
+
+  public func enqueue(_ job: consuming ExecutorJob) {
+    _enqueueJobGlobal(job.context)
+  }
+
+  public func asUnownedTaskExecutor() {
+    // The "default global concurrent executor" is simply the "undefined" one.
+    // We represent it as the `(0, 0)` ExecutorRef and it is handled properly
+    // by the runtime, without having to call through to the
+    // `_DefaultGlobalConcurrentExecutor` declared in Swift.
+    UnownedTaskExecutor(_getUndefinedTaskExecutor())
+  }
+}
+
+#endif

stdlib/public/Concurrency/PartialAsyncTask.swift

@@ -121,7 +121,7 @@ public struct UnownedJob: Sendable {
   @available(SwiftStdlib 9999, *)
   @_alwaysEmitIntoClient
   @inlinable
-  public func runSynchronously(isolated serialExecutor: UnownedSerialExecutor,
+  public func runSynchronously(isolatedTo serialExecutor: UnownedSerialExecutor,
                                taskExecutor: UnownedTaskExecutor) {
     _swiftJobRunOnTaskExecutor(self, serialExecutor, taskExecutor)
   }

stdlib/public/Concurrency/Task+TaskExecutor.swift

@@ -29,6 +29,50 @@ import Swift
 /// Passing `nil` as executor means disabling any preference preference (if it was set) and the task hierarchy
 /// will execute without any executor preference until a different preference is set.
 ///
+/// ### Asynchronous function execution semantics in presence of task executor preferences
+/// The following diagram illustrates on which executor an `async` function will
+/// execute, in presence (or lack thereof) a task executor preference.
+///
+/// ```
+/// [ func / closure ] - /* where should it execute? */
+///                               |
+///                     +--------------+          +===========================+
+///           +-------- | is isolated? | - yes -> | actor has unownedExecutor |
+///           |         +--------------+          +===========================+
+///           |                                       |                |
+///           |                                      yes               no
+///           |                                       |                |
+///           |                                       v                v
+///           |                  +=======================+    /* task executor preference? */
+///           |                  | on specified executor |        |                   |
+///           |                  +=======================+       yes                  no
+///           |                                                   |                   |
+///           |                                                   |                   v
+///           |                                                   |    +==========================+
+///           |                                                   |    | default (actor) executor |
+///           |                                                   v    +==========================+
+///           v                                     +==============================+
+///  /* task executor preference? */ ---- yes ----> | on Task's preferred executor |
+///           |                                     +==============================+
+///           no
+///           |
+///           v
+///  +===============================+
+///  | on global concurrent executor |
+///  +===============================+
+/// ```
+///
+/// In short, without a task executor preference, `nonisolated async` functions
+/// will execute on the global concurrent executor. If a task executor preference
+/// is present, such `nonisolated async` functions will execute on the preferred
+/// task executor.
+///
+/// Isolated functions semantically execute on the actor they are isolated to,
+/// however if such actor does not declare a custom executor (it is a "default
+/// actor") in presence of a task executor preference, tasks executing on this
+/// actor will use the preferred executor as source of threads to run the task,
+/// while isolated on the actor.
+///
 /// ### Example
 ///
 ///     Task {
@@ -55,7 +99,7 @@ import Swift
 ///         async let x = ...
 ///         await withTaskGroup(of: Int.self) { group in
 ///           group.addTask { 7 } // child task executes on 'specific' executor
-///           group.addTask(on: .default) { 13 } // child task executes on default executor
+///           group.addTask(executorPreference: globalConcurrentExecutor) { 13 } // child task executes on default executor
 ///         }
 ///
 ///         // disable the task executor preference:
@@ -75,20 +119,24 @@ import Swift
 ///     }
 ///
 /// - Parameters:
-///   - executorPreference: the task executor to use as preferred task executor; if `nil` it is interpreted as "no preference"
+///   - preferredTaskExecutor: the task executor to use as preferred task executor; if `nil` it is interpreted as "no preference"
 ///   - operation: the operation to execute on the passed executor; if the executor was `nil`, this will execute on the default global concurrent executor.
 /// - Returns: the value returned from the `operation` closure
 /// - Throws: if the operation closure throws
 /// - SeeAlso: `_TaskExecutor`
 @_unavailableInEmbedded
 @available(SwiftStdlib 9999, *)
 @_unsafeInheritExecutor // calling withTaskExecutor MUST NOT perform the "usual" hop to global
-public func _withTaskExecutor<T: Sendable>(
-  _ taskExecutorPreference: some _TaskExecutor,
+public func _withTaskExecutorPreference<T: Sendable>(
+  _ taskExecutor: (any _TaskExecutor)?,
   operation: @Sendable () async throws -> T
   ) async rethrows -> T {
   let taskExecutorBuiltin: Builtin.Executor =
-    taskExecutorPreference.asUnownedTaskExecutor().executor
+    if let taskExecutor {
+      taskExecutor.asUnownedTaskExecutor().executor
+    } else {
+      globalConcurrentExecutor.asUnownedTaskExecutor().executor
+    }
 
   let record = _pushTaskExecutorPreference(taskExecutorBuiltin)
   defer {
@@ -101,44 +149,6 @@ public func _withTaskExecutor<T: Sendable>(
   return try await operation()
 }
 
-/// Default global concurrent pool TaskExecutor --------------------------------
-
-@available(SwiftStdlib 9999, *)
-extension _TaskExecutor where Self == DefaultConcurrentExecutor {
-
-  /// The default executor preference, setting it using ``withTaskExecutor(_:)``
-  /// is equivalent to disabling an existing task executor preference, or
-  /// stating that task now has "no task executor preference".
-  @available(SwiftStdlib 9999, *)
-  public static var `default`: DefaultConcurrentExecutor {
-    DefaultConcurrentExecutor.shared
-  }
-
-}
-
-/// A task executor which enqueues all work on the default global concurrent
-/// thread pool that is used as the default executor for Swift concurrency
-/// tasks.
-@available(SwiftStdlib 9999, *)
-public final class DefaultConcurrentExecutor: _TaskExecutor {
-  public static let shared: DefaultConcurrentExecutor = .init()
-
-  private init() {}
-
-  public func enqueue(_ job: consuming ExecutorJob) {
-    _enqueueJobGlobal(job.context)
-  }
-
-  public func asUnownedTaskExecutor() {
-    // The "default global concurrent executor" is simply the "undefined" one.
-    // We represent it as the `(0, 0)` ExecutorRef and it is handled properly
-    // by the runtime, without having to call through to the
-    // `DefaultConcurrentExecutor` declared in Swift.
-    UnownedTaskExecutor(_getUndefinedTaskExecutor())
-  }
-
-}
-
 /// Task with specified executor -----------------------------------------------
 
 @available(SwiftStdlib 9999, *)
@@ -150,7 +160,7 @@ extension Task where Failure == Never {
   /// This overload allows specifying a preferred ``_TaskExecutor`` on which
   /// the `operation`, as well as all child tasks created from this task will be
   /// executing whenever possible. Refer to ``_TaskExecutor`` for a detailed discussion
-  // of the effect of task executors on execution semantics of asynchronous code.
+  /// of the effect of task executors on execution semantics of asynchronous code.
   ///
   /// Use this function when creating asynchronous work
   /// that operates on behalf of the synchronous function that calls it.
@@ -169,14 +179,14 @@ extension Task where Failure == Never {
   /// it only makes it impossible for you to explicitly cancel the task.
   ///
   /// - Parameters:
-  ///   - executor: the preferred task executor for this task, and any child tasks created by it
+  ///   - taskExecutor: the preferred task executor for this task, and any child tasks created by it
   ///   - priority: The priority of the task.
   ///     Pass `nil` to use the priority from `Task.currentPriority`.
   ///   - operation: The operation to perform.
   @discardableResult
   @_alwaysEmitIntoClient
   public init(
-    _on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async -> Success
   ) {
@@ -189,9 +199,15 @@ extension Task where Failure == Never {
       isDiscardingTask: false)
 
     // Create the asynchronous task.
-    let taskExecutorRef = executor.asUnownedTaskExecutor()
+    let executorBuiltin: Builtin.Executor =
+    if let taskExecutor {
+      taskExecutor.asUnownedTaskExecutor().executor
+    } else {
+      globalConcurrentExecutor.asUnownedTaskExecutor().executor
+    }
+
     let (task, _) = Builtin.createAsyncTaskWithExecutor(
-      flags, taskExecutorRef.executor, operation)
+      flags, executorBuiltin, operation)
     self._task = task
     #else
     fatalError("Unsupported Swift compiler, missing support for BuiltinCreateAsyncTaskWithExecutor")
@@ -204,7 +220,7 @@ extension Task where Failure == Error {
   @discardableResult
   @_alwaysEmitIntoClient
   public init(
-    _on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async throws -> Success
   ) {
@@ -217,9 +233,14 @@ extension Task where Failure == Error {
       isDiscardingTask: false)
 
     // Create the asynchronous task.
-    let taskExecutorRef = executor.asUnownedTaskExecutor()
+    let executorBuiltin: Builtin.Executor =
+    if let taskExecutor {
+      taskExecutor.asUnownedTaskExecutor().executor
+    } else {
+      globalConcurrentExecutor.asUnownedTaskExecutor().executor
+    }
     let (task, _) = Builtin.createAsyncTaskWithExecutor(
-      flags, taskExecutorRef.executor, operation)
+      flags, executorBuiltin, operation)
     self._task = task
     #else
     fatalError("Unsupported Swift compiler, missing support for $BuiltinCreateAsyncTaskWithExecutor")
@@ -236,7 +257,7 @@ extension Task where Failure == Never {
   @_alwaysEmitIntoClient
   @available(*, unavailable, message: "Unavailable in task-to-thread concurrency model")
   public static func _detached(
-    on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async -> Success
   ) -> Task<Success, Failure> {
@@ -267,7 +288,7 @@ extension Task where Failure == Never {
   @discardableResult
   @_alwaysEmitIntoClient
   public static func _detached(
-    on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async -> Success
   ) -> Task<Success, Failure> {
@@ -280,9 +301,14 @@ extension Task where Failure == Never {
       isDiscardingTask: false)
 
     // Create the asynchronous task.
-    let taskExecutorRef = executor.asUnownedTaskExecutor()
+    let executorBuiltin: Builtin.Executor =
+      if let taskExecutor {
+        taskExecutor.asUnownedTaskExecutor().executor
+      } else {
+        globalConcurrentExecutor.asUnownedTaskExecutor().executor
+      }
     let (task, _) = Builtin.createAsyncTaskWithExecutor(
-      flags, taskExecutorRef.executor, operation)
+      flags, executorBuiltin, operation)
 
     return Task(task)
     #else
@@ -299,7 +325,7 @@ extension Task where Failure == Error {
   @_alwaysEmitIntoClient
   @available(*, unavailable, message: "Unavailable in task-to-thread concurrency model")
   public static func _detached(
-    on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async throws -> Success
   ) -> Task<Success, Failure> {
@@ -332,7 +358,7 @@ extension Task where Failure == Error {
   @discardableResult
   @_alwaysEmitIntoClient
   public static func _detached(
-    on executor: some _TaskExecutor,
+    _executorPreference taskExecutor: (any _TaskExecutor)?,
     priority: TaskPriority? = nil,
     operation: __owned @Sendable @escaping () async throws -> Success
   ) -> Task<Success, Failure> {
@@ -345,10 +371,14 @@ extension Task where Failure == Error {
       isDiscardingTask: false)
 
     // Create the asynchronous task.
-    // Create the asynchronous task.
-    let taskExecutorRef = executor.asUnownedTaskExecutor()
+    let executorBuiltin: Builtin.Executor =
+      if let taskExecutor {
+        taskExecutor.asUnownedTaskExecutor().executor
+      } else {
+        globalConcurrentExecutor.asUnownedTaskExecutor().executor
+      }
     let (task, _) = Builtin.createAsyncTaskWithExecutor(
-      flags, taskExecutorRef.executor, operation)
+      flags, executorBuiltin, operation)
 
     return Task(task)
     #else