Merge pull request swiftlang#87082 from jamieQ/astream-cancel-docs

[NFC][Concurrency]: add note about deadlock risk for AsyncStream.onTermination

Author: FranzBusch

stdlib/public/Concurrency/AsyncStream.swift

@@ -218,6 +218,11 @@ public struct AsyncStream<Element> {
     /// needed cleanup in the cancellation handler. After reaching a terminal
     /// state as a result of cancellation, the `AsyncStream` sets the callback
     /// to `nil`.
+    ///
+    /// - Note: Because the system might call the `onTermination` callback as
+    /// part of task cancellation, it's subject to the same considerations for
+    /// avoiding deadlock as outlined in the documentation for
+    /// ``withTaskCancellationHandler(operation:onCancel:)``.
     public var onTermination: (@Sendable (Termination) -> Void)? {
       get {
         return storage.getOnTermination()
@@ -329,7 +334,10 @@ public struct AsyncStream<Element> {
   ///         print(random)
   ///     }
   ///
-  ///
+  /// - Note: Because the system might call the `onCancel` callback as
+  /// part of task cancellation, it's subject to the same considerations for
+  /// avoiding deadlock as outlined in the documentation for
+  /// ``withTaskCancellationHandler(operation:onCancel:)``.
   @_silgen_name("$sScS9unfolding8onCancelScSyxGxSgyYac_yyYbcSgtcfC")
   @preconcurrency // Original API had `@Sendable` only on `onCancel`
   public init(

stdlib/public/Concurrency/AsyncThrowingStream.swift

@@ -242,6 +242,11 @@ public struct AsyncThrowingStream<Element, Failure: Error> {
     /// iterator. This means that you can perform needed cleanup in the
     ///  cancellation handler. After reaching a terminal state, the
     ///  `AsyncThrowingStream` disposes of the callback.
+    ///
+    /// - Note: Because the system might call the `onTermination` callback as
+    /// part of task cancellation, it's subject to the same considerations for
+    /// avoiding deadlock as outlined in the documentation for
+    /// ``withTaskCancellationHandler(operation:onCancel:)``.
     public var onTermination: (@Sendable (Termination) -> Void)? {
       get {
         return storage.getOnTermination()