Clarify implementation contract of ThreadContextElement and CopyableThreadContextElement (#3314)

Author: qwwdfsad

integration/kotlinx-coroutines-slf4j/src/MDCContext.kt

@@ -28,7 +28,7 @@ public typealias MDCContextMap = Map<String, String>?
  * }
  * ```
  *
- * Note that you cannot update MDC context from inside of the coroutine simply
+ * Note that you cannot update MDC context from inside the coroutine simply
  * using [MDC.put]. These updates are going to be lost on the next suspension and
  * reinstalled to the MDC context that was captured or explicitly specified in
  * [contextMap] when this object was created on the next resumption.

kotlinx-coroutines-core/jvm/src/ThreadContextElement.kt

@@ -48,6 +48,15 @@ import kotlin.coroutines.*
  * this coroutine suspends.
  *
  * To use [ThreadLocal] variable within the coroutine use [ThreadLocal.asContextElement][asContextElement] function.
+ *
+ * ### Reentrancy and thread-safety
+ *
+ * Correct implementations of this interface must expect that calls to [restoreThreadContext]
+ * may happen in parallel to the subsequent [updateThreadContext] and [restoreThreadContext] operations.
+ * See [CopyableThreadContextElement] for advanced interleaving details.
+ *
+ * All implementations of [ThreadContextElement] should be thread-safe and guard their internal mutable state
+ * within an element accordingly.
  */
 public interface ThreadContextElement<S> : CoroutineContext.Element {
     /**
@@ -133,6 +142,27 @@ public interface ThreadContextElement<S> : CoroutineContext.Element {
  *
  * A coroutine using this mechanism can safely call Java code that assumes the corresponding thread local element's
  * value is installed into the target thread local.
+ *
+ * ### Reentrancy and thread-safety
+ *
+ * Correct implementations of this interface must expect that calls to [restoreThreadContext]
+ * may happen in parallel to the subsequent [updateThreadContext] and [restoreThreadContext] operations.
+ *
+ * Even though an element is copied for each child coroutine, an implementation should be able to handle the following
+ * interleaving when a coroutine with the corresponding element is launched on a multithreaded dispatcher:
+ *
+ * ```
+ * coroutine.updateThreadContext() // Thread #1
+ * ... coroutine body ...
+ * // suspension + immediate dispatch happen here
+ * coroutine.updateThreadContext() // Thread #2, coroutine is already resumed
+ * // ... coroutine body after suspension point on Thread #2 ...
+ * coroutine.restoreThreadContext() // Thread #1, is invoked late because Thread #1 is slow
+ * coroutine.restoreThreadContext() // Thread #2, may happen in parallel with the previous restore
+ * ```
+ *
+ * All implementations of [CopyableThreadContextElement] should be thread-safe and guard their internal mutable state
+ * within an element accordingly.
  */
 @DelicateCoroutinesApi
 @ExperimentalCoroutinesApi