Skip to content

Commit

Permalink
Fix guide for "Lazily started async"
Browse files Browse the repository at this point in the history
See PR Kotlin#442
  • Loading branch information
Sahil Lone authored and elizarov committed Jul 26, 2018
1 parent 705ba56 commit 52a0ec0
Show file tree
Hide file tree
Showing 3 changed files with 18 additions and 6 deletions.
3 changes: 3 additions & 0 deletions core/kotlinx-coroutines-core/test/guide/example-compose-03.kt
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ fun main(args: Array<String>) = runBlocking<Unit> {
val time = measureTimeMillis {
val one = async(start = CoroutineStart.LAZY) { doSomethingUsefulOne() }
val two = async(start = CoroutineStart.LAZY) { doSomethingUsefulTwo() }
// some computation
one.start() // start the first one
two.start() // start the second one
println("The answer is ${one.await() + two.await()}")
}
println("Completed in $time ms")
Expand Down
2 changes: 1 addition & 1 deletion core/kotlinx-coroutines-core/test/guide/test/GuideTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ class GuideTest {
fun testKotlinxCoroutinesExperimentalGuideCompose03() {
test("KotlinxCoroutinesExperimentalGuideCompose03") { kotlinx.coroutines.experimental.guide.compose03.main(emptyArray()) }.verifyLinesArbitraryTime(
"The answer is 42",
"Completed in 2017 ms"
"Completed in 1017 ms"
)
}

Expand Down
19 changes: 14 additions & 5 deletions coroutines-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -698,13 +698,16 @@ Note, that concurrency with coroutines is always explicit.
There is a laziness option to [async] using an optional `start` parameter with a value of [CoroutineStart.LAZY].
It starts coroutine only when its result is needed by some
[await][Deferred.await] or if a [start][Job.start] function
is invoked. Run the following example that differs from the previous one only by this option:
is invoked. Run the following example:

```kotlin
fun main(args: Array<String>) = runBlocking<Unit> {
val time = measureTimeMillis {
val one = async(start = CoroutineStart.LAZY) { doSomethingUsefulOne() }
val two = async(start = CoroutineStart.LAZY) { doSomethingUsefulTwo() }
// some computation
one.start() // start the first one
two.start() // start the second one
println("The answer is ${one.await() + two.await()}")
}
println("Completed in $time ms")
Expand All @@ -717,14 +720,20 @@ It produces something like this:

```text
The answer is 42
Completed in 2017 ms
Completed in 1017 ms
```

<!--- TEST ARBITRARY_TIME -->

So, we are back to sequential execution, because we _first_ start and await for `one`, _and then_ start and await
for `two`. It is not the intended use-case for laziness. It is designed as a replacement for
the standard `lazy` function in cases when computation of the value involves suspending functions.
So, here the two coroutines are defined but not executed as in the previous example, but the control is given to
the programmer about when exactly to start the execution by calling [start][Job.start] on it. We first
start `one`, then start `two`, and then await for the individual coroutines to finish.

Note, that if we have called [await][Deferred.await] in `println` and omitted [start][Job.start] on individual
coroutines, then we would have got the sequential behaviour as [await][Deferred.await] starts the coroutine
execution and waits for the execution to finish, which is not the intended use-case for laziness.
The use-case for `async(start = CoroutineStart.LAZY)` is a replacement for the
standard `lazy` function in cases when computation of the value involves suspending functions.

### Async-style functions

Expand Down

0 comments on commit 52a0ec0

Please sign in to comment.