In an Android app, Kotlin flows are typically collected from the UI layer to display data updates on the screen. However, you want to collect these flows making sure you’re not doing more work than necessary, wasting resources (both CPU and memory) or leaking data when the view goes to the background.
In this article, you’ll learn how the
Flow.flowWithLifecycle APIs protect you from wasting resources and why they’re a good default to use for flow collection in the UI layer.
It’s recommended to expose the
Flow<T> API from lower layers of your app hierarchy regardless of the flow producer implementation details. However, you should also collect them safely.
A cold flow backed by a channel or using operators with buffers such as
shareIn is not safe to collect with some of the existing APIs such as
LifecycleCoroutineScope.launchWhenX, unless you manually cancel the
Job that started the coroutine when the activity goes to the background. These APIs will keep the underlying flow producer active while emitting items into the buffer in the background, and thus wasting resources.
Note: A cold flow is a type of flow that executes the producer block of code on-demand when a new subscriber collects.
For example, consider this flow that emits Location updates using
Collecting this flow from the UI layer using any of the aforementioned APIs keeps the flow emitting locations even if the view is not displaying them in the UI! See the example below:
lifecycleScope.launchWhenStarted suspends the execution of the coroutine. New locations are not processed, but the
callbackFlow producer keeps sending locations nonetheless. Using the
launchIn APIs are even more dangerous as the view keeps consuming locations even if it’s in the background! Which could potentially make your app crash.
To solve this issue with these APIs, you’d need to manually cancel collection when the view goes to the background to cancel the
callbackFlow and avoid the location provider emitting items and wasting resources. For example, you could do something like the following:
That’s a good solution, but that’s boilerplate, friends! And if there’s a universal truth about Android developers, it’s that we absolutely detest writing boilerplate code. One of the biggest benefits of not having to write boilerplate code is that with less code, there are fewer chances of making a mistake!
Now that we all are on the same page and know where the problem lies, it’s time to come up with a solution. The solution needs to be 1) simple, 2) friendly or easy to remember/understand, and more importantly 3) safe! It should work for all use cases regardless of the flow implementation details.
Without further ado, the API you should use is
LifecycleOwner.addRepeatingJob available in the lifecycle-runtime-ktx library. Take a look at the following code:
addRepeatingJob takes a
Lifecycle.State as a parameter that is used to automatically create and launch a new coroutine with the block passed to it when the lifecycle reaches that
state, and cancel the ongoing coroutine when the lifecycle falls below the
This avoids any boilerplate code since the associated code to cancel the coroutine when it’s no longer needed is automatically done by
addRepeatingJob. As you could guess, it’s recommended to call these APIs in the activity’s
onCreate or fragment’s
onViewCreated methods to avoid unexpected behaviors. See the example below using fragments:
Note: These APIs are available in the
lifecycle:lifecycle-runtime-ktx:2.4.0-alpha01library or later.
Using repeatOnLifecycle under the hood
To provide more flexible APIs and preserve the calling
suspend Lifecycle.repeatOnLifecycle function is also available for you to use.
repeatOnLifecycle suspends the calling coroutine, re-launches the block when the lifecycle moves in and out of the target
state, and resumes the calling coroutine when the
Lifecycle is destroyed.
This API is helpful whenever you need to do one time setup tasks that need to suspend before doing the repeating work. See example below:
You can also use the
Flow.flowWithLifecycle operator when you have only one flow to collect. This API also uses the
suspend Lifecycle.repeatOnLifecycle function under the hood, and emits items and cancels the underlying producer when the
Lifecycle moves in and out of the target state.
Note: This API name takes the
Flow.flowOn(CoroutineContext)operator as a precedent since
CoroutineContextused to collect the upstream flow while leaving the downstream unaffected. Also, similar to
Flow.flowWithLifecycleadds a buffer in case the consumer doesn’t keep up with the producer. This is due to the fact that its implementation uses a
Configuring the underlying producer
Even if you use these APIs, watch out for hot flows that could waste resources even if they aren’t collected by anyone! There are some valid use cases for them, but do keep that in mind and document it if needed. Having the underlying flow producer active in the background, even if wasting resources, can be beneficial for some use cases: you instantly have fresh data available rather than catching up and temporarily showing stale data. Depending on the use case, decide whether the producer needs to be always active or not.
MutableSharedFlow APIs expose a
subscriptionCount field that you can use to stop the underlying producer when
subscriptionCount is zero. By default, they will keep the producer active as long as the object that holds the flow instance is in memory. There are some valid use cases for this though, for example, a
UiState exposed from the ViewModel to the UI using
StateFlow. That’s ok! This use case demands the ViewModel to always provide the latest UI state to the View.
Flow.shareIn operators can be configured with the sharing started policy for this.
WhileSubscribed() will stop the underlying producer when there are no active observers! On the contrary,
Lazily will keep the underlying producer active as long as the
CoroutineScope they use is active.
Note: The APIs shown in this article are a good default to collect flows from the UI and should be used regardless of the flow implementation detail. These APIs do what they need to do: stop collecting if the UI isn’t visible on screen. It’s up to the flow implementation if it should be always active or not.
Safe Flow collection in Jetpack Compose
Flow.collectAsState function is used in Compose to collect flows from composables and represent the values as
State<T> to be able to update Compose UI. Even if Compose doesn’t recompose the UI when the host activity or fragment is in the background, the flow producer is still active and can waste resources. Compose can suffer from the same problem as the View system.
When collecting flows in Compose, use the
Flow.flowWithLifecycle operator as follows:
In Compose, side effects must be performed in a controlled environment. Therefore,
LifecycleOwner.addRepeatingJob is not safe to use. Instead, use
LaunchedEffect to create a coroutine that follows the composable’s lifecycle. In its block, you could call the suspend
Lifecycle.repeatOnLifecycle if you need it to re-launch a block of code when the host lifecycle is in a certain
Comparison with LiveData
You might’ve noticed that this API behaves similarly to
LiveData, and that’s true!
LiveData is aware of Lifecycle, and its restarting behavior makes it ideal for observing streams of data from the UI. And that’s also the case for the
suspend Lifecycle.repeatOnLifecycle, and
Collecting flows using these APIs is a natural replacement for
LiveData in Kotlin-only apps. If you use these APIs for flow collection,
LiveData doesn’t offer any benefits over coroutines and flow. Even more, flows are more flexible since they can be collected from any
Dispatcher and they can be powered with all its operators. As opposed to
LiveData, which has limited operators available and whose values are always observed from the UI thread.
StateFlow support in data binding
On a different note, one of the reasons you might be using
LiveData is because it’s supported by data binding. Well, so is
StateFlow! For more information about
StateFlow support in data binding, check out the official documentation.
suspend Lifecycle.repeatOnLifecycle or
Flow.flowWithLifecycle APIs to safely collect flows from the UI layer in Android.