A Safer Way To Collect Flows From Android UIs

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 LifecycleOwner.addRepeatingJob, Lifecycle.repeatOnLifecycle, and Flow.flowWithLifecycle APIs protect you from wasting resources and why they’re a good default to use for flow collection in the UI layer.

Partner with aster.cloud
for your next big idea.
Let us know here.

Wasting resources

A cold flow backed by a channel or using operators with buffers such as <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/buffer.html" target="_blank" rel="noopener nofollow">buffer</a>, <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/conflate.html" target="_blank" rel="noopener nofollow">conflate</a>, <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow-on.html" target="_blank" rel="noopener nofollow">flowOn</a>, or <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/share-in.html" target="_blank" rel="noopener nofollow">shareIn</a> is not safe to collect with some of the existing APIs such as <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html" target="_blank" rel="noopener nofollow">CoroutineScope.launch</a>, <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/launch-in.html" target="_blank" rel="noopener nofollow">Flow<T>.launchIn</a>, or <a class="ck ig" href="https://developer.android.com/reference/kotlin/androidx/lifecycle/LifecycleCoroutineScope" target="_blank" rel="noopener nofollow">LifecycleCoroutineScope.launchWhenX</a>, 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 <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/callback-flow.html" target="_blank" rel="noopener nofollow">callbackFlow</a>:

// Implementation of a cold flow backed by a Channel that sends Location updates
fun FusedLocationProviderClient.locationFlow() = callbackFlow<Location> {
    val callback = object : LocationCallback() {
        override fun onLocationResult(result: LocationResult?) {
            result ?: return
            try { offer(result.lastLocation) } catch(e: Exception) {}
        }
    }
    requestLocationUpdates(createLocationRequest(), callback, Looper.getMainLooper())
        .addOnFailureListener { e ->
            close(e) // in case of exception, close the Flow
        }
    // clean up when Flow collection ends
    awaitClose {
        removeLocationUpdates(callback)
    }
}

Note: Internally, <em class="el">callbackFlow</em> uses a channel, which is conceptually very similar to a blocking queue, and has a default capacity of 64 elements.

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:

class LocationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Collects from the flow when the View is at least STARTED and
        // SUSPENDS the collection when the lifecycle is STOPPED.
        // Collecting the flow cancels when the View is DESTROYED.
        lifecycleScope.launchWhenStarted {
            locationProvider.locationFlow().collect {
                // New location! Update the map
            } 
        }
        // Same issue with:
        // - lifecycleScope.launch { /* Collect from locationFlow() here */ }
        // - locationProvider.locationFlow().onEach { /* ... */ }.launchIn(lifecycleScope)
    }
}

lifecycleScope.launchWhenStarted suspends the execution of the coroutine. New locations are not processed, but the callbackFlow producer keeps sending locations nonetheless. Using the lifecycleScope.launch or 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.

Read More  Faster Jetpack Compose View Interop With App Startup And Baseline Profile

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:

class LocationActivity : AppCompatActivity() {

    // Coroutine listening for Locations
    private var locationUpdatesJob: Job? = null

    override fun onStart() {
        super.onStart()
        locationUpdatesJob = lifecycleScope.launch {
            locationProvider.locationFlow().collect {
                // New location! Update the map
            } 
        }
    }

    override fun onStop() {
        // Stop collecting when the View goes to the background
        locationUpdatesJob?.cancel()
        super.onStop()
    }
}

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!

LifecycleOwner.addRepeatingJob

Without further ado, the API you should use is <strong class="hk jt">LifecycleOwner.addRepeatingJob</strong> available in the lifecycle-runtime-ktx library. Take a look at the following code:

class LocationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Collects from the flow when the lifecycle is at least STARTED and
        // STOPS the collection when it's STOPPED.
        // It automatically restarts collecting when the lifecycle is STARTED again.
        lifecycleOwner.addRepeatingJob(Lifecycle.State.STARTED) {
            locationProvider.locationFlow().collect {
                // New location! Update the map
            } 
        }
    }
}

addRepeatingJob takes a <a class="ck ig" href="https://developer.android.com/reference/android/arch/lifecycle/Lifecycle.State" target="_blank" rel="noopener nofollow">Lifecycle.State</a> 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 state.

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:

Read More  The Next Wave Of 5G To Arrive Early For Telstra Customers
class LocationFragment: Fragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        // ...
        viewLifecycleOwner.addRepeatingJob(Lifecycle.State.STARTED) {
            locationProvider.locationFlow().collect {
                // New location! Update the map
            } 
        }
    }
}

Note: These APIs are available in the <em class="el">lifecycle:lifecycle-runtime-ktx:2.4.0-alpha01</em> library or later.

Using repeatOnLifecycle under the hood

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:

class LocationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        lifecycleScope.launch {
            // One time setup task
            val expensiveObject = createExpensiveObject()

            lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
                // Repeat when the lifecycle is STARTED, cancel when STOPPED
                // Do work with expensive object
            }

            // `lifecycle` is DESTROYED when the coroutine resumes. repeatOnLifecycle
            // suspends the execution of the coroutine until the lifecycle is DESTROYED.
        }
    }
}

Flow.flowWithLifecycle

class LocationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        locationProvider.locationFlow()
            .flowWithLifecycle(this, Lifecycle.State.STARTED)
            .onEach {
                // New location! Update the map
            }
            .launchIn(lifecycleScope) 
    }
}

Note: This API name takes the Flow.flowOn(CoroutineContext) operator as a precedent since Flow.flowWithLifecycle changes the CoroutineContext used to collect the upstream flow while leaving the downstream unaffected. Also, similar to flowOn, Flow.flowWithLifecycle adds a buffer in case the consumer doesn’t keep up with the producer. This is due to the fact that its implementation uses a callbackFlow.

Configuring the underlying producer

Read More  Developer Tips And Guides: Common Policy Violations And How You Can Avoid Them

The MutableStateFlow and 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.

Similarly, the <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/state-in.html" target="_blank" rel="noopener nofollow">Flow.stateIn</a> and <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/share-in.html" target="_blank" rel="noopener nofollow">Flow.shareIn</a> operators can be configured with the sharing started policy for this. <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-sharing-started/-while-subscribed.html" target="_blank" rel="noopener nofollow">WhileSubscribed()</a> will stop the underlying producer when there are no active observers! On the contrary, <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-sharing-started/-eagerly.html" rel="noopener nofollow">Eagerly</a> or <a class="ck ig" href="https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-sharing-started/-lazily.html" rel="noopener nofollow">Lazily</a> 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

When collecting flows in Compose, use the Flow.flowWithLifecycle operator as follows:

@Composable
fun LocationScreen(locationFlow: Flow<Flow>) {

    val lifecycleOwner = LocalLifecycleOwner.current
    val locationFlowLifecycleAware = remember(locationFlow, lifecycleOwner) {
        locationFlow.flowWithLifecycle(lifecycleOwner.lifecycle, Lifecycle.State.STARTED)
    }

    val location by locationFlowLifecycleAware.collectAsState()

    // Current location, do something with it
}

Notice that you need to <a class="ck ig" href="https://developer.android.com/jetpack/compose/state" target="_blank" rel="noopener nofollow">remember</a> the flow that is aware of the lifecycle with locationFlow and lifecycleOwner as keys to always use the same flow unless one of the keys change.

In Compose, side effects must be performed in a controlled environment. Therefore, LifecycleOwner.addRepeatingJob is not safe to use. Instead, use <a class="ck ig" href="https://developer.android.com/reference/kotlin/androidx/compose/runtime/package-summary#launchedeffect_1" target="_blank" rel="noopener nofollow">LaunchedEffect</a> 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 State.

Comparison with LiveData

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

Use the LifecycleOwner.addRepeatingJob, suspend Lifecycle.repeatOnLifecycle or Flow.flowWithLifecycle APIs to safely collect flows from the UI layer in Android.

By Manuel Vivo
Source Medium

For enquiries, product placements, sponsorships, and collaborations, connect with us at [email protected]. We'd love to hear from you!
Our humans need coffee too! Your support is highly appreciated, thank you!

Related Topics
You May Also Like