Rename 'foo' function to 'simple' in flow docs (#2078)
The name 'foo' might be hard to get for novice developers. It is really hard to find a "meaningful" name for all examples in the docs, so this is simply a consistent solution. The alternative is to something like "simpleFlow", but adding a "Flow" suffix to the name implicitly condones Hungarian notation, which is not aligned with Kotlin coding style.
diff --git a/docs/flow.md b/docs/flow.md
index bb35b2e..0405e80 100644
--- a/docs/flow.md
+++ b/docs/flow.md
@@ -54,16 +54,16 @@
### Representing multiple values
Multiple values can be represented in Kotlin using [collections].
-For example, we can have a function `foo()` that returns a [List]
+For example, we can have a `simple` function that returns a [List]
of three numbers and then print them all using [forEach]:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
```kotlin
-fun foo(): List<Int> = listOf(1, 2, 3)
+fun simple(): List<Int> = listOf(1, 2, 3)
fun main() {
- foo().forEach { value -> println(value) }
+ simple().forEach { value -> println(value) }
}
```
@@ -89,7 +89,7 @@
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
```kotlin
-fun foo(): Sequence<Int> = sequence { // sequence builder
+fun simple(): Sequence<Int> = sequence { // sequence builder
for (i in 1..3) {
Thread.sleep(100) // pretend we are computing it
yield(i) // yield next value
@@ -97,7 +97,7 @@
}
fun main() {
- foo().forEach { value -> println(value) }
+ simple().forEach { value -> println(value) }
}
```
@@ -116,7 +116,7 @@
#### Suspending functions
However, this computation blocks the main thread that is running the code.
-When these values are computed by asynchronous code we can mark the function `foo` with a `suspend` modifier,
+When these values are computed by asynchronous code we can mark the `simple` function with a `suspend` modifier,
so that it can perform its work without blocking and return the result as a list:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -125,13 +125,13 @@
import kotlinx.coroutines.*
//sampleStart
-suspend fun foo(): List<Int> {
+suspend fun simple(): List<Int> {
delay(1000) // pretend we are doing something asynchronous here
return listOf(1, 2, 3)
}
fun main() = runBlocking<Unit> {
- foo().forEach { value -> println(value) }
+ simple().forEach { value -> println(value) }
}
//sampleEnd
```
@@ -160,7 +160,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow { // flow builder
+fun simple(): Flow<Int> = flow { // flow builder
for (i in 1..3) {
delay(100) // pretend we are doing something useful here
emit(i) // emit next value
@@ -176,7 +176,7 @@
}
}
// Collect the flow
- foo().collect { value -> println(value) }
+ simple().collect { value -> println(value) }
}
//sampleEnd
```
@@ -203,11 +203,11 @@
* A builder function for [Flow] type is called [flow].
* Code inside the `flow { ... }` builder block can suspend.
-* The function `foo()` is no longer marked with `suspend` modifier.
+* The `simple` function is no longer marked with `suspend` modifier.
* Values are _emitted_ from the flow using [emit][FlowCollector.emit] function.
* Values are _collected_ from the flow using [collect][collect] function.
-> We can replace [delay] with `Thread.sleep` in the body of `foo`'s `flow { ... }` and see that the main
+> We can replace [delay] with `Thread.sleep` in the body of `simple`'s `flow { ... }` and see that the main
thread is blocked in this case.
### Flows are cold
@@ -222,7 +222,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
println("Flow started")
for (i in 1..3) {
delay(100)
@@ -231,8 +231,8 @@
}
fun main() = runBlocking<Unit> {
- println("Calling foo...")
- val flow = foo()
+ println("Calling simple function...")
+ val flow = simple()
println("Calling collect...")
flow.collect { value -> println(value) }
println("Calling collect again...")
@@ -248,7 +248,7 @@
Which prints:
```text
-Calling foo...
+Calling simple function...
Calling collect...
Flow started
1
@@ -263,8 +263,8 @@
<!--- TEST -->
-This is a key reason the `foo()` function (which returns a flow) is not marked with `suspend` modifier.
-By itself, `foo()` returns quickly and does not wait for anything. The flow starts every time it is collected,
+This is a key reason the `simple` function (which returns a flow) is not marked with `suspend` modifier.
+By itself, `simple()` call returns quickly and does not wait for anything. The flow starts every time it is collected,
that is why we see "Flow started" when we call `collect` again.
### Flow cancellation
@@ -283,7 +283,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
delay(100)
println("Emitting $i")
@@ -293,7 +293,7 @@
fun main() = runBlocking<Unit> {
withTimeoutOrNull(250) { // Timeout after 250ms
- foo().collect { value -> println(value) }
+ simple().collect { value -> println(value) }
}
println("Done")
}
@@ -304,7 +304,7 @@
> You can get the full code from [here](../kotlinx-coroutines-core/jvm/test/guide/example-flow-06.kt).
-Notice how only two numbers get emitted by the flow in `foo()` function, producing the following output:
+Notice how only two numbers get emitted by the flow in the `simple` function, producing the following output:
```text
Emitting 1
@@ -590,14 +590,14 @@
### Flow context
Collection of a flow always happens in the context of the calling coroutine. For example, if there is
-a `foo` flow, then the following code runs in the context specified
-by the author of this code, regardless of the implementation details of the `foo` flow:
+a `simple` flow, then the following code runs in the context specified
+by the author of this code, regardless of the implementation details of the `simple` flow:
<div class="sample" markdown="1" theme="idea" data-highlight-only>
```kotlin
withContext(context) {
- foo.collect { value ->
+ simple().collect { value ->
println(value) // run in the specified context
}
}
@@ -610,7 +610,7 @@
This property of a flow is called _context preservation_.
So, by default, code in the `flow { ... }` builder runs in the context that is provided by a collector
-of the corresponding flow. For example, consider the implementation of `foo` that prints the thread
+of the corresponding flow. For example, consider the implementation of a `simple` function that prints the thread
it is called on and emits three numbers:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -622,15 +622,15 @@
fun log(msg: String) = println("[${Thread.currentThread().name}] $msg")
//sampleStart
-fun foo(): Flow<Int> = flow {
- log("Started foo flow")
+fun simple(): Flow<Int> = flow {
+ log("Started simple flow")
for (i in 1..3) {
emit(i)
}
}
fun main() = runBlocking<Unit> {
- foo().collect { value -> log("Collected $value") }
+ simple().collect { value -> log("Collected $value") }
}
//sampleEnd
```
@@ -642,7 +642,7 @@
Running this code produces:
```text
-[main @coroutine#1] Started foo flow
+[main @coroutine#1] Started simple flow
[main @coroutine#1] Collected 1
[main @coroutine#1] Collected 2
[main @coroutine#1] Collected 3
@@ -650,7 +650,7 @@
<!--- TEST FLEXIBLE_THREAD -->
-Since `foo().collect` is called from the main thread, the body of `foo`'s flow is also called in the main thread.
+Since `simple().collect` is called from the main thread, the body of `simple`'s flow is also called in the main thread.
This is the perfect default for fast-running or asynchronous code that does not care about the execution context and
does not block the caller.
@@ -670,7 +670,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
// The WRONG way to change context for CPU-consuming code in flow builder
kotlinx.coroutines.withContext(Dispatchers.Default) {
for (i in 1..3) {
@@ -681,7 +681,7 @@
}
fun main() = runBlocking<Unit> {
- foo().collect { value -> println(value) }
+ simple().collect { value -> println(value) }
}
//sampleEnd
```
@@ -717,7 +717,7 @@
fun log(msg: String) = println("[${Thread.currentThread().name}] $msg")
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
Thread.sleep(100) // pretend we are computing it in CPU-consuming way
log("Emitting $i")
@@ -726,7 +726,7 @@
}.flowOn(Dispatchers.Default) // RIGHT way to change context for CPU-consuming code in flow builder
fun main() = runBlocking<Unit> {
- foo().collect { value ->
+ simple().collect { value ->
log("Collected $value")
}
}
@@ -757,7 +757,7 @@
Running different parts of a flow in different coroutines can be helpful from the standpoint of the overall time it takes
to collect the flow, especially when long-running asynchronous operations are involved. For example, consider a case when
-the emission by `foo()` flow is slow, taking 100 ms to produce an element; and collector is also slow,
+the emission by a `simple` flow is slow, taking 100 ms to produce an element; and collector is also slow,
taking 300 ms to process an element. Let's see how long it takes to collect such a flow with three numbers:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -768,7 +768,7 @@
import kotlin.system.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
delay(100) // pretend we are asynchronously waiting 100 ms
emit(i) // emit next value
@@ -777,7 +777,7 @@
fun main() = runBlocking<Unit> {
val time = measureTimeMillis {
- foo().collect { value ->
+ simple().collect { value ->
delay(300) // pretend we are processing it for 300 ms
println(value)
}
@@ -802,7 +802,7 @@
<!--- TEST ARBITRARY_TIME -->
-We can use a [buffer] operator on a flow to run emitting code of `foo()` concurrently with collecting code,
+We can use a [buffer] operator on a flow to run emitting code of the `simple` flow concurrently with collecting code,
as opposed to running them sequentially:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -812,7 +812,7 @@
import kotlinx.coroutines.flow.*
import kotlin.system.*
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
delay(100) // pretend we are asynchronously waiting 100 ms
emit(i) // emit next value
@@ -822,7 +822,7 @@
fun main() = runBlocking<Unit> {
//sampleStart
val time = measureTimeMillis {
- foo()
+ simple()
.buffer() // buffer emissions, don't wait
.collect { value ->
delay(300) // pretend we are processing it for 300 ms
@@ -867,7 +867,7 @@
import kotlinx.coroutines.flow.*
import kotlin.system.*
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
delay(100) // pretend we are asynchronously waiting 100 ms
emit(i) // emit next value
@@ -877,7 +877,7 @@
fun main() = runBlocking<Unit> {
//sampleStart
val time = measureTimeMillis {
- foo()
+ simple()
.conflate() // conflate emissions, don't process each one
.collect { value ->
delay(300) // pretend we are processing it for 300 ms
@@ -918,7 +918,7 @@
import kotlinx.coroutines.flow.*
import kotlin.system.*
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
delay(100) // pretend we are asynchronously waiting 100 ms
emit(i) // emit next value
@@ -928,7 +928,7 @@
fun main() = runBlocking<Unit> {
//sampleStart
val time = measureTimeMillis {
- foo()
+ simple()
.collectLatest { value -> // cancel & restart on the latest value
println("Collecting $value")
delay(300) // pretend we are processing it for 300 ms
@@ -1279,7 +1279,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
println("Emitting $i")
emit(i) // emit next value
@@ -1288,7 +1288,7 @@
fun main() = runBlocking<Unit> {
try {
- foo().collect { value ->
+ simple().collect { value ->
println(value)
check(value <= 1) { "Collected $value" }
}
@@ -1329,7 +1329,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<String> =
+fun simple(): Flow<String> =
flow {
for (i in 1..3) {
println("Emitting $i")
@@ -1343,7 +1343,7 @@
fun main() = runBlocking<Unit> {
try {
- foo().collect { value -> println(value) }
+ simple().collect { value -> println(value) }
} catch (e: Throwable) {
println("Caught $e")
}
@@ -1390,7 +1390,7 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
-fun foo(): Flow<String> =
+fun simple(): Flow<String> =
flow {
for (i in 1..3) {
println("Emitting $i")
@@ -1404,7 +1404,7 @@
fun main() = runBlocking<Unit> {
//sampleStart
- foo()
+ simple()
.catch { e -> emit("Caught $e") } // emit on exception
.collect { value -> println(value) }
//sampleEnd
@@ -1437,7 +1437,7 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
println("Emitting $i")
emit(i)
@@ -1445,7 +1445,7 @@
}
fun main() = runBlocking<Unit> {
- foo()
+ simple()
.catch { e -> println("Caught $e") } // does not catch downstream exceptions
.collect { value ->
check(value <= 1) { "Collected $value" }
@@ -1481,7 +1481,7 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
for (i in 1..3) {
println("Emitting $i")
emit(i)
@@ -1490,7 +1490,7 @@
fun main() = runBlocking<Unit> {
//sampleStart
- foo()
+ simple()
.onEach { value ->
check(value <= 1) { "Collected $value" }
println(value)
@@ -1532,11 +1532,11 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = (1..3).asFlow()
+fun simple(): Flow<Int> = (1..3).asFlow()
fun main() = runBlocking<Unit> {
try {
- foo().collect { value -> println(value) }
+ simple().collect { value -> println(value) }
} finally {
println("Done")
}
@@ -1548,7 +1548,7 @@
> You can get the full code from [here](../kotlinx-coroutines-core/jvm/test/guide/example-flow-31.kt).
-This code prints three numbers produced by the `foo()` flow followed by a "Done" string:
+This code prints three numbers produced by the `simple` flow followed by a "Done" string:
```text
1
@@ -1572,11 +1572,11 @@
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*
-fun foo(): Flow<Int> = (1..3).asFlow()
+fun simple(): Flow<Int> = (1..3).asFlow()
fun main() = runBlocking<Unit> {
//sampleStart
- foo()
+ simple()
.onCompletion { println("Done") }
.collect { value -> println(value) }
//sampleEnd
@@ -1595,7 +1595,7 @@
The key advantage of [onCompletion] is a nullable `Throwable` parameter of the lambda that can be used
to determine whether the flow collection was completed normally or exceptionally. In the following
-example the `foo()` flow throws an exception after emitting the number 1:
+example the `simple` flow throws an exception after emitting the number 1:
<div class="sample" markdown="1" theme="idea" data-min-compiler-version="1.3">
@@ -1604,13 +1604,13 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = flow {
+fun simple(): Flow<Int> = flow {
emit(1)
throw RuntimeException()
}
fun main() = runBlocking<Unit> {
- foo()
+ simple()
.onCompletion { cause -> if (cause != null) println("Flow completed exceptionally") }
.catch { cause -> println("Caught exception") }
.collect { value -> println(value) }
@@ -1647,10 +1647,10 @@
import kotlinx.coroutines.flow.*
//sampleStart
-fun foo(): Flow<Int> = (1..3).asFlow()
+fun simple(): Flow<Int> = (1..3).asFlow()
fun main() = runBlocking<Unit> {
- foo()
+ simple()
.onCompletion { cause -> println("Flow completed with $cause") }
.collect { value ->
check(value <= 1) { "Collected $value" }