[Concurrency] Warn about deadlock potential in withTaskCancellationHandler docs.

withTaskCancellationHandler gets called with the task status record lock held, so care needs to be taken if the cancellation handler acquires any locks of its own. Update the docs comment to describe this.

rdar://111686260

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,