Merge branch 'master' of https://github.com/Kotlin/kotlinx.coroutines

# Conflicts (resolved):
#	docs/cancellation-and-timeouts.md

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

@@ -20,44 +20,44 @@ import kotlin.jvm.*
  *
  * The following methods are available for override:
  *
- * * [onStart] is invoked when coroutine was created in not active state and is being [started][Job.start].
- * * [onCancelling] is invoked as soon as coroutine is being cancelled for any reason (or completes).
- * * [onCompleted] is invoked when coroutine completes with a value.
- * * [onCancelled] in invoked when coroutines completes with exception (cancelled).
+ * * [onStart] is invoked when the coroutine was created in non-active state and is being [started][Job.start].
+ * * [onCancelling] is invoked as soon as the coroutine starts being cancelled for any reason (or completes).
+ * * [onCompleted] is invoked when the coroutine completes with a value.
+ * * [onCancelled] in invoked when the coroutine completes with an exception (cancelled).
  *
- * @param parentContext context of the parent coroutine.
- * @param active when `true` (by default) coroutine is created in _active_ state, when `false` in _new_ state.
+ * @param parentContext the context of the parent coroutine.
+ * @param active when `true` (by default), the coroutine is created in the _active_ state, otherwise it is created in the _new_ state.
  * See [Job] for details.
  *
  * @suppress **This an internal API and should not be used from general code.**
  */
 @InternalCoroutinesApi
 public abstract class AbstractCoroutine<in T>(
  /**
- * Context of the parent coroutine.
+ * The context of the parent coroutine.
  */
  @JvmField
  protected val parentContext: CoroutineContext,
  active: Boolean = true
 ) : JobSupport(active), Job, Continuation<T>, CoroutineScope {
  /**
- * Context of this coroutine that includes this coroutine as a [Job].
+ * The context of this coroutine that includes this coroutine as a [Job].
  */
  @Suppress("LeakingThis")
  public final override val context: CoroutineContext = parentContext + this
 
  /**
- * Context of this scope which is the same as the [context] of this coroutine.
+ * The context of this scope which is the same as the [context] of this coroutine.
  */
  public override val coroutineContext: CoroutineContext get() = context
 
  override val isActive: Boolean get() = super.isActive
 
  /**
- * Initializes parent job from the `parentContext` of this coroutine that was passed to it during construction.
+ * Initializes the parent job from the `parentContext` of this coroutine that was passed to it during construction.
  * It shall be invoked at most once after construction after all other initialization.
  * 
- * Invocation of this function may cause this coroutine to become cancelled if parent is already cancelled,
+ * Invocation of this function may cause this coroutine to become cancelled if the parent is already cancelled,
  * in which case it synchronously invokes all the corresponding handlers.
  * @suppress **This is unstable API and it is subject to change.**
  */
@@ -66,7 +66,7 @@ public abstract class AbstractCoroutine<in T>(
  }
 
  /**
- * This function is invoked once when non-active coroutine (constructed with `active` set to `false)
+ * This function is invoked once when a non-active coroutine (constructed with `active` set to `false)
  * is [started][start].
  */
  protected open fun onStart() {}
@@ -76,13 +76,13 @@ public abstract class AbstractCoroutine<in T>(
  }
 
  /**
- * This function is invoked once when job was completed normally with the specified [value],
- * right before all the waiters for coroutine's completion are notified.
+ * This function is invoked once when the job was completed normally with the specified [value],
+ * right before all the waiters for the coroutine's completion are notified.
  */
  protected open fun onCompleted(value: T) {}
 
  /**
- * This function is invoked once when job was cancelled with the specified [cause],
+ * This function is invoked once when the job was cancelled with the specified [cause],
  * right before all the waiters for coroutine's completion are notified.
  *
  * **Note:** the state of the coroutine might not be final yet in this function and should not be queried.

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

@@ -10,8 +10,8 @@ import kotlinx.coroutines.selects.*
 /**
  * A [Deferred] that can be completed via public functions [complete] or [cancel][Job.cancel].
  *
- * Note that [complete] functions returns `false` when this deferred value is already complete or completing,
- * while [cancel][Job.cancel] returns `true` as long the deferred is still _cancelling_ and the corresponding
+ * Note that the [complete] function returns `false` when this deferred value is already complete or completing,
+ * while [cancel][Job.cancel] returns `true` as long as the deferred is still _cancelling_ and the corresponding
  * exception is incorporated into the final [completion exception][getCompletionExceptionOrNull].
  *
  * An instance of completable deferred can be created by `CompletableDeferred()` function in _active_ state.
@@ -24,7 +24,7 @@ public interface CompletableDeferred<T> : Deferred<T> {
  * Completes this deferred value with a given [value]. The result is `true` if this deferred was
  * completed as a result of this invocation and `false` otherwise (if it was already completed).
  *
- * Repeated invocations of this function have no effect and always produce `false`.
+ * Subsequent invocations of this function have no effect and always produce `false`.
  *
  * This function transitions this deferred into _completed_ state if it was not completed or cancelled yet.
  * However, if this deferred has children, then it transitions into _completing_ state and becomes _complete_
@@ -36,7 +36,7 @@ public interface CompletableDeferred<T> : Deferred<T> {
  * Completes this deferred value exceptionally with a given [exception]. The result is `true` if this deferred was
  * completed as a result of this invocation and `false` otherwise (if it was already completed).
  *
- * Repeated invocations of this function have no effect and always produce `false`.
+ * Subsequent invocations of this function have no effect and always produce `false`.
  *
  * This function transitions this deferred into _cancelled_ state if it was not completed or cancelled yet.
  * However, that if this deferred has children, then it transitions into _cancelling_ state and becomes _cancelled_

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

@@ -13,7 +13,7 @@ public interface CompletableJob : Job {
  * Completes this job. The result is `true` if this job was completed as a result of this invocation and
  * `false` otherwise (if it was already completed).
  *
- * Repeated invocations of this function have no effect and always produce `false`.
+ * Subsequent invocations of this function have no effect and always produce `false`.
  *
  * This function transitions this job into _completed- state if it was not completed or cancelled yet.
  * However, that if this job has children, then it transitions into _completing_ state and becomes _complete_
@@ -25,7 +25,7 @@ public interface CompletableJob : Job {
  * Completes this job exceptionally with a given [exception]. The result is `true` if this job was
  * completed as a result of this invocation and `false` otherwise (if it was already completed).
  *
- * Repeated invocations of this function have no effect and always produce `false`.
+ * Subsequent invocations of this function have no effect and always produce `false`.
  *
  * This function transitions this job into _cancelled_ state if it was not completed or cancelled yet.
  * However, that if this job has children, then it transitions into _cancelling_ state and becomes _cancelled_

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

@@ -13,8 +13,8 @@ import kotlinx.coroutines.internal.*
  * wrapped into [CompletionHandlerException], and rethrown, potentially causing crash of unrelated code.
  *
  * The meaning of `cause` that is passed to the handler:
- * * Cause is `null` when job has completed normally.
- * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
+ * * Cause is `null` when the job has completed normally.
+ * * Cause is an instance of [CancellationException] when the job was cancelled _normally_.
  * **It should not be treated as an error**. In particular, it should not be reported to error logs.
  * * Otherwise, the job had _failed_.
  *

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

@@ -19,7 +19,7 @@ internal expect fun handleCoroutineExceptionImpl(context: CoroutineContext, exce
  */
 @InternalCoroutinesApi
 public fun handleCoroutineException(context: CoroutineContext, exception: Throwable) {
- // Invoke exception handler from the context if present
+ // Invoke an exception handler from the context if present
  try {
  context[CoroutineExceptionHandler]?.let {
  it.handleException(context, exception)
@@ -29,7 +29,7 @@ public fun handleCoroutineException(context: CoroutineContext, exception: Throwa
  handleCoroutineExceptionImpl(context, handlerException(exception, t))
  return
  }
- // If handler is not present in the context or exception was thrown, fallback to the global handler
+ // If a handler is not present in the context or an exception was thrown, fallback to the global handler
  handleCoroutineExceptionImpl(context, exception)
 }
 
@@ -54,7 +54,7 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
 /**
  * An optional element in the coroutine context to handle uncaught exceptions.
  *
- * Normally, uncaught exceptions can only result from coroutines created using [launch][CoroutineScope.launch] builder.
+ * Normally, uncaught exceptions can only result from coroutines created using the [launch][CoroutineScope.launch] builder.
  * A coroutine that was created using [async][CoroutineScope.async] always catches all its exceptions and represents them
  * in the resulting [Deferred] object.
  *

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

@@ -15,10 +15,10 @@ import kotlin.coroutines.intrinsics.*
  * to automatically propagate both context elements and cancellation.
  *
  * The best ways to obtain a standalone instance of the scope are [CoroutineScope()] and [MainScope()] factory functions.
- * Additional context elements can be appended to the scope using [plus][CoroutineScope.plus] operator.
+ * Additional context elements can be appended to the scope using the [plus][CoroutineScope.plus] operator.
  *
  * Manual implementation of this interface is not recommended, implementation by delegation should be preferred instead.
- * By convention, [context of the scope][CoroutineScope.coroutineContext] should contain an instance of a [job][Job] to enforce structured concurrency.
+ * By convention, the [context of a scope][CoroutineScope.coroutineContext] should contain an instance of a [job][Job] to enforce structured concurrency.
  *
  * Every coroutine builder (like [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc)
  * and every scoping function (like [coroutineScope], [withContext], etc) provides _its own_ scope
@@ -164,8 +164,8 @@ public object GlobalScope : CoroutineScope {
  * }
  * ```
  *
- * Semantics of the scope in this example:
- * 1) `showSomeData` returns as soon as data is loaded and displayed in the UI.
+ * The scope in this example has the following semantics:
+ * 1) `showSomeData` returns as soon as the data is loaded and displayed in the UI.
  * 2) If `doSomeWork` throws an exception, then the `async` task is cancelled and `showSomeData` rethrows that exception.
  * 3) If the outer scope of `showSomeData` is cancelled, both started `async` and `withContext` blocks are cancelled.
  * 4) If the `async` block fails, `withContext` will be cancelled.

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

@@ -60,7 +60,7 @@ public enum class CoroutineStart {
 
  /**
  * Immediately executes the coroutine until its first suspension point _in the current thread_ as if the
- * coroutine was started using [Dispatchers.Unconfined]. However, when coroutine is resumed from suspension
+ * coroutine was started using [Dispatchers.Unconfined]. However, when the coroutine is resumed from suspension
  * it is dispatched according to the [CoroutineDispatcher] in its context.
  *
  * This is similar to [ATOMIC] in the sense that coroutine starts executing even if it was already cancelled,

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

@@ -7,20 +7,20 @@ package kotlinx.coroutines
 import kotlinx.coroutines.selects.*
 
 /**
- * Deferred value is a non-blocking cancellable future — it is a [Job] that has a result.
+ * Deferred value is a non-blocking cancellable future — it is a [Job] with a result.
  *
- * It is created with [async][CoroutineScope.async] coroutine builder or via constructor of [CompletableDeferred] class.
+ * It is created with the [async][CoroutineScope.async] coroutine builder or via the constructor of [CompletableDeferred] class.
  * It is in [active][isActive] state while the value is being computed.
  *
- * Deferred value has the same state machine as the [Job] with additional convenience methods to retrieve
- * successful or failed result of the computation that was carried out. The result of the deferred is
+ * `Deferred` has the same state machine as the [Job] with additional convenience methods to retrieve
+ * the successful or failed result of the computation that was carried out. The result of the deferred is
  * available when it is [completed][isCompleted] and can be retrieved by [await] method, which throws
- * exception if the deferred had failed.
- * Note that a _cancelled_ deferred is also considered to be completed.
+ * an exception if the deferred had failed.
+ * Note that a _cancelled_ deferred is also considered as completed.
  * The corresponding exception can be retrieved via [getCompletionExceptionOrNull] from a completed instance of deferred.
  *
  * Usually, a deferred value is created in _active_ state (it is created and started).
- * However, [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state
+ * However, the [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state
  * when this parameter is set to [CoroutineStart.LAZY].
  * Such a deferred can be be made _active_ by invoking [start], [join], or [await].
  *

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

@@ -19,8 +19,8 @@ import kotlin.jvm.*
  * culminates in its completion.
  *
  * Jobs can be arranged into parent-child hierarchies where cancellation
- * of parent lead to an immediate cancellation of all its [children]. Failure or cancellation of a child
- * with an exception other than [CancellationException] immediately cancels its parent. This way, parent
+ * of a parent leads to immediate cancellation of all its [children]. Failure or cancellation of a child
+ * with an exception other than [CancellationException] immediately cancels its parent. This way, a parent
  * can [cancel] its own children (including all their children recursively) without cancelling itself.
  *
  * The most basic instances of [Job] are created with [launch][CoroutineScope.launch] coroutine builder or with a
@@ -255,13 +255,13 @@ public interface Job : CoroutineContext.Element {
 
  /**
  * Registers handler that is **synchronously** invoked once on completion of this job.
- * When job is already complete, then the handler is immediately invoked
- * with a job's exception or cancellation cause or `null`. Otherwise, handler will be invoked once when this
+ * When the job is already complete, then the handler is immediately invoked
+ * with the job's exception or cancellation cause or `null`. Otherwise, the handler will be invoked once when this
  * job is complete.
  *
  * The meaning of `cause` that is passed to the handler:
- * * Cause is `null` when job has completed normally.
- * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
+ * * Cause is `null` when the job has completed normally.
+ * * Cause is an instance of [CancellationException] when the job was cancelled _normally_.
  * **It should not be treated as an error**. In particular, it should not be reported to error logs.
  * * Otherwise, the job had _failed_.
  *
@@ -281,13 +281,13 @@ public interface Job : CoroutineContext.Element {
 
  /**
  * Registers handler that is **synchronously** invoked once on cancellation or completion of this job.
- * When job was already cancelled and is completed its execution, then the handler is immediately invoked
- * with a job's cancellation cause or `null` unless [invokeImmediately] is set to false.
+ * when the job was already cancelled and is completed its execution, then the handler is immediately invoked
+ * with the job's cancellation cause or `null` unless [invokeImmediately] is set to false.
  * Otherwise, handler will be invoked once when this job is cancelled or is complete.
  *
  * The meaning of `cause` that is passed to the handler:
- * * Cause is `null` when job has completed normally.
- * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
+ * * Cause is `null` when the job has completed normally.
+ * * Cause is an instance of [CancellationException] when the job was cancelled _normally_.
  * **It should not be treated as an error**. In particular, it should not be reported to error logs.
  * * Otherwise, the job had _failed_.
  *

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

@@ -76,7 +76,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
  +--------+---------+--------------------+
 
 
- This state machine and its transition matrix are optimized for the common case when job is created in active
+ This state machine and its transition matrix are optimized for the common case when a job is created in active
  state (EMPTY_A), at most one completion listener is added to it during its life-time, and it completes
  successfully without children (in this case it directly goes from EMPTY_A or SINGLE state to FINAL_R
  state without going to COMPLETING state)
@@ -881,7 +881,7 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
  * is handled specially by invokeOnCompletion itself -- it adds this node to the list even
  * if the job is already cancelling. For cancelling state child is attached under state lock.
  * It's required to properly wait all children before completion and provide linearizable hierarchy view:
- * If child is attached when job is already being cancelled, such child will receive immediate notification on
+ * If child is attached when the job is already being cancelled, such child will receive immediate notification on
  * cancellation, but parent *will* wait for that child before completion and will handle its exception.
  */
  return invokeOnCompletion(onCancelling = true, handler = ChildHandleNode(this, child).asHandler) as ChildHandle
@@ -902,8 +902,8 @@ public open class JobSupport constructor(active: Boolean) : Job, ChildJob, Paren
  * similarly to [invokeOnCompletion] with `onCancelling` set to `true`.
  *
  * The meaning of [cause] parameter:
- * * Cause is `null` when job has completed normally.
- * * Cause is an instance of [CancellationException] when job was cancelled _normally_.
+ * * Cause is `null` when the job has completed normally.
+ * * Cause is an instance of [CancellationException] when the job was cancelled _normally_.
  * **It should not be treated as an error**. In particular, it should not be reported to error logs.
  * * Otherwise, the job had been cancelled or failed with exception.
  *

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

@@ -80,7 +80,7 @@ public interface SendChannel<in E> {
 
  /**
  * Closes this channel.
- * This is an idempotent operation -- repeated invocations of this function have no effect and return `false`.
+ * This is an idempotent operation -- subsequent invocations of this function have no effect and return `false`.
  * Conceptually, its sends a special "close token" over this channel.
  *
  * Immediately after invocation of this function