@@ -32,7 +32,7 @@ class GuideTest {
32
32
33
33
# Guide to kotlinx.coroutines by example
34
34
35
- This is a short guide on core features of ` kotlinx.coroutines ` with a series of examples.
35
+ This is a guide on core features of ` kotlinx.coroutines ` with a series of examples.
36
36
37
37
## Introduction and setup
38
38
@@ -41,7 +41,7 @@ libraries to utilize coroutines. Unlike many other languages with similar capabi
41
41
are not keywords in Kotlin and are not even part of its standard library.
42
42
43
43
` kotlinx.coroutines ` is one such rich library. It contains a number of high-level
44
- coroutine-enabled primitives that this guide covers, including ` async ` and ` await ` .
44
+ coroutine-enabled primitives that this guide covers, including ` launch ` , ` async ` and others .
45
45
You need to add a dependency on ` kotlinx-coroutines-core ` module as explained
46
46
[ here] ( README.md#using-in-your-projects ) to use primitives from this guide in your projects.
47
47
@@ -117,11 +117,11 @@ Run the following code:
117
117
118
118
``` kotlin
119
119
fun main (args : Array <String >) {
120
- launch { // launch new coroutine
120
+ launch { // launch new coroutine in background and continue
121
121
delay(1000L ) // non-blocking delay for 1 second (default time unit is ms)
122
122
println (" World!" ) // print after delay
123
123
}
124
- println (" Hello," ) // main function continues while coroutine is delayed
124
+ println (" Hello," ) // main thread continues while coroutine is delayed
125
125
Thread .sleep(2000L ) // block main thread for 2 seconds to keep JVM alive
126
126
}
127
127
```
@@ -153,18 +153,20 @@ coroutine and it can be only used from a coroutine.
153
153
154
154
### Bridging blocking and non-blocking worlds
155
155
156
- The first example mixes _ non-blocking_ ` delay(...) ` and _ blocking_ ` Thread.sleep(...) ` in the same
157
- code of ` main ` function. It is easy to get lost. Let's cleanly separate blocking and non-blocking
158
- worlds by using [ runBlocking] :
156
+ The first example mixes _ non-blocking_ ` delay(...) ` and _ blocking_ ` Thread.sleep(...) ` in the same code.
157
+ It is easy to get lost which one is blocking and which one is not.
158
+ Let's be explicit about blocking using [ runBlocking] coroutine builder :
159
159
160
160
``` kotlin
161
- fun main (args : Array <String >) = runBlocking< Unit > { // start main coroutine
162
- launch { // launch new coroutine
161
+ fun main (args : Array <String >) {
162
+ launch { // launch new coroutine in background and continue
163
163
delay(1000L )
164
164
println (" World!" )
165
165
}
166
- println (" Hello," ) // main coroutine continues while child is delayed
167
- delay(2000L ) // non-blocking delay for 2 seconds to keep JVM alive
166
+ println (" Hello," ) // main thread continues here immediately
167
+ runBlocking { // but this expression blocks the main thread
168
+ delay(2000L ) // ... while we delay for 2 seconds to keep JVM alive
169
+ }
168
170
}
169
171
```
170
172
@@ -176,9 +178,31 @@ World!
176
178
-->
177
179
178
180
The result is the same, but this code uses only non-blocking [ delay] .
181
+ The the main thread, that invokes ` runBlocking ` , _ blocks_ until the coroutine inside ` runBlocking ` is active.
182
+
183
+ This example can be also rewritten in a more idiomatic way, using ` runBlocking ` to wrap
184
+ the execution of the main function:
185
+
186
+ ``` kotlin
187
+ fun main (args : Array <String >) = runBlocking<Unit > { // start main coroutine
188
+ launch { // launch new coroutine in background and continue
189
+ delay(1000L )
190
+ println (" World!" )
191
+ }
192
+ println (" Hello," ) // main coroutine continues here immediately
193
+ delay(2000L ) // delaying for 2 seconds to keep JVM alive
194
+ }
195
+ ```
196
+
197
+ > You can get full code [ here] ( core/kotlinx-coroutines-core/src/test/kotlin/guide/example-basic-02b.kt )
198
+
199
+ <!-- - TEST
200
+ Hello,
201
+ World!
202
+ -->
179
203
180
- ` runBlocking { ... } ` works as an adaptor that is used here to start the top-level main coroutine.
181
- The regular code outside of ` runBlocking ` _ blocks _ , until the coroutine inside ` runBlocking ` is active.
204
+ Here ` runBlocking<Unit> { ... } ` works as an adaptor that is used to start the top-level main coroutine.
205
+ We explicitly specify its ` Unit ` return type, because a well-formed ` main ` function in Kotlin has to return ` Unit ` .
182
206
183
207
This is also a way to write unit-tests for suspending functions:
184
208
0 commit comments