This guide assumes familiarity with basic coroutine concepts that are covered in Guide to kotlinx.coroutines and gives specific examples on how to use coroutines in UI applications.
All UI application libraries have one thing in common. They have the single main thread where all state of the UI is confined, and all updates to the UI has to happen in this particular thread. With respect to coroutines, it means that you need an appropriate coroutine dispatcher context that confines the coroutine execution to this main UI thread.
In particular, kotlinx.coroutines
has three modules that provide coroutine context for different UI application libraries:
Dispatchers.Main
context for Android applications.Dispatchers.JavaFx
context for JavaFX UI applications.Dispatchers.Swing
context for Swing UI applications.Also, UI dispatcher is available via Dispatchers.Main
from kotlinx-coroutines-core
and corresponding implementation (Android, JavaFx or Swing) is discovered by ServiceLoader
API. For example, if you are writing JavaFx application, you can use either Dispatchers.Main
or Dispachers.JavaFx
extension, it will be the same object.
This guide covers all UI libraries simultaneously, because each of these modules consists of just one object definition that is a couple of pages long. You can use any of them as an example to write the corresponding context object for your favourite UI library, even if it is not included out of the box here.
The runnable examples in this guide are presented for JavaFx. The advantage is that all the examples can be directly started on any OS without the need for emulators or anything like that and they are fully self-contained (each example is in one file). There are separate notes on what changes need to be made (if any) to reproduce them on Android.
The basic example application for JavaFx consists of a window with a text label named hello
that initially contains "Hello World!" string and a pinkish circle in the bottom-right corner named fab
(floating action button).
The start
function of JavaFX application invokes setup
function, passing it reference to hello
and fab
nodes. That is where various code is placed in the rest of this guide:
fun setup(hello: Text, fab: Circle) { // placeholder }
You can get full code here.
You can clone kotlinx.coroutines project from GitHub onto your workstation and open the project in IDE. All the examples from this guide are in the test folder of ui/kotlinx-coroutines-javafx
module. This way you'll be able to run and see how each example works and to experiment with them by making changes.
Follow the guide on Getting Started With Android and Kotlin to create Kotlin project in Android Studio. You are also encouraged to add Kotlin Android Extensions to your application.
In Android Studio 2.3 you'll get an application that looks similarly to the one shown below:
Go to the context_main.xml
of your application and assign an ID of "hello" to the text view with "Hello World!" string, so that it is available in your application as hello
with Kotlin Android extensions. The pinkish floating action button is already named fab
in the project template that gets created.
In the MainActivity.kt
of your application remove the block fab.setOnClickListener { ... }
and instead add setup(hello, fab)
invocation as the last line of onCreate
function. Create a placeholder setup
function at the end of the file. That is where various code is placed in the rest of this guide:
fun setup(hello: TextView, fab: FloatingActionButton) { // placeholder }
Add dependencies on kotlinx-coroutines-android
module to the dependencies { ... }
section of app/build.gradle
file:
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.0-M1"
You can clone kotlinx.coroutines project from GitHub onto your workstation. The resulting template project for Android resides in ui/kotlinx-coroutines-android/example-app
directory. You can load it in Android Studio to follow this guide on Android.
This section shows basic usage of coroutines in UI applications.
The kotlinx-coroutines-javafx
module contains Dispatchers.JavaFx dispatcher that dispatches coroutine execution to the JavaFx application thread. We import it as Main
to make all the presented examples easily portable to Android:
import kotlinx.coroutines.javafx.JavaFx as Main
Coroutines confined to the main UI thread can freely update anything in UI and suspend without blocking the main thread. For example, we can perform animations by coding them in imperative style. The following code updates the text with a 10 to 1 countdown twice a second, using launch coroutine builder:
fun setup(hello: Text, fab: Circle) { GlobalScope.launch(Dispatchers.Main) { // launch coroutine in the main thread for (i in 10 downTo 1) { // countdown from 10 to 1 hello.text = "Countdown $i ..." // update text delay(500) // wait half a second } hello.text = "Done!" } }
You can get full code here.
So, what happens here? Because we are launching coroutine in the main UI context, we can freely update UI from inside this coroutine and invoke suspending functions like delay at the same time. UI is not frozen while delay
waits, because it does not block the UI thread -- it just suspends the coroutine.
The corresponding code for Android application is the same. You just need to copy the body of
setup
function into the corresponding function of Android project.
We can keep a reference to the Job object that launch
function returns and use it to cancel coroutine when we want to stop it. Let us cancel the coroutine when pinkish circle is clicked:
fun setup(hello: Text, fab: Circle) { val job = GlobalScope.launch(Dispatchers.Main) { // launch coroutine in the main thread for (i in 10 downTo 1) { // countdown from 10 to 1 hello.text = "Countdown $i ..." // update text delay(500) // wait half a second } hello.text = "Done!" } fab.onMouseClicked = EventHandler { job.cancel() } // cancel coroutine on click }
You can get full code here.
Now, if the circle is clicked while countdown is still running, the countdown stops. Note that Job.cancel is completely thread-safe and non-blocking. It just signals the coroutine to cancel its job, without waiting for it to actually terminate. It can be invoked from anywhere. Invoking it on a coroutine that was already cancelled or has completed does nothing.
The corresponding line for Android is shown below:
fab.setOnClickListener { job.cancel() } // cancel coroutine on click
In this section we show how UI applications can use actors within their UI context make sure that there is no unbounded growth in the number of launched coroutines.
Our goal is to write an extension coroutine builder function named onClick
, so that we can perform countdown animation every time when the circle is clicked with this simple code:
fun setup(hello: Text, fab: Circle) { fab.onClick { // start coroutine when the circle is clicked for (i in 10 downTo 1) { // countdown from 10 to 1 hello.text = "Countdown $i ..." // update text delay(500) // wait half a second } hello.text = "Done!" } }
Our first implementation for onClick
just launches a new coroutine on each mouse event and passes the corresponding mouse event into the supplied action (just in case we need it):
fun Node.onClick(action: suspend (MouseEvent) -> Unit) { onMouseClicked = EventHandler { event -> GlobalScope.launch(Dispatchers.Main) { action(event) } } }
You can get full code here.
Note that each time the circle is clicked, it starts a new coroutine and they all compete to update the text. Try it. It does not look very good. We'll fix it later.
On Android, the corresponding extension can be written for
View
class, so that the code insetup
function that is shown above can be used without changes. There is noMouseEvent
used in OnClickListener on Android, so it is omitted.
fun View.onClick(action: suspend () -> Unit) { setOnClickListener { GlobalScope.launch(Dispatchers.Main) { action() } } }
We can cancel an active job before starting a new one to ensure that at most one coroutine is animating the countdown. However, it is generally not the best idea. The cancel function serves only as a signal to abort a coroutine. Cancellation is cooperative and a coroutine may, at the moment, be doing something non-cancellable or otherwise ignore a cancellation signal. A better solution is to use an actor for tasks that should not be performed concurrently. Let us change onClick
extension implementation:
fun Node.onClick(action: suspend (MouseEvent) -> Unit) { // launch one actor to handle all events on this node val eventActor = GlobalScope.actor<MouseEvent>(Dispatchers.Main) { for (event in channel) action(event) // pass event to action } // install a listener to offer events to this actor onMouseClicked = EventHandler { event -> eventActor.offer(event) } }
You can get full code here.
The key idea that underlies an integration of an actor coroutine and a regular event handler is that there is an offer function on SendChannel that does not wait. It sends an element to the actor immediately, if it is possible, or discards an element otherwise. An offer
actually returns a Boolean
result which we ignore here.
Try clicking repeatedly on a circle in this version of the code. The clicks are just ignored while the countdown animation is running. This happens because the actor is busy with an animation and does not receive from its channel. By default, an actor's mailbox is backed by RendezvousChannel
, whose offer
operation succeeds only when the receive
is active.
On Android, there is
View
sent in OnClickListener, so we send theView
to the actor as a signal. The corresponding extension forView
class looks like this:
fun View.onClick(action: suspend (View) -> Unit) { // launch one actor val eventActor = GlobalScope.actor<View>(Dispatchers.Main) { for (event in channel) action(event) } // install a listener to activate this actor setOnClickListener { eventActor.offer(it) } }
Sometimes it is more appropriate to process the most recent event, instead of just ignoring events while we were busy processing the previous one. The actor coroutine builder accepts an optional capacity
parameter that controls the implementation of the channel that this actor is using for its mailbox. The description of all the available choices is given in documentation of the Channel()
factory function.
Let us change the code to use ConflatedChannel
by passing Channel.CONFLATED capacity value. The change is only to the line that creates an actor:
fun Node.onClick(action: suspend (MouseEvent) -> Unit) { // launch one actor to handle all events on this node val eventActor = GlobalScope.actor<MouseEvent>(Dispatchers.Main, capacity = Channel.CONFLATED) { // <--- Changed here for (event in channel) action(event) // pass event to action } // install a listener to offer events to this actor onMouseClicked = EventHandler { event -> eventActor.offer(event) } }
You can get full JavaFx code here. On Android you need to update
val eventActor = ...
line from the previous example.
Now, if a circle is clicked while the animation is running, it restarts animation after the end of it. Just once. Repeated clicks while the animation is running are conflated and only the most recent event gets to be processed.
This is also a desired behaviour for UI applications that have to react to incoming high-frequency event streams by updating their UI based on the most recently received update. A coroutine that is using ConflatedChannel
avoids delays that are usually introduced by buffering of events.
You can experiment with capacity
parameter in the above line to see how it affects the behaviour of the code. Setting capacity = Channel.UNLIMITED
creates a coroutine with LinkedListChannel
mailbox that buffers all events. In this case, the animation runs as many times as the circle is clicked.
This section explains how to use UI coroutines with thread-blocking operations.
It would have been great if all APIs out there were written as suspending functions that never blocks an execution thread. However, it is quite often not the case. Sometimes you need to do a CPU-consuming computation or just need to invoke some 3rd party APIs for network access, for example, that blocks the invoker thread. You cannot do that from the main UI thread nor from the UI-confined coroutine directly, because that would block the main UI thread and cause the freeze up of the UI.
The following example illustrates the problem. We are going to use onClick
extension with UI-confined event-conflating actor from the last section to process the last click in the main UI thread. For this example, we are going to perform naive computation of Fibonacci numbers:
fun fib(x: Int): Int = if (x <= 1) x else fib(x - 1) + fib(x - 2)
We'll be computing larger and larger Fibonacci number each time the circle is clicked. To make the UI freeze more obvious, there is also a fast counting animation that is always running and is constantly updating the text in the main UI dispatcher:
fun setup(hello: Text, fab: Circle) { var result = "none" // the last result // counting animation GlobalScope.launch(Dispatchers.Main) { var counter = 0 while (true) { hello.text = "${++counter}: $result" delay(100) // update the text every 100ms } } // compute the next fibonacci number of each click var x = 1 fab.onClick { result = "fib($x) = ${fib(x)}" x++ } }
You can get full JavaFx code here. You can just copy the
fib
function and the body of thesetup
function to your Android project.
Try clicking on the circle in this example. After around 30-40th click our naive computation is going to become quite slow and you would immediately see how the main UI thread freezes, because the animation stops running during UI freeze.
A typical UI application has a number of elements with a lifecycle. Windows, UI controls, activities, views, fragments and other visual elements are created and destroyed. A long-running coroutine, performing some IO or a background computation, can retain references to the corresponding UI elements for longer than it is needed, preventing garbage collection of the whole trees of UI objects that were already destroyed and will not be displayed anymore.
The natural solution to this problem is to associate a Job object with each UI object that has a lifecycle and create all the coroutines in the context of this job. But passing associated job object to every coroutine builder is error-prone, it is easy to forget it. For this purpose, CoroutineScope interface could be implemented by UI owner, and then every coroutine builder defined as an extension on CoroutineScope inherits UI job without explicitly mentioning it. For the sake of simplicity, MainScope() factory can be used. It automatically provides Dispatchers.Main
and parent job.
For example, in Android application an Activity
is initially created and is destroyed when it is no longer needed and when its memory must be released. A natural solution is to attach an instance of a Job
to an instance of an Activity
:
abstract class ScopedAppActivity: AppCompatActivity(), CoroutineScope by MainScope() { override fun onDestroy() { super.onDestroy() cancel() // CoroutineScope.cancel } }
Now, an activity that is associated with a job has to extend ScopedAppActivity
class MainActivity : ScopedAppActivity() { fun asyncShowData() = launch { // Is invoked in UI context with Activity's job as a parent // actual implementation } suspend fun showIOData() { val deferred = async(Dispatchers.IO) { // impl } withContext(Dispatchers.Main) { val data = deferred.await() // Show data in UI } } }
Every coroutine launched from within a MainActivity
has its job as a parent and is immediately cancelled when activity is destroyed.
To propagate activity scope to its views and presenters, multiple techniques can be used:
class ActivityWithPresenters: ScopedAppActivity() { fun init() { val presenter = Presenter() val presenter2 = ScopedPresenter(this) } } class Presenter { suspend fun loadData() = coroutineScope { // Nested scope of outer activity } suspend fun loadData(uiScope: CoroutineScope) = uiScope.launch { // Invoked in the uiScope } } class ScopedPresenter(scope: CoroutineScope): CoroutineScope by scope { fun loadData() = launch { // Extension on ActivityWithPresenters's scope } } suspend fun CoroutineScope.launchInIO() = launch(Dispatchers.IO) { // Launched in the scope of the caller, but with IO dispatcher }
Parent-child relation between jobs forms a hierarchy. A coroutine that performs some background job on behalf of the view and in its context can create further children coroutines. The whole tree of coroutines gets cancelled when the parent job is cancelled. An example of that is shown in the "Children of a coroutine" section of the guide to coroutines.
The fix for the blocking operations on the main UI thread is quite straightforward with coroutines. We'll convert our "blocking" fib
function to a non-blocking suspending function that runs the computation in the background thread by using withContext function to change its execution context to Dispatchers.Default that is backed by the background pool of threads. Notice, that fib
function is now marked with suspend
modifier. It does not block the coroutine that it is invoked from anymore, but suspends its execution when the computation in the background thread is working:
suspend fun fib(x: Int): Int = withContext(Dispatchers.Default) { if (x <= 1) x else fib(x - 1) + fib(x - 2) }
You can get full code here.
You can run this code and verify that UI is not frozen while large Fibonacci numbers are being computed. However, this code computes fib
somewhat slower, because every recursive call to fib
goes via withContext
. This is not a big problem in practice, because withContext
is smart enough to check that the coroutine is already running in the required context and avoids overhead of dispatching coroutine to a different thread again. It is an overhead nonetheless, which is visible on this primitive code that does nothing else, but only adds integers in between invocations to withContext
. For some more substantial code, the overhead of an extra withContext
invocation is not going to be significant.
Still, this particular fib
implementation can be made to run as fast as before, but in the background thread, by renaming the original fib
function to fibBlocking
and defining fib
with withContext
wrapper on top of fibBlocking
:
suspend fun fib(x: Int): Int = withContext(Dispatchers.Default) { fibBlocking(x) } fun fibBlocking(x: Int): Int = if (x <= 1) x else fibBlocking(x - 1) + fibBlocking(x - 2)
You can get full code here.
You can now enjoy full-speed naive Fibonacci computation without blocking the main UI thread. All we need is withContext(Dispatchers.Default)
.
Note that because the fib
function is invoked from the single actor in our code, there is at most one concurrent computation of it at any given time, so this code has a natural limit on the resource utilization. It can saturate at most one CPU core.
This section covers various advanced topics.
Let us write the following code in setup
to visualize the order of execution when coroutine is launched from the UI thread:
fun setup(hello: Text, fab: Circle) { fab.onMouseClicked = EventHandler { println("Before launch") GlobalScope.launch(Dispatchers.Main) { println("Inside coroutine") delay(100) println("After delay") } println("After launch") } }
You can get full JavaFx code here.
When we start this code and click on a pinkish circle, the following messages are printed to the console:
Before launch After launch Inside coroutine After delay
As you can see, execution immediately continues after launch, while the coroutine gets posted onto the main UI thread for execution later. All UI dispatchers in kotlinx.coroutines
are implemented this way. Why so?
Basically, the choice here is between "JS-style" asynchronous approach (async actions are always postponed to be executed later in the event dispatch thread) and "C#-style" approach (async actions are executed in the invoker thread until the first suspension point). While, C# approach seems to be more efficient, it ends up with recommendations like "use yield
if you need to ....". This is error-prone. JS-style approach is more consistent and does not require programmers to think about whether they need to yield or not.
However, in this particular case when coroutine is started from an event handler and there is no other code around it, this extra dispatch does indeed add an extra overhead without bringing any additional value. In this case an optional CoroutineStart parameter to launch, async and actor coroutine builders can be used for performance optimization. Setting it to the value of CoroutineStart.UNDISPATCHED has the effect of starting to execute coroutine immediately until its first suspension point as the following example shows:
fun setup(hello: Text, fab: Circle) { fab.onMouseClicked = EventHandler { println("Before launch") GlobalScope.launch(Dispatchers.Main, CoroutineStart.UNDISPATCHED) { // <--- Notice this change println("Inside coroutine") delay(100) // <--- And this is where coroutine suspends println("After delay") } println("After launch") } }
You can get full JavaFx code here.
It prints the following messages on click, confirming that code in the coroutine starts to execute immediately:
Before launch Inside coroutine After launch After delay