[Concurrency] Major cleanup of assert/precondition/assume isolated docs (#70800)

Co-authored-by: Alex Martini <amartini@apple.com>

Author: ktoso

stdlib/public/Concurrency/ExecutorAssertions.swift

@@ -20,8 +20,8 @@ import SwiftShims
 
 @available(SwiftStdlib 5.1, *)
 extension SerialExecutor {
-  /// Unconditionally if the current task is executing on the expected serial executor,
-  /// and if not crash the program offering information about the executor mismatch.
+  /// Stops program execution if the current task is not executing on this
+  /// serial executor.
   ///
   /// This function's effect varies depending on the build flag used:
   ///
@@ -32,9 +32,18 @@ extension SerialExecutor {
   /// * In `-O` builds (the default for Xcode's Release configuration), stops
   ///   program execution.
   ///
-  /// * In `-Ounchecked` builds, the optimizer may assume that this function is
-  ///   never called. Failure to satisfy that assumption is a serious
-  ///   programming error.
+  /// - Note: Because this check is performed against the actor's serial executor,
+  ///   if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed. From a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
+  ///
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default value is
+  ///           the file where this method was called.
+  ///   - line: The line number to print if the assertion fails The default value is
+  ///           the line where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -60,8 +69,8 @@ extension SerialExecutor {
 
 @available(SwiftStdlib 5.1, *)
 extension Actor {
-  /// Unconditionally if the current task is executing on the serial executor of the passed in `actor`,
-  /// and if not crash the program offering information about the executor mismatch.
+  /// Stops program execution if the current task is not executing on this
+  /// actor's serial executor.
   ///
   /// This function's effect varies depending on the build flag used:
   ///
@@ -72,9 +81,18 @@ extension Actor {
   /// * In `-O` builds (the default for Xcode's Release configuration), stops
   ///   program execution.
   ///
-  /// * In `-Ounchecked` builds, the optimizer may assume that this function is
-  ///   never called. Failure to satisfy that assumption is a serious
-  ///   programming error.
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed , as from a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
+  ///
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -100,8 +118,8 @@ extension Actor {
 
 @available(SwiftStdlib 5.1, *)
 extension GlobalActor {
-  /// Unconditionally if the current task is executing on the serial executor of the passed in `actor`,
-  /// and if not crash the program offering information about the executor mismatch.
+  /// Stops program execution if the current task is not executing on this
+  /// actor's serial executor.
   ///
   /// This function's effect varies depending on the build flag used:
   ///
@@ -112,9 +130,18 @@ extension GlobalActor {
   /// * In `-O` builds (the default for Xcode's Release configuration), stops
   ///   program execution.
   ///
-  /// * In `-Ounchecked` builds, the optimizer may assume that this function is
-  ///   never called. Failure to satisfy that assumption is a serious
-  ///   programming error.
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed , as from a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
+  ///
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -133,18 +160,30 @@ extension GlobalActor {
 
 @available(SwiftStdlib 5.1, *)
 extension SerialExecutor {
-  /// Performs an executor check in debug builds.
+  /// Stops program execution if the current task is not executing on this
+  /// serial executor.
+  ///
+  /// This function's effect varies depending on the build flag used:
   ///
   /// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
-  ///   configuration): If `condition` evaluates to `false`, stop program
-  ///   execution in a debuggable state after printing `message`.
+  ///   configuration), stops program execution in a debuggable state after
+  ///   printing `message`.
   ///
   /// * In `-O` builds (the default for Xcode's Release configuration),
-  ///   `condition` is not evaluated, and there are no effects.
+  ///   the isolation check is not performed and there are no effects.
+  ///
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed , as from a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
   ///
-  /// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
-  ///   may assume that it *always* evaluates to `true`. Failure to satisfy that
-  ///   assumption is a serious programming error.
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -170,18 +209,30 @@ extension SerialExecutor {
 
 @available(SwiftStdlib 5.1, *)
 extension Actor {
-  /// Performs an executor check in debug builds.
+  /// Stops program execution if the current task is not executing on this
+  /// actor's serial executor.
+  ///
+  /// This function's effect varies depending on the build flag used:
   ///
   /// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
-  ///   configuration): If `condition` evaluates to `false`, stop program
-  ///   execution in a debuggable state after printing `message`.
+  ///   configuration), stops program execution in a debuggable state after
+  ///   printing `message`.
   ///
   /// * In `-O` builds (the default for Xcode's Release configuration),
-  ///   `condition` is not evaluated, and there are no effects.
+  ///   the isolation check is not performed and there are no effects.
+  ///
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed , as from a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
   ///
-  /// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
-  ///   may assume that it *always* evaluates to `true`. Failure to satisfy that
-  ///   assumption is a serious programming error.
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -208,18 +259,30 @@ extension Actor {
 
 @available(SwiftStdlib 5.1, *)
 extension GlobalActor {
-  /// Performs an executor check in debug builds.
+  /// Stops program execution if the current task is not executing on this
+  /// actor's serial executor.
+  ///
+  /// This function's effect varies depending on the build flag used:
   ///
   /// * In playgrounds and `-Onone` builds (the default for Xcode's Debug
-  ///   configuration): If `condition` evaluates to `false`, stop program
-  ///   execution in a debuggable state after printing `message`.
+  ///   configuration), stops program execution in a debuggable state after
+  ///   printing `message`.
   ///
   /// * In `-O` builds (the default for Xcode's Release configuration),
-  ///   `condition` is not evaluated, and there are no effects.
+  ///   the isolation check is not performed and there are no effects.
   ///
-  /// * In `-Ounchecked` builds, `condition` is not evaluated, but the optimizer
-  ///   may assume that it *always* evaluates to `true`. Failure to satisfy that
-  ///   assumption is a serious programming error.
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   that actor's serial executor as its own ``Actor/unownedExecutor``--this
+  ///   check will succeed , as from a concurrency safety perspective, the
+  ///   serial executor guarantees mutual exclusion of those two actors.
+  ///
+  /// - Parameters:
+  ///   - message: The message to print if the assertion fails.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)
@@ -238,19 +301,47 @@ extension GlobalActor {
 
 @available(SwiftStdlib 5.1, *)
 extension Actor {
-  /// A safe way to synchronously assume that the current execution context belongs to the passed in actor.
+  /// Assume that the current task is executing on this actor's serial executor,
+  /// or stop program execution otherwise.
+  ///
+  /// You call this method to *assume and verify* that the currently
+  /// executing synchronous function is actually executing on the serial
+  /// executor of this actor.
+  ///
+  /// If that is the case, the operation is invoked with an `isolated` version
+  /// of the actor, allowing synchronous access to actor local state without
+  /// hopping through asynchronous boundaries.
+  ///
+  /// If the current context is not running on the actor's serial executor, or
+  /// if the actor is a reference to a remote actor, this method will crash
+  /// with a fatal error (similar to ``preconditionIsolated()``).
+  ///
+  /// Note that this check is performed against the passed in actor's serial
+  /// executor, meaning that if another actor uses the same serial executor--by
+  /// using that actor's ``Actor/unownedExecutor`` as its own
+  /// ``Actor/unownedExecutor``--this check will succeed, as from a concurrency
+  /// safety perspective, the serial executor guarantees mutual exclusion of
+  /// those two actors.
   ///
-  /// This API should only be used as last resort, when it is not possible to express the current
-  /// execution context definitely belongs to the specified actor in other ways. E.g. one may need to use
-  /// this in a delegate style API, where a synchronous method is guaranteed to be called by the
-  /// specified actor, however it is not possible to move this method as being declared on the specified actor.
+  /// This method can only be used from synchronous functions, as asynchronous
+  /// functions should instead perform a normal method call to the actor, which
+  /// will hop task execution to the target actor if necessary.
   ///
-  /// - Warning: If the current executor is *not* the expected serial executor, this function will crash.
+  /// - Note: This check is performed against the actor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   another actor's executor as its own ``Actor/unownedExecutor``
+  ///   --this check will succeed , as from a concurrency safety perspective,
+  ///   the serial executor guarantees mutual exclusion of those two actors.
   ///
-  /// Note that this check is performed against the passed in actor's serial executor, meaning that
-  /// if another actor uses the same serial executor--by using that actor's ``Actor/unownedExecutor``
-  /// as its own ``Actor/unownedExecutor``--this check will succeed, as from a concurrency safety
-  /// perspective, the serial executor guarantees mutual exclusion of those two actors.
+  /// - Parameters:
+  ///   - operation: the operation that will be executed if the current context
+  ///                is executing on the actors serial executor.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
+  /// - Returns: the return value of the `operation`
+  /// - Throws: rethrows the `Error` thrown by the operation if it threw
   @available(SwiftStdlib 5.1, *)
   #if !$Embedded
   @backDeployed(before: SwiftStdlib 5.9)

stdlib/public/Concurrency/MainActor.swift

@@ -101,19 +101,41 @@ extension MainActor {
 
 @available(SwiftStdlib 5.1, *)
 extension MainActor {
-  /// A safe way to synchronously assume that the current execution context belongs to the MainActor.
+  /// Assume that the current task is executing on the main actor's
+  /// serial executor, or stop program execution.
   ///
-  /// This API should only be used as last resort, when it is not possible to express the current
-  /// execution context definitely belongs to the main actor in other ways. E.g. one may need to use
-  /// this in a delegate style API, where a synchronous method is guaranteed to be called by the
-  /// main actor, however it is not possible to annotate this legacy API with `@MainActor`.
+  /// This method allows to *assume and verify* that the currently
+  /// executing synchronous function is actually executing on the serial
+  /// executor of the MainActor.
   ///
-  /// - Warning: If the current executor is *not* the MainActor's serial executor, this function will crash.
+  /// If that is the case, the operation is invoked with an `isolated` version
+  /// of the actor, / allowing synchronous access to actor local state without
+  /// hopping through asynchronous boundaries.
   ///
-  /// Note that this check is performed against the MainActor's serial executor, meaning that
-  /// if another actor uses the same serial executor--by using ``MainActor/sharedUnownedExecutor``
-  /// as its own ``Actor/unownedExecutor``--this check will succeed, as from a concurrency safety
-  /// perspective, the serial executor guarantees mutual exclusion of those two actors.
+  /// If the current context is not running on the actor's serial executor, or
+  /// if the actor is a reference to a remote actor, this method will crash
+  /// with a fatal error (similar to ``preconditionIsolated()``).
+  ///
+  /// This method can only be used from synchronous functions, as asynchronous
+  /// functions should instead perform a normal method call to the actor, which
+  /// will hop task execution to the target actor if necessary.
+  ///
+  /// - Note: This check is performed against the MainActor's serial executor,
+  ///   meaning that / if another actor uses the same serial executor--by using
+  ///   ``MainActor/sharedUnownedExecutor`` as its own
+  ///   ``Actor/unownedExecutor``--this check will succeed , as from a concurrency
+  ///   safety perspective, the serial executor guarantees mutual exclusion of
+  ///   those two actors.
+  ///
+  /// - Parameters:
+  ///   - operation: the operation that will be executed if the current context
+  ///                is executing on the MainActor's serial executor.
+  ///   - file: The file name to print if the assertion fails. The default is
+  ///           where this method was called.
+  ///   - line: The line number to print if the assertion fails The default is
+  ///           where this method was called.
+  /// - Returns: the return value of the `operation`
+  /// - Throws: rethrows the `Error` thrown by the operation if it threw
   @available(SwiftStdlib 5.1, *)
   @backDeployed(before: SwiftStdlib 5.9)
   @_unavailableFromAsync(message: "await the call to the @MainActor closure directly")