diff --git a/coroutines-guide.md b/coroutines-guide.md index ad06cc100b..1351923c6d 100644 --- a/coroutines-guide.md +++ b/coroutines-guide.md @@ -17,7 +17,7 @@ The main coroutines guide has moved to the [docs folder](docs/coroutines-guide.m * [Cancelling coroutine execution](docs/cancellation-and-timeouts.md#cancelling-coroutine-execution) * [Cancellation is cooperative](docs/cancellation-and-timeouts.md#cancellation-is-cooperative) * [Making computation code cancellable](docs/cancellation-and-timeouts.md#making-computation-code-cancellable) - * [Closing resources with finally](docs/cancellation-and-timeouts.md#closing-resources-with-finally) + * [Closing resources with `finally`](docs/cancellation-and-timeouts.md#closing-resources-with-`finally`) * [Run non-cancellable block](docs/cancellation-and-timeouts.md#run-non-cancellable-block) * [Timeout](docs/cancellation-and-timeouts.md#timeout) diff --git a/docs/cancellation-and-timeouts.md b/docs/cancellation-and-timeouts.md index 56d9c4ec0d..d718080bde 100644 --- a/docs/cancellation-and-timeouts.md +++ b/docs/cancellation-and-timeouts.md @@ -23,7 +23,7 @@ class CancellationTimeOutsGuideTest { * [Cancelling coroutine execution](#cancelling-coroutine-execution) * [Cancellation is cooperative](#cancellation-is-cooperative) * [Making computation code cancellable](#making-computation-code-cancellable) - * [Closing resources with finally](#closing-resources-with-finally) + * [Closing resources with `finally`](#closing-resources-with-`finally`) * [Run non-cancellable block](#run-non-cancellable-block) * [Timeout](#timeout) @@ -49,7 +49,7 @@ fun main() = runBlocking { //sampleStart val job = launch { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } @@ -69,9 +69,9 @@ fun main() = runBlocking { It produces the following output: ```text -I'm sleeping 0 ... -I'm sleeping 1 ... -I'm sleeping 2 ... +job: I'm sleeping 0 ... +job: I'm sleeping 1 ... +job: I'm sleeping 2 ... main: I'm tired of waiting! main: Now I can quit. ``` @@ -104,7 +104,7 @@ fun main() = runBlocking { while (i < 5) { // computation loop, just wastes CPU // print a message twice a second if (System.currentTimeMillis() >= nextPrintTime) { - println("I'm sleeping ${i++} ...") + println("job: I'm sleeping ${i++} ...") nextPrintTime += 500L } } @@ -125,12 +125,12 @@ Run it to see that it continues to print "I'm sleeping" even after cancellation until the job completes by itself after five iterations. @@ -156,7 +156,7 @@ fun main() = runBlocking { while (isActive) { // cancellable computation loop // print a message twice a second if (System.currentTimeMillis() >= nextPrintTime) { - println("I'm sleeping ${i++} ...") + println("job: I'm sleeping ${i++} ...") nextPrintTime += 500L } } @@ -173,22 +173,22 @@ fun main() = runBlocking { > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt). -As you can see, now this loop is cancelled. [isActive] is an extension property that is -available inside the code of coroutine via [CoroutineScope] object. +As you can see, now this loop is cancelled. [isActive] is an extension property +available inside the coroutine via the [CoroutineScope] object. -### Closing resources with finally +### Closing resources with `finally` Cancellable suspending functions throw [CancellationException] on cancellation which can be handled in -a usual way. For example, `try {...} finally {...}` expression and Kotlin `use` function execute their -finalization actions normally when coroutine is cancelled: +the usual way. For example, `try {...} finally {...}` expression and Kotlin `use` function execute their +finalization actions normally when a coroutine is cancelled:
@@ -201,11 +201,11 @@ fun main() = runBlocking { val job = launch { try { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } finally { - println("I'm running finally") + println("job: I'm running finally") } } delay(1300L) // delay a bit @@ -220,15 +220,15 @@ fun main() = runBlocking { > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt). -Both [join][Job.join] and [cancelAndJoin] wait for all the finalization actions to complete, +Both [join][Job.join] and [cancelAndJoin] wait for all finalization actions to complete, so the example above produces the following output: ```text -I'm sleeping 0 ... -I'm sleeping 1 ... -I'm sleeping 2 ... +job: I'm sleeping 0 ... +job: I'm sleeping 1 ... +job: I'm sleeping 2 ... main: I'm tired of waiting! -I'm running finally +job: I'm running finally main: Now I can quit. ``` @@ -240,7 +240,7 @@ Any attempt to use a suspending function in the `finally` block of the previous [CancellationException], because the coroutine running this code is cancelled. Usually, this is not a problem, since all well-behaving closing operations (closing a file, cancelling a job, or closing any kind of a communication channel) are usually non-blocking and do not involve any suspending functions. However, in the -rare case when you need to suspend in the cancelled coroutine you can wrap the corresponding code in +rare case when you need to suspend in a cancelled coroutine you can wrap the corresponding code in `withContext(NonCancellable) {...}` using [withContext] function and [NonCancellable] context as the following example shows:
@@ -253,14 +253,14 @@ fun main() = runBlocking { val job = launch { try { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } finally { withContext(NonCancellable) { - println("I'm running finally") + println("job: I'm running finally") delay(1000L) - println("And I've just delayed for 1 sec because I'm non-cancellable") + println("job: And I've just delayed for 1 sec because I'm non-cancellable") } } } @@ -277,18 +277,18 @@ fun main() = runBlocking { > You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt). ### Timeout -The most obvious reason to cancel coroutine execution in practice +The most obvious practical reason to cancel execution of a coroutine is because its execution time has exceeded some timeout. While you can manually track the reference to the corresponding [Job] and launch a separate coroutine to cancel the tracked one after delay, there is a ready to use [withTimeout] function that does it. @@ -331,10 +331,10 @@ We have not seen its stack trace printed on the console before. That is because inside a cancelled coroutine `CancellationException` is considered to be a normal reason for coroutine completion. However, in this example we have used `withTimeout` right inside the `main` function. -Because cancellation is just an exception, all the resources are closed in a usual way. -You can wrap the code with timeout in `try {...} catch (e: TimeoutCancellationException) {...}` block if -you need to do some additional action specifically on any kind of timeout or use [withTimeoutOrNull] function -that is similar to [withTimeout], but returns `null` on timeout instead of throwing an exception: +Since cancellation is just an exception, all resources are closed in the usual way. +You can wrap the code with timeout in a `try {...} catch (e: TimeoutCancellationException) {...}` block if +you need to do some additional action specifically on any kind of timeout or use the [withTimeoutOrNull] function +that is similar to [withTimeout] but returns `null` on timeout instead of throwing an exception:
diff --git a/kotlinx-coroutines-core/common/src/Annotations.kt b/kotlinx-coroutines-core/common/src/Annotations.kt index 9f52a1a57b..e51e982f24 100644 --- a/kotlinx-coroutines-core/common/src/Annotations.kt +++ b/kotlinx-coroutines-core/common/src/Annotations.kt @@ -24,7 +24,7 @@ public annotation class ExperimentalCoroutinesApi * Its API and semantics can and will be changed in next releases. * * Feature preview can be used to evaluate its real-world strengths and weaknesses, gather and provide feedback. - * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to stable API. + * According to the feedback, [Flow] will be refined on its road to stabilization and promotion to a stable API. */ @MustBeDocumented @Retention(value = AnnotationRetention.BINARY) @@ -44,7 +44,7 @@ public annotation class ObsoleteCoroutinesApi /** * Marks declarations that are **internal** in coroutines API, which means that should not be used outside of - * `kotlinx.coroutines`, because their signatures and semantics will be changing between release without any + * `kotlinx.coroutines`, because their signatures and semantics will change between future releases without any * warnings and without providing any migration aids. */ @Retention(value = AnnotationRetention.BINARY) diff --git a/kotlinx-coroutines-core/common/src/CoroutineScope.kt b/kotlinx-coroutines-core/common/src/CoroutineScope.kt index 7b69d011d4..92977b1dcc 100644 --- a/kotlinx-coroutines-core/common/src/CoroutineScope.kt +++ b/kotlinx-coroutines-core/common/src/CoroutineScope.kt @@ -51,7 +51,7 @@ public interface CoroutineScope { /** * The context of this scope. * Context is encapsulated by the scope and used for implementation of coroutine builders that are extensions on the scope. - * Accessing this property in general code is not recommended for any purposes except accessing [Job] instance for advanced usages. + * Accessing this property in general code is not recommended for any purposes except accessing the [Job] instance for advanced usages. * * By convention, should contain an instance of a [job][Job] to enforce structured concurrency. */ @@ -91,7 +91,7 @@ public operator fun CoroutineScope.plus(context: CoroutineContext): CoroutineSco public fun MainScope(): CoroutineScope = ContextScope(SupervisorJob() + Dispatchers.Main) /** - * Returns `true` when current [Job] is still active (has not completed and was not cancelled yet). + * Returns `true` when the current [Job] is still active (has not completed and was not cancelled yet). * * Check this property in long-running computation loops to support cancellation: * ``` diff --git a/kotlinx-coroutines-core/common/src/Dispatchers.common.kt b/kotlinx-coroutines-core/common/src/Dispatchers.common.kt index b3791ec27b..b340568307 100644 --- a/kotlinx-coroutines-core/common/src/Dispatchers.common.kt +++ b/kotlinx-coroutines-core/common/src/Dispatchers.common.kt @@ -13,36 +13,36 @@ public expect object Dispatchers { /** * The default [CoroutineDispatcher] that is used by all standard builders like * [launch][CoroutineScope.launch], [async][CoroutineScope.async], etc - * if no dispatcher nor any other [ContinuationInterceptor] is specified in their context. + * if neither a dispatcher nor any other [ContinuationInterceptor] is specified in their context. * - * It is backed by a shared pool of threads on JVM. By default, the maximal number of threads used - * by this dispatcher is equal to the number CPU cores, but is at least two. + * It is backed by a shared pool of threads on JVM. By default, the maximum number of threads used + * by this dispatcher is equal to the number of CPU cores, but is at least two. */ public val Default: CoroutineDispatcher /** * A coroutine dispatcher that is confined to the Main thread operating with UI objects. - * Usually such dispatcher is single-threaded. + * Usually such dispatchers are single-threaded. * - * Access to this property may throw [IllegalStateException] if no main dispatchers are present in the classpath. + * Access to this property may throw an [IllegalStateException] if no main dispatchers are present in the classpath. * * Depending on platform and classpath it can be mapped to different dispatchers: - * - On JS and Native it is equivalent of [Default] dispatcher. - * - On JVM it either Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by + * - On JS and Native it is equivalent to the [Default] dispatcher. + * - On JVM it either the Android main thread dispatcher, JavaFx or Swing EDT dispatcher. It is chosen by the * [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html). * - * In order to work with `Main` dispatcher, following artifact should be added to project runtime dependencies: - * - `kotlinx-coroutines-android` for Android Main thread dispatcher - * - `kotlinx-coroutines-javafx` for JavaFx Application thread dispatcher - * - `kotlinx-coroutines-swing` for Swing EDT dispatcher + * In order to work with the `Main` dispatcher, the following artifact should be added to the project runtime dependencies: + * - `kotlinx-coroutines-android` — for Android Main thread dispatcher + * - `kotlinx-coroutines-javafx` — for JavaFx Application thread dispatcher + * - `kotlinx-coroutines-swing` — for Swing EDT dispatcher * - * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on Native and JS platforms. + * Implementation note: [MainCoroutineDispatcher.immediate] is not supported on the Native and JS platforms. */ public val Main: MainCoroutineDispatcher /** * A coroutine dispatcher that is not confined to any specific thread. - * It executes initial continuation of the coroutine in the current call-frame + * It executes the initial continuation of a coroutine in the current call-frame * and lets the coroutine resume in whatever thread that is used by the corresponding suspending function, without * mandating any specific threading policy. Nested coroutines launched in this dispatcher form an event-loop to avoid * stack overflows. @@ -64,12 +64,12 @@ public expect object Dispatchers { * println("Done") * ``` * Can print both "1 2 3" and "1 3 2", this is an implementation detail that can be changed. - * But it is guaranteed that "Done" will be printed only when both `withContext` are completed. + * But it is guaranteed that "Done" will be printed only when both `withContext` calls are completed. * * Note that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption, * but still want to execute it in the current call-frame until its first suspension, then you can use * an optional [CoroutineStart] parameter in coroutine builders like - * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to the + * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to * the value of [CoroutineStart.UNDISPATCHED]. */ public val Unconfined: CoroutineDispatcher diff --git a/kotlinx-coroutines-core/common/src/Timeout.kt b/kotlinx-coroutines-core/common/src/Timeout.kt index 23de4f7cb9..3c902db9a8 100644 --- a/kotlinx-coroutines-core/common/src/Timeout.kt +++ b/kotlinx-coroutines-core/common/src/Timeout.kt @@ -12,16 +12,16 @@ import kotlin.coroutines.intrinsics.* import kotlin.jvm.* /** - * Runs a given suspending [block] of code inside a coroutine with a specified timeout and throws - * [TimeoutCancellationException] if timeout was exceeded. + * Runs a given suspending [block] of code inside a coroutine with a specified [timeout][timeMillis] and throws + * a [TimeoutCancellationException] if the timeout was exceeded. * * 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 [TimeoutCancellationException]. + * the cancellable suspending function inside the block throws a [TimeoutCancellationException]. * - * The sibling function that does not throw exception on timeout is [withTimeoutOrNull]. - * Note that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause. + * 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. * - * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context. + * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher]. * * @param timeMillis timeout time in milliseconds. */ @@ -33,16 +33,16 @@ public suspend fun withTimeout(timeMillis: Long, block: suspend CoroutineSco } /** - * Runs a given suspending block of code inside a coroutine with a specified timeout and returns + * Runs a given suspending block of code inside a coroutine with a specified [timeout][timeMillis] and returns * `null` if this timeout was exceeded. * * 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 [TimeoutCancellationException]. + * cancellable suspending function inside the block throws a [TimeoutCancellationException]. * - * The sibling function that throws exception on timeout is [withTimeout]. - * Note that timeout action can be specified for [select] invocation with [onTimeout][SelectBuilder.onTimeout] clause. + * 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. * - * Implementation note: how exactly time is tracked is an implementation detail of [CoroutineDispatcher] in the context. + * Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher]. * * @param timeMillis timeout time in milliseconds. */ @@ -57,7 +57,7 @@ public suspend fun withTimeoutOrNull(timeMillis: Long, block: suspend Corout setupTimeout(timeoutCoroutine, block) } } catch (e: TimeoutCancellationException) { - // Return null iff it's our exception, otherwise propagate it upstream (e.g. in case of nested withTimeouts) + // Return null if it's our exception, otherwise propagate it upstream (e.g. in case of nested withTimeouts) if (e.coroutine === coroutine) { return null } @@ -73,8 +73,8 @@ private fun setupTimeout( val cont = coroutine.uCont val context = cont.context coroutine.disposeOnCompletion(context.delay.invokeOnTimeout(coroutine.time, coroutine)) - // restart block using new coroutine with new job, - // however start it as undispatched coroutine, because we are already in the proper context + // restart the block using a new coroutine with a new job, + // however, start it undispatched, because we already are in the proper context return coroutine.startUndispatchedOrReturnIgnoreTimeout(coroutine, block) } @@ -114,7 +114,7 @@ public class TimeoutCancellationException internal constructor( @JvmField internal val coroutine: Job? ) : CancellationException(message) { /** - * Creates timeout exception with a given message. + * Creates a timeout exception with the given message. * This constructor is needed for exception stack-traces recovery. */ @Suppress("UNUSED") diff --git a/kotlinx-coroutines-core/common/src/flow/Builders.kt b/kotlinx-coroutines-core/common/src/flow/Builders.kt index 00e9fd704d..c79a5ac255 100644 --- a/kotlinx-coroutines-core/common/src/flow/Builders.kt +++ b/kotlinx-coroutines-core/common/src/flow/Builders.kt @@ -14,7 +14,7 @@ import kotlin.coroutines.* import kotlin.jvm.* /** - * Creates flow from the given suspendable [block]. + * Creates a flow from the given suspendable [block]. * * Example of usage: * ``` @@ -31,8 +31,8 @@ import kotlin.jvm.* * } * ``` * - * `emit` should happen strictly in the dispatchers of the [block] in order to preserve flow context. - * For example, the following code will produce [IllegalStateException]: + * `emit` should happen strictly in the dispatchers of the [block] in order to preserve the flow context. + * For example, the following code will result in an [IllegalStateException]: * ``` * flow { * emit(1) // Ok @@ -41,7 +41,7 @@ import kotlin.jvm.* * } * } * ``` - * If you want to switch the context where this flow is executed use [flowOn] operator. + * If you want to switch the context of execution of a flow, use the [flowOn] operator. */ @FlowPreview public fun flow(@BuilderInference block: suspend FlowCollector.() -> Unit): Flow { @@ -53,8 +53,8 @@ public fun flow(@BuilderInference block: suspend FlowCollector.() -> Unit } /** - * Analogue of [flow] builder that does not check a context of flow execution. - * Used in our own operators where we trust the context of the invocation. + * An analogue of the [flow] builder that does not check the context of execution of the resulting flow. + * Used in our own operators where we trust the context of invocations. */ @FlowPreview @PublishedApi @@ -67,7 +67,7 @@ internal fun unsafeFlow(@BuilderInference block: suspend FlowCollector.() } /** - * Creates flow that produces single value from the given functional type. + * Creates a flow that produces a single value from the given functional type. */ @FlowPreview public fun (() -> T).asFlow(): Flow = unsafeFlow { @@ -75,7 +75,7 @@ public fun (() -> T).asFlow(): Flow = unsafeFlow { } /** - * Creates flow that produces single value from the given functional type. + * Creates a flow that produces a single value from the given functional type. */ @FlowPreview public fun (suspend () -> T).asFlow(): Flow = unsafeFlow { @@ -83,7 +83,7 @@ public fun (suspend () -> T).asFlow(): Flow = unsafeFlow { } /** - * Creates flow that produces values from the given iterable. + * Creates a flow that produces values from the given iterable. */ @FlowPreview public fun Iterable.asFlow(): Flow = unsafeFlow { @@ -93,7 +93,7 @@ public fun Iterable.asFlow(): Flow = unsafeFlow { } /** - * Creates flow that produces values from the given iterable. + * Creates a flow that produces values from the given iterable. */ @FlowPreview public fun Iterator.asFlow(): Flow = unsafeFlow { @@ -103,7 +103,7 @@ public fun Iterator.asFlow(): Flow = unsafeFlow { } /** - * Creates flow that produces values from the given sequence. + * Creates a flow that produces values from the given sequence. */ @FlowPreview public fun Sequence.asFlow(): Flow = unsafeFlow { @@ -113,7 +113,7 @@ public fun Sequence.asFlow(): Flow = unsafeFlow { } /** - * Creates flow that produces values from the given array of elements. + * Creates a flow that produces values from the given array of elements. */ @FlowPreview public fun flowOf(vararg elements: T): Flow = unsafeFlow { @@ -133,7 +133,7 @@ private object EmptyFlow : Flow { } /** - * Creates flow that produces values from the given array. + * Creates a flow that produces values from the given array. */ @FlowPreview public fun Array.asFlow(): Flow = flow { diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt index 5b1c6ec965..d1467d3550 100644 --- a/kotlinx-coroutines-core/common/src/flow/Flow.kt +++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt @@ -7,54 +7,54 @@ package kotlinx.coroutines.flow import kotlinx.coroutines.* /** - * A cold asynchronous stream of the data, that emits from zero to N (where N can be unbounded) values and completes normally or with an exception. + * A cold asynchronous data stream emitting zero to N (where N can be unbounded) values and completing normally or with an exception. * - * All transformations on the flow, such as [map] and [filter] do not trigger flow collection or execution, only terminal operators (e.g. [single]) do trigger it. + * Transformations on a flow, such as [map] and [filter], do not trigger its collection or execution (which is only done by terminal operators like [single]). * - * Flow can be collected in a suspending manner, without actual blocking, using [collect] extension that will complete normally or exceptionally: + * A flow can be collected in a suspending manner, without actual blocking, using the [collect] extension that will complete normally or exceptionally: * ``` * try { * flow.collect { value -> * println("Received $value") * } * } catch (e: Exception) { - * println("Flow has thrown an exception: $e") + * println("The flow has thrown an exception: $e") * } * ``` * Additionally, the library provides a rich set of terminal operators such as [single], [reduce] and others. * - * Flow does not carry information whether it is a cold stream (that can be collected multiple times and - * triggers its evaluation every time [collect] is executed) or a hot one, but conventionally flow represents a cold stream. + * Flows don't carry information whether they are cold streams (which can be collected repeatedly and + * trigger their evaluation every time [collect] is executed) or hot ones, but, conventionally, they represent cold streams. * Transitions between hot and cold streams are supported via channels and the corresponding API: [flowViaChannel], [broadcastIn], [produceIn]. * - * Flow has a context preserving property: it encapsulates its own execution context and never propagates or leaks it to the downstream, thus making - * reasoning about execution context of particular transformations or terminal operations trivial. + * The flow has a context preserving property: it encapsulates its own execution context and never propagates or leaks it downstream, thus making + * reasoning about the execution context of particular transformations or terminal operations trivial. * - * There are two ways of changing the flow's context: [flowOn][Flow.flowOn] and [flowWith][Flow.flowWith]. + * There are two ways to change the context of a flow: [flowOn][Flow.flowOn] and [flowWith][Flow.flowWith]. * The former changes the upstream context ("everything above the flowOn operator") while the latter - * changes the context of the flow within [flowWith] body. For additional information refer to these operators documentation. + * changes the context of the flow within [flowWith] body. For additional information refer to these operators' documentation. * - * This reasoning can be demonstrated in the practice: + * This reasoning can be demonstrated in practice: * ``` * val flow = flowOf(1, 2, 3) * .map { it + 1 } // Will be executed in ctx_1 - * .flowOn(ctx_1) // Changes upstream context: flowOf and map + * .flowOn(ctx_1) // Changes the upstream context: flowOf and map * - * // Now we have flow that is context-preserving: it is executed somewhere but this information is encapsulated in the flow itself + * // Now we have a context-preserving flow: it is executed somewhere but this information is encapsulated in the flow itself * * val filtered = flow // ctx_1 is inaccessible * .filter { it == 3 } // Pure operator without a context yet * * withContext(Dispatchers.Main) { - * // All not encapsulated operators will be executed in Main: filter and single + * // All non-encapsulated operators will be executed in Main: filter and single * val result = filtered.single() * myUi.text = result * } * ``` * - * From the implementation point of view it means that all intermediate operators on [Flow] should use the following constraint: - * If one wants to separate collection or emission into multiple coroutines, it should use [coroutineScope] or [supervisorScope] and - * is not allowed to modify coroutines context: + * From the implementation point of view it means that all intermediate operators on [Flow] should abide by the following constraint: + * If collection or emission of a flow is to be separated into multiple coroutines, it should use [coroutineScope] or [supervisorScope] and + * is not allowed to modify the coroutines' context: * ``` * fun Flow.buffer(bufferSize: Int): Flow = flow { * coroutineScope { // coroutine scope is necessary, withContext is prohibited diff --git a/kotlinx-coroutines-core/common/src/flow/FlowCollector.kt b/kotlinx-coroutines-core/common/src/flow/FlowCollector.kt index 8c63b9afdb..2db7dfae63 100644 --- a/kotlinx-coroutines-core/common/src/flow/FlowCollector.kt +++ b/kotlinx-coroutines-core/common/src/flow/FlowCollector.kt @@ -10,7 +10,7 @@ import kotlinx.coroutines.* * [FlowCollector] is used as an intermediate or a terminal collector of the flow and represents * an entity that accepts values emitted by the [Flow]. * - * This interface usually should not be implemented directly, but rather used as a receiver in [flow] builder when implementing a custom operator. + * This interface should usually not be implemented directly, but rather used as a receiver in a [flow] builder when implementing a custom operator. * Implementations of this interface are not thread-safe. */ @FlowPreview diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt index c2a7b0bceb..ab699f2dc3 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-01.kt @@ -11,7 +11,7 @@ fun main() = runBlocking { //sampleStart val job = launch { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt index 3618a3b60c..cbb3d622b6 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-02.kt @@ -16,7 +16,7 @@ fun main() = runBlocking { while (i < 5) { // computation loop, just wastes CPU // print a message twice a second if (timeSource.currentTimeMillis() >= nextPrintTime) { - println("I'm sleeping ${i++} ...") + println("job: I'm sleeping ${i++} ...") nextPrintTime += 500L } } diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt index edd9ef024b..bebb94b18c 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-03.kt @@ -16,7 +16,7 @@ fun main() = runBlocking { while (isActive) { // cancellable computation loop // print a message twice a second if (timeSource.currentTimeMillis() >= nextPrintTime) { - println("I'm sleeping ${i++} ...") + println("job: I'm sleeping ${i++} ...") nextPrintTime += 500L } } diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt index 4d530f712a..fcad73087b 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-04.kt @@ -12,11 +12,11 @@ fun main() = runBlocking { val job = launch { try { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } finally { - println("I'm running finally") + println("job: I'm running finally") } } delay(1300L) // delay a bit diff --git a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt index d977d4ec34..08bb1e27da 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/example-cancel-05.kt @@ -12,14 +12,14 @@ fun main() = runBlocking { val job = launch { try { repeat(1000) { i -> - println("I'm sleeping $i ...") + println("job: I'm sleeping $i ...") delay(500L) } } finally { withContext(NonCancellable) { - println("I'm running finally") + println("job: I'm running finally") delay(1000L) - println("And I've just delayed for 1 sec because I'm non-cancellable") + println("job: And I've just delayed for 1 sec because I'm non-cancellable") } } } diff --git a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt index 47cc2623a1..83bca486cd 100644 --- a/kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt +++ b/kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt @@ -8,9 +8,9 @@ class CancellationTimeOutsGuideTest { @Test fun testKotlinxCoroutinesGuideCancel01() { test("KotlinxCoroutinesGuideCancel01") { kotlinx.coroutines.guide.cancel01.main() }.verifyLines( - "I'm sleeping 0 ...", - "I'm sleeping 1 ...", - "I'm sleeping 2 ...", + "job: I'm sleeping 0 ...", + "job: I'm sleeping 1 ...", + "job: I'm sleeping 2 ...", "main: I'm tired of waiting!", "main: Now I can quit." ) @@ -19,12 +19,12 @@ class CancellationTimeOutsGuideTest { @Test fun testKotlinxCoroutinesGuideCancel02() { test("KotlinxCoroutinesGuideCancel02") { kotlinx.coroutines.guide.cancel02.main() }.verifyLines( - "I'm sleeping 0 ...", - "I'm sleeping 1 ...", - "I'm sleeping 2 ...", + "job: I'm sleeping 0 ...", + "job: I'm sleeping 1 ...", + "job: I'm sleeping 2 ...", "main: I'm tired of waiting!", - "I'm sleeping 3 ...", - "I'm sleeping 4 ...", + "job: I'm sleeping 3 ...", + "job: I'm sleeping 4 ...", "main: Now I can quit." ) } @@ -32,9 +32,9 @@ class CancellationTimeOutsGuideTest { @Test fun testKotlinxCoroutinesGuideCancel03() { test("KotlinxCoroutinesGuideCancel03") { kotlinx.coroutines.guide.cancel03.main() }.verifyLines( - "I'm sleeping 0 ...", - "I'm sleeping 1 ...", - "I'm sleeping 2 ...", + "job: I'm sleeping 0 ...", + "job: I'm sleeping 1 ...", + "job: I'm sleeping 2 ...", "main: I'm tired of waiting!", "main: Now I can quit." ) @@ -43,11 +43,11 @@ class CancellationTimeOutsGuideTest { @Test fun testKotlinxCoroutinesGuideCancel04() { test("KotlinxCoroutinesGuideCancel04") { kotlinx.coroutines.guide.cancel04.main() }.verifyLines( - "I'm sleeping 0 ...", - "I'm sleeping 1 ...", - "I'm sleeping 2 ...", + "job: I'm sleeping 0 ...", + "job: I'm sleeping 1 ...", + "job: I'm sleeping 2 ...", "main: I'm tired of waiting!", - "I'm running finally", + "job: I'm running finally", "main: Now I can quit." ) } @@ -55,12 +55,12 @@ class CancellationTimeOutsGuideTest { @Test fun testKotlinxCoroutinesGuideCancel05() { test("KotlinxCoroutinesGuideCancel05") { kotlinx.coroutines.guide.cancel05.main() }.verifyLines( - "I'm sleeping 0 ...", - "I'm sleeping 1 ...", - "I'm sleeping 2 ...", + "job: I'm sleeping 0 ...", + "job: I'm sleeping 1 ...", + "job: I'm sleeping 2 ...", "main: I'm tired of waiting!", - "I'm running finally", - "And I've just delayed for 1 sec because I'm non-cancellable", + "job: I'm running finally", + "job: And I've just delayed for 1 sec because I'm non-cancellable", "main: Now I can quit." ) } diff --git a/kotlinx-coroutines-test/README.md b/kotlinx-coroutines-test/README.md index 71a542f054..715beb4c6f 100644 --- a/kotlinx-coroutines-test/README.md +++ b/kotlinx-coroutines-test/README.md @@ -449,5 +449,4 @@ If you have any suggestions for improvements to this experimental API please sha [TestCoroutineScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-scope/index.html [TestCoroutineExceptionHandler]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-exception-handler/index.html [TestCoroutineScope.cleanupTestCoroutines]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-scope/cleanup-test-coroutines.html -[TestCoroutineDispatcher.cleanupTestCoroutines]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-dispatcher/cleanup-test-coroutines.html