Document withTimeout*, produce

Author: dkhalanskyjb

kotlinx-coroutines-core/common/src/CoroutineScope.kt

@@ -836,7 +836,8 @@ public object GlobalScope : CoroutineScope {
  * ```
  *
  * If cancellation during the acquisition of the resource is also undesired, the following pattern can be used
- * ([coroutineScope] is not needed here, as [withContext] defines its own [CoroutineScope], but :
+ * ([coroutineScope] would be meaningless here, as [withContext] defines its own [CoroutineScope],
+ * but another lexical scope like [supervisorScope] or [withContext] can be useful as part of this pattern):
  *
  * ```
  * withContext(NonCancellable) {

kotlinx-coroutines-core/common/src/Timeout.kt

@@ -14,26 +14,11 @@ import kotlin.time.*
 import kotlin.time.Duration.Companion.milliseconds
 
 /**
- * Runs a given suspending [block] of code inside a coroutine with a specified [timeout][timeMillis] and throws
- * a [TimeoutCancellationException] if the timeout was exceeded.
- * If the given [timeMillis] is non-positive, [TimeoutCancellationException] is thrown immediately.
+ * Shortcut for calling [withTimeout] with a [Duration] timeout of [timeMillis] milliseconds.
+ * Please see that overload for details.
  *
- * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
- * the cancellable suspending function inside the block throws a [TimeoutCancellationException].
- *
- * The sibling function that does not throw an exception on timeout is [withTimeoutOrNull].
- * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
- *
- * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside the block.
- * See the
- * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
- * section of the coroutines guide for details.
- *
- * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
- *
- * @param timeMillis timeout time in milliseconds.
+ * > Note: the behavior of this function can be different from [withTimeout] if [timeMillis] is greater than
+ * `Long.MAX_VALUE / 2` milliseconds.
  */
 public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineScope.() -> T): T {
     contract {
@@ -52,12 +37,9 @@ public suspend fun <T> withTimeout(timeMillis: Long, block: suspend CoroutineSco
  * If the [block] execution times out, it is cancelled with a [TimeoutCancellationException].
  * If the [timeout] is non-positive, this happens immediately and the [block] is not executed.
  *
- * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside the block.
- * See the
- * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
- * section of the coroutines guide for details.
+ * The cancellation on timeout is asynchronous with respect to the code running in the block
+ * and may happen at any time, even after the [block] finishes executing but before the caller gets resumed with
+ * the result.
  *
  * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
  *
@@ -160,26 +142,11 @@ public suspend fun <T> withTimeout(timeout: Duration, block: suspend CoroutineSc
 }
 
 /**
- * Runs a given suspending block of code inside a coroutine with a specified [timeout][timeMillis] and returns
- * `null` if this timeout was exceeded.
- * If the given [timeMillis] is non-positive, `null` is returned immediately.
- *
- * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
- * cancellable suspending function inside the block throws a [TimeoutCancellationException].
- *
- * The sibling function that throws an exception on timeout is [withTimeout].
- * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
- *
- * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside the block.
- * See the
- * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
- * section of the coroutines guide for details.
- *
- * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * Shortcut for calling [withTimeoutOrNull] with a [Duration] timeout of [timeMillis] milliseconds.
+ * Please see that overload for details.
  *
- * @param timeMillis timeout time in milliseconds.
+ * > Note: the behavior of this function can be different from [withTimeoutOrNull] if [timeMillis] is greater than
+ * `Long.MAX_VALUE / 2` milliseconds.
  */
 public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend CoroutineScope.() -> T): T? {
     if (timeMillis <= 0L) return null
@@ -201,24 +168,54 @@ public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend Corout
 }
 
 /**
- * Runs a given suspending block of code inside a coroutine with the specified [timeout] and returns
- * `null` if this timeout was exceeded.
- * If the given [timeout] is non-positive, `null` is returned immediately.
+ * Calls the specified suspending [block] with the specified [timeout], suspends until it completes,
+ * and returns the result.
+ *
+ * If the [block] execution times out, it is cancelled with a [TimeoutCancellationException].
+ * If the [timeout] is non-positive, this happens immediately and the [block] is not executed.
+ *
+ * The cancellation on timeout is asynchronous with respect to the code running in the block
+ * and may happen at any time, even after the [block] finishes executing but before the caller gets resumed with
+ * the result.
+ *
+ * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ *
+ * ## Structured Concurrency
+ *
+ * [withTimeoutOrNull] behaves like [coroutineScope], as it, too, creates a new *scoped child coroutine*.
+ * Refer to the documentation of [coroutineScope] for details.
  *
- * The code that is executing inside the [block] is cancelled on timeout and the active or next invocation of
- * cancellable suspending function inside the block throws a [TimeoutCancellationException].
+ * ## Pitfalls
+ *
+ * ### Cancellation is cooperative
  *
- * The sibling function that throws an exception on timeout is [withTimeout].
- * Note that the timeout action can be specified for a [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause.
+ * [withTimeoutOrNull] will not automatically stop all code inside it from being executed
+ * once the timeout gets triggered.
+ * It only cancels the running [block], but it's up to the [block] to notice that it was cancelled, for example,
+ * using [ensureActive], checking [isActive], or using [suspendCancellableCoroutine].
+ *
+ * For example, this JVM code will run to completion, taking 10 seconds to do so:
+ *
+ * ```
+ * withTimeout(1.seconds) {
+ *     Thread.sleep(10_000)
+ * }
+ * ```
  *
- * **The timeout event is asynchronous with respect to the code running in the block** and may happen at any time,
- * even right before the return from inside the timeout [block]. Keep this in mind if you open or acquire some
- * resource inside the [block] that needs closing or release outside the block.
- * See the
- * [Asynchronous timeout and resources](https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html#asynchronous-timeout-and-resources)
+ * On the JVM, use the `runInterruptible` function to propagate cancellations
+ * to blocking JVM code as thread interruptions.
+ *
+ * See the [Cancellation is cooperative](https://kotlinlang.org/docs/cancellation-and-timeouts.html#cancellation-is-cooperative).
  * section of the coroutines guide for details.
  *
- * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
+ * ### Returning closeable resources
+ *
+ * Values returned from [withTimeoutOrNull] will typically be lost if the caller is cancelled.
+ *
+ * See the corresponding section in the [coroutineScope] documentation for details.
+ *
+ * @see withTimeoutOrNull
+ * @see SelectBuilder.onTimeout
  */
 public suspend fun <T> withTimeoutOrNull(timeout: Duration, block: suspend CoroutineScope.() -> T): T? =
     withTimeoutOrNull(timeout.toDelayMillis(), block)

kotlinx-coroutines-core/common/src/channels/Produce.kt

@@ -75,14 +75,17 @@ public suspend fun ProducerScope<*>.awaitClose(block: () -> Unit = {}) {
  * and returns a reference to the coroutine as a [ReceiveChannel]. This resulting
  * object can be used to [receive][ReceiveChannel.receive] elements produced by this coroutine.
  *
- * The scope of the coroutine contains the [ProducerScope] interface, which implements
- * both [CoroutineScope] and [SendChannel], so that the coroutine can invoke [send][SendChannel.send] directly.
+ * The receiver of [block] is a [ProducerScope], which implements both [SendChannel] and [CoroutineScope].
+ * This allows invoking [send][SendChannel.send] directly from the [block] to send elements to the channel
+ * while treating [block] as a coroutine.
  *
  * The kind of the resulting channel depends on the specified [capacity] parameter.
  * See the [Channel] interface documentation for details.
  * By default, an unbuffered channel is created.
  * If an invalid [capacity] value is specified, an [IllegalArgumentException] is thrown.
  *
+ * ## Behavior specifics
+ *
  * ### Behavior on termination
  *
  * The channel is [closed][SendChannel.close] when the coroutine completes.
@@ -132,6 +135,19 @@ public suspend fun ProducerScope<*>.awaitClose(block: () -> Unit = {}) {
  * for (value in channel) { println(value) }
  * ```
  *
+ * The exception will not be considered uncaught even if the parent coroutine does not react to it
+ * (for example, because it has a [SupervisorJob]).
+ * This means that, in the following code, the exception will not be reported anywhere and needs to be handled
+ * manually by receiving from the resulting channel:
+ *
+ * ```
+ * supervisorScope {
+ *     produce<Int> {
+ *         throw IllegalStateException()
+ *     }
+ * }
+ * ```
+ *
  * When the coroutine is cancelled via structured concurrency and not the `cancel` function,
  * the channel does not automatically close until the coroutine completes,
  * so it is possible that some elements will be sent even after the coroutine is cancelled:
@@ -182,7 +198,36 @@ public suspend fun ProducerScope<*>.awaitClose(block: () -> Unit = {}) {
  * If this is unsuitable, please create a [Channel] manually and pass the `onUndeliveredElement` callback to the
  * constructor: [Channel(onUndeliveredElement = ...)][Channel].
  *
- * ### Usage example
+ * ## Structured concurrency
+ *
+ * ### Coroutine context
+ *
+ * [produce] creates a *child coroutine* of `this` [CoroutineScope].
+ *
+ * See the corresponding subsection in the [launch] documentation for details on how the coroutine context is created.
+ * In essence, the elements of [context] are combined with the elements of the [CoroutineScope.coroutineContext],
+ * typically overriding them. It is incorrect to pass a [Job] element there, as this breaks structured concurrency.
+ *
+ * ### Interactions between coroutines
+ *
+ * The details of structured concurrency are described in the [CoroutineScope] interface documentation.
+ * Here is a restatement of some main points as they relate to [async]:
+ *
+ * - The lifecycle of the parent [CoroutineScope] can not end until this coroutine
+ *   (as well as all its children) completes.
+ * - If the parent [CoroutineScope] is cancelled, this coroutine is cancelled as well.
+ * - If this coroutine fails with a non-[CancellationException] exception
+ *   and the parent [CoroutineScope] has a non-supervisor [Job] in its context,
+ *   the parent [Job] is cancelled with this exception.
+ * - If this coroutine fails with an exception and the parent [CoroutineScope] has a supervisor [Job] or no job at all
+ *   (as is the case with [GlobalScope] or malformed scopes),
+ *   the exception is considered uncaught and is only available through the returned [Channel].
+ * - The lifecycle of the [CoroutineScope] passed as the receiver to the [block]
+ *   will not end until the [block] completes (or gets cancelled before ever having a chance to run).
+ * - If the [block] throws a [CancellationException], the coroutine is considered cancelled,
+ *   cancelling all its children in turn, but the parent does not get notified.
+ *
+ * ## Usage example
  *
  * ```
  * /* Generate random integers until we find the square root of 9801.