Merge pull request swiftlang#67457 from mikeash/task-cancellation-deadlock-docs

[Concurrency] Warn about deadlock potential in withTaskCancellationHandler docs.

Author: mikeash

stdlib/public/Concurrency/TaskCancellation.swift

@@ -24,6 +24,13 @@ import Swift
 /// operation is running code that never checks for cancellation, a cancellation
 /// handler still runs and provides a chance to run some cleanup code.
 ///
+/// Cancellation handlers which acquire locks must take care to avoid deadlock.
+/// The cancellation handler may be invoked while holding internal locks
+/// associated with the task or other tasks.  Other operations on the task, such
+/// as resuming a continuation, may acquire these same internal locks.
+/// Therefore, if a cancellation handler must acquire a lock, other code should
+/// not cancel tasks or resume continuations while holding that lock.
+///
 /// Doesn't check for cancellation, and always executes the passed `operation`.
 ///
 /// The `operation` executes on the calling execution context and does not suspend by itself,