[Concurrency] API stubs: Task.Handle, priority and runDetached

Author: ktoso

stdlib/public/Concurrency/Task.swift

@@ -28,6 +28,142 @@ import Swift
 public struct Task {
 }
 
+// ==== Task Priority ----------------------------------------------------------
+
+extension Task {
+  public struct Priority: Comparable {
+    public static let `default`: Task.Priority = .init() // TODO: replace with actual values
+
+    // TODO: specifics of implementation are not decided yet
+    let __value: Int = 0
+
+    public static func < (lhs: Self, rhs: Self) -> Bool {
+      lhs.__value < rhs.__value
+    }
+  }
+}
+
+// ==== Task Handle ------------------------------------------------------------
+
+extension Task {
+
+  /// A task handle refers to an in-flight `Task`, allowing for (potentially)
+  /// awaiting for its result or potentially canceling it.
+  public final class Handle<Success, Failure: Error> {
+
+    /// Wait for the task to complete, returning (or throwing) its result.
+    ///
+    /// ### Priority
+    /// If the task has not completed yet, its priority will be elevated to the
+    /// priority of the current task. Note that this may not be as effective as
+    /// creating the task with the "right" priority to in the first place.
+    public func get() async throws -> Success {
+    fatalError("\(#function) not implemented yet.")
+  }
+
+  /// Attempt to cancel the task.
+  ///
+  /// Whether this function has any effect is task-dependent.
+  ///
+  /// For a task to respect cancellation it must cooperatively check for it
+  /// while running. Many tasks will check for cancellation before beginning
+  /// their "actual work", however this is not a requirement nor is it guaranteed
+  /// how and when tasks check for cancellation in general.
+  public func cancel() {
+    fatalError("\(#function) not implemented yet.")
+  }
+}
+}
+
+extension Task.Handle where Failure == Never {
+  /// Wait for the task to complete, returning its result.
+  ///
+  /// ### Priority
+  /// If the task has not completed yet, its priority will be elevated to the
+  /// priority of the current task. Note that this may not be as effective as
+  /// creating the task with the "right" priority to in the first place.
+  public func get() async -> Success {
+  fatalError("\(#function) not implemented yet.")
+}
+}
+
+// ==== Detached Tasks ---------------------------------------------------------
+
+extension Task {
+  /// Run given `operation` as part of a new top-level task.
+  ///
+  /// Creating detached tasks should, generally, be avoided in favor of using
+  /// `async` functions, `async let` declarations and `await` expressions - as
+  /// those benefit from structured, bounded concurrency which is easier to reason
+  /// about, as well as automatically inheriting the parent tasks priority,
+  /// task-local storage, deadlines, as well as being cancelled automatically
+  /// when their parent task is cancelled. Detached tasks do not get any of those
+  /// benefits, and thus should only be used when an operation is impossible to
+  /// be modelled with child tasks.
+  ///
+  /// ### Cancellation
+  /// A detached task always runs to completion unless it is explicitly cancelled.
+  /// Specifically, dropping a detached tasks `Task.Handle` does _not_ automatically
+  /// cancel given task.
+  ///
+  /// Canceling a task must be performed explicitly via `handle.cancel()`.
+  ///
+  /// - Parameters:
+  ///   - priority: priority of the task TODO: reword and define more explicitly once we have priorities well-defined
+  ///   - operation:
+  /// - Returns: handle to the task, allowing to `await handle.get()` on the
+  ///     tasks result or `cancel` it.
+  ///
+  /// - Note: it is generally preferable to use child tasks rather than detached
+  ///   tasks. Child tasks automatically carry priorities, task-local state,
+  ///   deadlines and have other benefits resulting from the structured
+  ///   concurrency concepts that they model. Consider using detached tasks only
+  ///   when strictly necessary and impossible to model operations otherwise.
+  public static func runDetached<T>(
+    priority: Priority = .default,
+    operation: () async -> T
+  ) -> Handle<T, Never> {
+    fatalError("\(#function) not implemented yet.")
+  }
+
+  /// Run given throwing `operation` as part of a new top-level task.
+  ///
+  /// Creating detached tasks should, generally, be avoided in favor of using
+  /// `async` functions, `async let` declarations and `await` expressions - as
+  /// those benefit from structured, bounded concurrency which is easier to reason
+  /// about, as well as automatically inheriting the parent tasks priority,
+  /// task-local storage, deadlines, as well as being cancelled automatically
+  /// when their parent task is cancelled. Detached tasks do not get any of those
+  /// benefits, and thus should only be used when an operation is impossible to
+  /// be modelled with child tasks.
+  ///
+  /// ### Cancellation
+  /// A detached task always runs to completion unless it is explicitly cancelled.
+  /// Specifically, dropping a detached tasks `Task.Handle` does _not_ automatically
+  /// cancel given task.
+  ///
+  /// Canceling a task must be performed explicitly via `handle.cancel()`.
+  ///
+  /// - Parameters:
+  ///   - priority: priority of the task TODO: reword and define more explicitly once we have priorities well-defined
+  ///   - operation:
+  /// - Returns: handle to the task, allowing to `await handle.get()` on the
+  ///     tasks result or `cancel` it. If the operation fails the handle will
+  ///     throw the error the operation has thrown when awaited on.
+  ///
+  /// - Note: it is generally preferable to use child tasks rather than detached
+  ///   tasks. Child tasks automatically carry priorities, task-local state,
+  ///   deadlines and have other benefits resulting from the structured
+  ///   concurrency concepts that they model. Consider using detached tasks only
+  ///   when strictly necessary and impossible to model operations otherwise.
+  public static func runDetached<T>(
+    priority: Priority = .default,
+    operation: () async throws -> T
+  ) -> Handle<T, Error> {
+    fatalError("\(#function) not implemented yet.")
+  }
+}
+
 // ==== UnsafeContinuation -----------------------------------------------------
 
 extension Task {

test/Concurrency/async_tasks.swift

@@ -2,7 +2,9 @@
 // REQUIRES: concurrency
 
 func someAsyncFunc() async -> String { "" }
+
 struct MyError: Error {}
+func someThrowingAsyncFunc() async throws -> String { throw MyError() }
 
 // non-async function with "weird shape" representing some API that has not adopted
 // swift concurrency yet, but we want to call it from an async function and make it
@@ -37,3 +39,26 @@ func test_unsafeThrowingContinuations() async {
 
   // TODO: Potentially could offer some warnings if we know that a continuation was resumed or escaped at all in a closure?
 }
+
+// ==== Detached Tasks ---------------------------------------------------------
+
+func test_detached() async {
+  let handle = Task.runDetached() {
+    await someAsyncFunc() // able to call async functions
+  }
+
+  let result: String = await handle.get()
+  _ = result
+}
+
+func test_detached_throwing() async -> String {
+  let handle: Task.Handle<String, Error> = Task.runDetached() {
+    await try someThrowingAsyncFunc() // able to call async functions
+  }
+
+  do {
+    return await try handle.get()
+  } catch {
+    print("caught: \(error)")
+  }
+}