Table of contents

Select Expression (experimental)

Select expression makes it possible to await multiple suspending functions simultaneously and select the first one that becomes available.

Select expressions are an experimental feature of kotlinx.coroutines. Their API is expected to evolve in the upcoming updates of the kotlinx.coroutines library with potentially breaking changes.

Selecting from channels

Let us have two producers of strings: fizz and buzz. The fizz produces “Fizz” string every 300 ms:

  1. fun CoroutineScope.fizz() = produce<String> {
  2.     while (true) { // sends "Fizz" every 300 ms
  3.         delay(300)
  4.         send("Fizz")
  5.     }
  6. }

And the buzz produces “Buzz!” string every 500 ms:

  1. fun CoroutineScope.buzz() = produce<String> {
  2.     while (true) { // sends "Buzz!" every 500 ms
  3.         delay(500)
  4.         send("Buzz!")
  5.     }
  6. }

Using receive suspending function we can receive either from one channel or the other. But select expression allows us to receive from both simultaneously using its onReceive clauses:

  1. suspend fun selectFizzBuzz(fizz: ReceiveChannel<String>, buzz: ReceiveChannel<String>) {
  2.     select<Unit> { // <Unit> means that this select expression does not produce any result 
  3.         fizz.onReceive { value ->  // this is the first select clause
  4.             println("fizz -> '$value'")
  5.         }
  6.         buzz.onReceive { value ->  // this is the second select clause
  7.             println("buzz -> '$value'")
  8.         }
  9.     }
  10. }

Let us run it all seven times:

  1. import kotlinx.coroutines.*
  2. import kotlinx.coroutines.channels.*
  3. import kotlinx.coroutines.selects.*
  5. fun CoroutineScope.fizz() = produce<String> {
  6.     while (true) { // sends "Fizz" every 300 ms
  7.         delay(300)
  8.         send("Fizz")
  9.     }
  10. }
  12. fun CoroutineScope.buzz() = produce<String> {
  13.     while (true) { // sends "Buzz!" every 500 ms
  14.         delay(500)
  15.         send("Buzz!")
  16.     }
  17. }
  19. suspend fun selectFizzBuzz(fizz: ReceiveChannel<String>, buzz: ReceiveChannel<String>) {
  20.     select<Unit> { // <Unit> means that this select expression does not produce any result 
  21.         fizz.onReceive { value ->  // this is the first select clause
  22.             println("fizz -> '$value'")
  23.         }
  24.         buzz.onReceive { value ->  // this is the second select clause
  25.             println("buzz -> '$value'")
  26.         }
  27.     }
  28. }
  30. fun main() = runBlocking<Unit> {
  31. //sampleStart
  32.     val fizz = fizz()
  33.     val buzz = buzz()
  34.     repeat(7) {
  35.         selectFizzBuzz(fizz, buzz)
  36.     }
  37.     coroutineContext.cancelChildren() // cancel fizz & buzz coroutines
  38. //sampleEnd        
  39. }

You can get the full code here.

The result of this code is:

  1. fizz -> 'Fizz'
  2. buzz -> 'Buzz!'
  3. fizz -> 'Fizz'
  4. fizz -> 'Fizz'
  5. buzz -> 'Buzz!'
  6. fizz -> 'Fizz'
  7. buzz -> 'Buzz!'

Selecting on close

The onReceive clause in select fails when the channel is closed causing the corresponding select to throw an exception. We can use onReceiveOrNull clause to perform a specific action when the channel is closed. The following example also shows that select is an expression that returns the result of its selected clause:

  1. suspend fun selectAorB(a: ReceiveChannel<String>, b: ReceiveChannel<String>): String =
  2.     select<String> {
  3.         a.onReceiveOrNull { value -> 
  4.             if (value == null) 
  5.                 "Channel 'a' is closed" 
  6.             else 
  7.                 "a -> '$value'"
  8.         }
  9.         b.onReceiveOrNull { value -> 
  10.             if (value == null) 
  11.                 "Channel 'b' is closed"
  12.             else    
  13.                 "b -> '$value'"
  14.         }
  15.     }

Note that onReceiveOrNull is an extension function defined only for channels with non-nullable elements so that there is no accidental confusion between a closed channel and a null value.

Let’s use it with channel a that produces “Hello” string four times and channel b that produces “World” four times:

  1. import kotlinx.coroutines.*
  2. import kotlinx.coroutines.channels.*
  3. import kotlinx.coroutines.selects.*
  5. suspend fun selectAorB(a: ReceiveChannel<String>, b: ReceiveChannel<String>): String =
  6.     select<String> {
  7.         a.onReceiveOrNull { value -> 
  8.             if (value == null) 
  9.                 "Channel 'a' is closed" 
  10.             else 
  11.                 "a -> '$value'"
  12.         }
  13.         b.onReceiveOrNull { value -> 
  14.             if (value == null) 
  15.                 "Channel 'b' is closed"
  16.             else    
  17.                 "b -> '$value'"
  18.         }
  19.     }
  21. fun main() = runBlocking<Unit> {
  22. //sampleStart
  23.     val a = produce<String> {
  24.         repeat(4) { send("Hello $it") }
  25.     }
  26.     val b = produce<String> {
  27.         repeat(4) { send("World $it") }
  28.     }
  29.     repeat(8) { // print first eight results
  30.         println(selectAorB(a, b))
  31.     }
  32.     coroutineContext.cancelChildren()  
  33. //sampleEnd      
  34. }

You can get the full code here.

The result of this code is quite interesting, so we’ll analyze it in more detail:

  1. a -> 'Hello 0'
  2. a -> 'Hello 1'
  3. b -> 'World 0'
  4. a -> 'Hello 2'
  5. a -> 'Hello 3'
  6. b -> 'World 1'
  7. Channel 'a' is closed
  8. Channel 'a' is closed

There are couple of observations to make out of it.

First of all, select is biased to the first clause. When several clauses are selectable at the same time, the first one among them gets selected. Here, both channels are constantly producing strings, so a channel, being the first clause in select, wins. However, because we are using unbuffered channel, the a gets suspended from time to time on its send invocation and gives a chance for b to send, too.

The second observation, is that onReceiveOrNull gets immediately selected when the channel is already closed.

Selecting to send

Select expression has onSend clause that can be used for a great good in combination with a biased nature of selection.

Let us write an example of producer of integers that sends its values to a side channel when the consumers on its primary channel cannot keep up with it:

  1. fun CoroutineScope.produceNumbers(side: SendChannel<Int>) = produce<Int> {
  2.     for (num in 1..10) { // produce 10 numbers from 1 to 10
  3.         delay(100) // every 100 ms
  4.         select<Unit> {
  5.             onSend(num) {} // Send to the primary channel
  6.             side.onSend(num) {} // or to the side channel     
  7.         }
  8.     }
  9. }

Consumer is going to be quite slow, taking 250 ms to process each number:

  1. import kotlinx.coroutines.*
  2. import kotlinx.coroutines.channels.*
  3. import kotlinx.coroutines.selects.*
  5. fun CoroutineScope.produceNumbers(side: SendChannel<Int>) = produce<Int> {
  6.     for (num in 1..10) { // produce 10 numbers from 1 to 10
  7.         delay(100) // every 100 ms
  8.         select<Unit> {
  9.             onSend(num) {} // Send to the primary channel
  10.             side.onSend(num) {} // or to the side channel     
  11.         }
  12.     }
  13. }
  15. fun main() = runBlocking<Unit> {
  16. //sampleStart
  17.     val side = Channel<Int>() // allocate side channel
  18.     launch { // this is a very fast consumer for the side channel
  19.         side.consumeEach { println("Side channel has $it") }
  20.     }
  21.     produceNumbers(side).consumeEach { 
  22.         println("Consuming $it")
  23.         delay(250) // let us digest the consumed number properly, do not hurry
  24.     }
  25.     println("Done consuming")
  26.     coroutineContext.cancelChildren()  
  27. //sampleEnd      
  28. }

You can get the full code here.

So let us see what happens:

  1. Consuming 1
  2. Side channel has 2
  3. Side channel has 3
  4. Consuming 4
  5. Side channel has 5
  6. Side channel has 6
  7. Consuming 7
  8. Side channel has 8
  9. Side channel has 9
  10. Consuming 10
  11. Done consuming

Selecting deferred values

Deferred values can be selected using onAwait clause. Let us start with an async function that returns a deferred string value after a random delay:

  1. fun CoroutineScope.asyncString(time: Int) = async {
  2.     delay(time.toLong())
  3.     "Waited for $time ms"
  4. }

Let us start a dozen of them with a random delay.

  1. fun CoroutineScope.asyncStringsList(): List<Deferred<String>> {
  2.     val random = Random(3)
  3.     return List(12) { asyncString(random.nextInt(1000)) }
  4. }

Now the main function awaits for the first of them to complete and counts the number of deferred values that are still active. Note that we’ve used here the fact that select expression is a Kotlin DSL, so we can provide clauses for it using an arbitrary code. In this case we iterate over a list of deferred values to provide onAwait clause for each deferred value.

  1. import kotlinx.coroutines.*
  2. import kotlinx.coroutines.selects.*
  3. import java.util.*
  5. fun CoroutineScope.asyncString(time: Int) = async {
  6.     delay(time.toLong())
  7.     "Waited for $time ms"
  8. }
  10. fun CoroutineScope.asyncStringsList(): List<Deferred<String>> {
  11.     val random = Random(3)
  12.     return List(12) { asyncString(random.nextInt(1000)) }
  13. }
  15. fun main() = runBlocking<Unit> {
  16. //sampleStart
  17.     val list = asyncStringsList()
  18.     val result = select<String> {
  19.         list.withIndex().forEach { (index, deferred) ->
  20.             deferred.onAwait { answer ->
  21.                 "Deferred $index produced answer '$answer'"
  22.             }
  23.         }
  24.     }
  25.     println(result)
  26.     val countActive = list.count { it.isActive }
  27.     println("$countActive coroutines are still active")
  28. //sampleEnd
  29. }

You can get the full code here.

The output is:

  1. Deferred 4 produced answer 'Waited for 128 ms'
  2. 11 coroutines are still active

Switch over a channel of deferred values

Let us write a channel producer function that consumes a channel of deferred string values, waits for each received deferred value, but only until the next deferred value comes over or the channel is closed. This example puts together onReceiveOrNull and onAwait clauses in the same select:

  1. fun CoroutineScope.switchMapDeferreds(input: ReceiveChannel<Deferred<String>>) = produce<String> {
  2.     var current = input.receive() // start with first received deferred value
  3.     while (isActive) { // loop while not cancelled/closed
  4.         val next = select<Deferred<String>?> { // return next deferred value from this select or null
  5.             input.onReceiveOrNull { update ->
  6.                 update // replaces next value to wait
  7.             }
  8.             current.onAwait { value ->  
  9.                 send(value) // send value that current deferred has produced
  10.                 input.receiveOrNull() // and use the next deferred from the input channel
  11.             }
  12.         }
  13.         if (next == null) {
  14.             println("Channel was closed")
  15.             break // out of loop
  16.         } else {
  17.             current = next
  18.         }
  19.     }
  20. }

To test it, we’ll use a simple async function that resolves to a specified string after a specified time:

  1. fun CoroutineScope.asyncString(str: String, time: Long) = async {
  2.     delay(time)
  3.     str
  4. }

The main function just launches a coroutine to print results of switchMapDeferreds and sends some test data to it:

  1. import kotlinx.coroutines.*
  2. import kotlinx.coroutines.channels.*
  3. import kotlinx.coroutines.selects.*
  5. fun CoroutineScope.switchMapDeferreds(input: ReceiveChannel<Deferred<String>>) = produce<String> {
  6.     var current = input.receive() // start with first received deferred value
  7.     while (isActive) { // loop while not cancelled/closed
  8.         val next = select<Deferred<String>?> { // return next deferred value from this select or null
  9.             input.onReceiveOrNull { update ->
  10.                 update // replaces next value to wait
  11.             }
  12.             current.onAwait { value ->  
  13.                 send(value) // send value that current deferred has produced
  14.                 input.receiveOrNull() // and use the next deferred from the input channel
  15.             }
  16.         }
  17.         if (next == null) {
  18.             println("Channel was closed")
  19.             break // out of loop
  20.         } else {
  21.             current = next
  22.         }
  23.     }
  24. }
  26. fun CoroutineScope.asyncString(str: String, time: Long) = async {
  27.     delay(time)
  28.     str
  29. }
  31. fun main() = runBlocking<Unit> {
  32. //sampleStart
  33.     val chan = Channel<Deferred<String>>() // the channel for test
  34.     launch { // launch printing coroutine
  35.         for (s in switchMapDeferreds(chan)) 
  36.             println(s) // print each received string
  37.     }
  38.     chan.send(asyncString("BEGIN", 100))
  39.     delay(200) // enough time for "BEGIN" to be produced
  40.     chan.send(asyncString("Slow", 500))
  41.     delay(100) // not enough time to produce slow
  42.     chan.send(asyncString("Replace", 100))
  43.     delay(500) // give it time before the last one
  44.     chan.send(asyncString("END", 500))
  45.     delay(1000) // give it time to process
  46.     chan.close() // close the channel ... 
  47.     delay(500) // and wait some time to let it finish
  48. //sampleEnd
  49. }

You can get the full code here.

The result of this code:

  1. BEGIN
  2. Replace
  3. END
  4. Channel was closed