Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/jvm/src/ThreadContextElement.kt (Kotlin)

Code before:
 *         return TraceContextElement(traceThreadLocal.get()?.copy())
 *     }
 *
 *     override fun mergeForChild(overwritingElement: CoroutineContext.Element): CoroutineContext {
 *         // Merge operation defines how to handle situations when both
 *         // the parent coroutine has an element in the context and
 *         // an element with the same key was also
 *         // explicitly passed to the child coroutine.
 *         // If merging does not require special behavior,
 *         // the copy of the element can be returned.
 *         return TraceContextElement(traceThreadLocal.get()?.copy())
 *     }
 * }
 * ```
 *
 * 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 implementation of this interface should be reentrant and expect
 * that [updateThreadContext] can be invoked multiple times prior to matching [restoreThreadContext],
 * but it is guaranteed that every update will eventually receive its matching [restoreThreadContext].
 *
 * Even though an element is copied for each child coroutine, an implementation should be ready for 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
 * ```
 *
 * All implementations of [CopyableThreadContextElement] should be thread-safe and guard their internal mutable state
 * within an element accordingly.
 */
@DelicateCoroutinesApi
@ExperimentalCoroutinesApi
public interface CopyableThreadContextElement<S> : ThreadContextElement<S> {

    /**
     * Returns a [CopyableThreadContextElement] to replace `this` `CopyableThreadContextElement` in the child
     * coroutine's context that is under construction if the added context does not contain an element with the same [key].
     *
     * This function is called on the element each time a new coroutine inherits a context containing it,
     * and the returned value is folded into the context given to the child.
     *

Review comment (suggestion):
```suggestion
 * interleaving when a coroutine with the corresponding element is launched on a multithreaded dispatcher:
```

Code after:
 *     }
 *
 *     override fun mergeForChild(overwritingElement: CoroutineContext.Element): CoroutineContext {
 *         // Merge operation defines how to handle situations when both
 *         // the parent coroutine has an element in the context and
 *         // an element with the same key was also
 *         // explicitly passed to the child coroutine.
 *         // If merging does not require special behavior,
 *         // the copy of the element can be returned.
 *         return TraceContextElement(traceThreadLocal.get()?.copy())
 *     }
 * }
 * ```
 *
 * 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
public interface CopyableThreadContextElement<S> : ThreadContextElement<S> {

    /**
     * Returns a [CopyableThreadContextElement] to replace `this` `CopyableThreadContextElement` in the child
     * coroutine's context that is under construction if the added context does not contain an element with the same [key].
     *
     * This function is called on the element each time a new coroutine inherits a context containing it,
     * and the returned value is folded into the context given to the child.
     *
     * Since this method is called whenever a new coroutine is launched in a context containing this
     * [CopyableThreadContextElement], implementations are performance-sensitive.