I have been building reactive, fully asynchronous, high-performance, multiplatform apps for multiple years now. Over time, I have stumbled upon a few difficult, tricky-to-find, hard-to-debug issues with state management. In this article, I would like to share my experience with you so that hopefully you won’t have to go through the same problems I went through, and to propose a new approach to state management I have never seen before that will free you of these issues for good.

So the story begins when reactive apps using MVI / MVVM+ became popular and I started taking my first steps in learning to build them. In this article, I will mostly be talking about MVI because state management in MVI is slightly more advanced so the examples are going to be more illustrative, but the same problems and solutions apply to MVVM (which also has state(s) to manage).

Remember that time when UDF became a fad and we all started using it? That time produced very distinct bugs in some applications that I will call “inconsistent state problem” (ICS). Let me show you a real-world example:

data class UIState(
    val isLoading: Boolean = true,
    val error: Exception? = null,
    val items: List<Item>? = null,
)

val isLoading = MutableStateFlow<Boolean>(true)
val error = MutableStateFlow<Exception?>(null)
val items = MutableStateFlow<List<Item>?>(null)

val items = flow { 
    api.getLatestItems()
}

val username = MutableStateFlow<String>("")

fun onUsernameChanged(value: String) = username.value = value

val isLoading = MutableStateFlow<Boolean>(true)
val error = MutableStateFlow<Exception?>(null)
val items = MutableStateFlow<List<Item>?>(null)

data class UIState {
    val isLoading: Boolean = true,
    val error: Exception? = null,
    val items: List<Item>? = null,
}

internal sealed interface EditProfileState {

    data object Loading : EditProfileState
    
    data class Error(val e: Exception?) : EditProfileState
    
    data object Success : EditProfileState
    
    data object DisplayingAccountDeleted : EditProfileState
    
    data class EditingProfile(
        val email: String, // data from repository
        val name: Input, // value the user typed
    ) : EditProfileState
}

val state = MutableStateFlow<EditProfileState>(Loading)

fun onSaveChangesClicked(state: EditingProfile) {
    state.value = Loading
    validateNameAsync(state)
}

fun showValidationError(e: Exception) { /* display a snackbar etc */ }  

fun validateNameAsync(previous: EditingProfile) = launch {
    try {
      repository.verifyNameIsUnique(previous.name)
      state.value = Success
    } catch (e: Exception) {
        state.value = previous
        showValidationError(e)
    } 
}

Solving the Problem #2: Managing the type of the object

Kotlin is a statically typed language, and because of that, we need to cast the state to a particular value safely to be sure we don’t crash the app. We need to cast because sometimes we want to access some properties of the previous state if they are present.

For example, whenever we want to update the current state with the new data from an outside source (remember UDF stuff above?), we don’t know what the current state is. Kotlin’s syntax is quite annoying in this case, but by doing all of this, we are explicitly following our contract during compilation and thus getting the benefits of our previous improvements. For example:

class EditProfileContainer(
    private val repo: UserRepository,
) {
    val state = MutableStateFlow<EditProfileState>(Loading)
    
    override suspend fun onSubscribed() { // (1)
        repo.getUserProfileFlow().collect { user: User ->
            state.update { state: EditProfileState -> // (2)
                val current = state as? EditingProfile // (3)
                EditingProfile( // (4)
                    email = user.email,
                    name = current?.name ?: Input.Valid(user.name ?: ""), // (5)
                )
            }
        }
    }
    
    // not using the "update()" function for illustration purposes
    fun onNameChange(value: String) { 
        state.value = (state.value as? EditingProfile)?.let { 
            it.copy(name = Input.Valid(value))
        } ?: state.value // (6)
    } 
}

1. This is important: We should only watch for persistent state changes when the user sees the page, not in the background. Otherwise, we are wasting resources for nothing and the user may never see the changes. This requirement is new, it appeared because our state is now a Hot Stream of data, and requires a custom lifecycle handling implementation.

2. Each time we get an update from our data source, we want to use that data to transition from a loading state to a new EditingProfile state. Why? Because the new data has arrived, so there is no point in keeping the loading indicator present. In any case, we don’t know if there is a point now.

3. We check for the type of the current state safely to see if the state is already containing some data. In our example, a “Name” form field. We now have to safely handle both cases — when the value is and is not present.

4. We assemble a state where we are no longer loading and are supposed to display the data instead, but we need to provide the required values now. Otherwise, if our state is invalid, we won’t be able to compile the app

5. We are now forced to first check if the user has already made changes to their name.

• If yes, we just use the previous value. We have successfully preserved the changes the user has made.
• If not, we first check if the user has set a value in the remote user object. It’s a good UX to show the user their previous username if they want to make a small change.
• If neither are present, we suggest the user add a username and populate the input form with an empty string.

6. If the state is not of the type we wanted, we just skip the operation. The user was probably spamming buttons or the processes are being executed in parallel and the state is changing.

I know — the code above looks slightly more complicated at first, but I would argue we can solve that easily as well:

• We can abstract the logic of onSubscribe invocations by using or creating an architectural framework.
• We can simplify the visual look and boilerplate of those type casts by creating a nice DSL that will do all the type checking for us.
• For each specific use case, we can create simple extensions to do the boilerplate for us if we don’t like how our code looks. For example, we could create a function:

fun Input?.input(default: String? = null) = this ?: Input.Valid(default ?: "")

// usage:

EditingProfile(
   name = current?.name.input(user.name), 
)

Here’s how my code for this feature looks after some refactoring:

val store = store<EditProfileState>(Loading) { 
    whileSubscribed { 
        repo.user.collect { user ->
            updateState { 
                val current: EditingProfile? = typed<EditingProfile>()
                EditingProfile(
                    email = user.email,
                    name = current?.name.input(user.name),
                )
            } 
        }
    } 
    
    fun onNameChanged(value: String) = updateState<EditingProfile, _> { // this: EditingProfile
        copy(name = value.input())
    } 
} 

Not so scary anymore? My opinion is that this not only gets all the benefits we discussed before but also looks and reads like English, which is golden for our fellow teammates and us in the long term.

So now we just got to solve our last problem, the most insidious one and one you may not have even been aware of till now.

Step 4: Making State Updates Parallel

Whenever we create applications in the modern, reactive world, our users expect nothing less than to have their experience always be fluid, consistent, performant, and stable. With the rising demands on the quality of client applications, we developers have to put in more and more effort into ensuring that we always deliver the best possible UX with animations, progressive content loading, database caching, and reactive data streaming. This demands for us to do 2 things:

1. We make our applications fully reactive and multithreaded
2. We execute operations in parallel and in the background
3. We ensure our app handles errors and frees resources during concurrent operations
4. We display proper feedback to the user at all times

Remember the times when we could just slap a blank screen while the data was loading and show a full-screen error if it wasn’t able to, and the users wouldn’t mind much? I think those times are gone, and now a blank screen for even a second can be an easy 1⭐️ review and a full-screen loading indicator will now ensue the wrath of the UX designer on your team complaining about retention metrics.

Ensuring all 4 of the criteria are met is extremely challenging and requires in-depth knowledge of parallelism, thread synchronization principles, and asynchronous frameworks like Coroutines.

For a practical example, let’s say we made our EditProfileContainer run on a background thread and we added an input validation that checks if the username is unique.

fun onNameChanged(value: String) = updateState<EditingProfile, _> { // this: EditingProfile
    val new = copy(name = value.input())
    launchValidateUsername(new)
    new
}

fun launchValidateUsername(state: EditingProfile) = launch {
    val unique = repo.verifyUsernameIsUnique(state.name.value)
    if (!unique) updateState {
        state.copy(name = Input.Error(name.value, "Username is not unique")
    }
}

The problem is, when the user is editing their name and stops, the username is sent to be verified, but then if they click “Submit”, the order of state transactions is now undefined because they are parallel now and we have captured the state that went out of the scope of the transaction.

This leads to the following happening, as just one example among others:

1. The user changes their name and it is unique
2. We start validating the user name, but the operation is quite slow
3. The user immediately clicks “Submit”
4. We send the value to be saved and set the state to Loading
5. While we are trying to save changes, the validation result comes in!
6. We update the state to restore the previous value
7. The user’s screen flickers and the loading indicator disappears
8. The user, not understanding what has happened and why there was no feedback, clicks the “Submit” button again.
9. We start updating the state and show a loading indicator again
10. The previous save result comes as a success and the user sees a message that their changes were saved
11. The next submitted username result comes in. The name is no longer unique and the function throws an error
12. The screen flickers and the user sees a message saying their changes could not be saved, despite being saved in reality, just a second after seeing the success message

This is such a terrible user experience! And we just tried to simply do the work on the background thread. The reason this happened is that our state transactions are not serializable.

Step 5: Serializable State Transactions

The term “serializable” actually comes from database architecture (DBA) terminology and has nothing to do with REST or JSON structures.

If you are not familiar with DBA’s quirks, the same problem we just faced existed a long time ago with databases, as their transactions are parallel as well. One transaction can read the data, and while it’s running, another can change that data, leading to a race between two transactions and an undefined result for both.

There are multiple ways database frameworks solve this (and they are ultra-complicated) so we are not going to deep dive into them right now. If you want to learn more, search for “Database transaction isolation”. Instead, let’s solve this problem for good in our application.

But before we do, I must mention that I have never seen this topic even being brought up once in the Kotlin development community before, so what I’m doing here is something either completely new (or a rather specific case of inventing the wheel, your decision), and that’s the main reason I am writing this article.

I investigated this issue on my own and I concluded that most client apps and architectural frameworks use the following approaches:

1. Making all operations sequential
   – For example, with MVI, we define our Intents as a queue of commands (e.g. with a Channel), and they are processed sequentially as a result. We already said that this approach won’t do for our highly parallel reactive application
2. Using only the Main (or a single) thread for updating the state
   – Frameworks such as MVIKotlin, Orbit MVI, and most others employ this strategy by disallowing background thread state updates. As we said, our goal is to make a fully async, performant application
3. Splitting the state into multiple streams, updated atomically between threads
   – This is the approach of MVVM / MVVM+, but by going back to it, we would lose all the other benefits we just got
4. Making all states persistent — this one is self-explanatory, but we can’t cover all the possible use cases for this. There are quite a bunch of imperative/stateful platform APIs to deal with, as an example
5. Using various flags in the state to indicate the progress of operations and constantly managing all of them
   – For example, we could add a flag isValidatingUsername to our state and check it to decide whether to transition the user to the next state or not and/or cancel the update job when we send the data
   – I don’t believe this solution to be satisfactory, not only because we are going back to where we started, trying to get rid of meaningless values, but because also the complexity of such solutions can grow exponentially on us
6. Manually synchronizing each parallel data source using primitives such as Semaphores and Mutexes
   – This one is actually good and is (spoiler) the basis for our solution, but it’s super cumbersome to create and manage locks for everything we have, and it also shifts the responsibility for atomicity downward to the business logic that wants nothing to do with our presentation layer states.
   – It will also ultimately slow down our app when we face the usual problems of synchronized code such as deadlocks, livelocks, and thread starvation

I propose something different — why don’t we just learn from databases and make our state transactions serializable? The implementation of this solution is straightforward as well:

private val _states = MutableStateFlow(initial)
val states: StateFlow<S> = _states.asStateFlow()
private val stateMutex = Mutex()

suspend fun withState(
    block: suspend S.() -> Unit
) = stateMutex.withReentrantLock { block(states.value) }

suspend fun updateState(
    transform: suspend S.() -> S
) = stateMutex.withReentrantLock { _states.update { transform(it) } }

We can extract this code to a delegated interface and be done with this problem forever.

P.S. For those who know the details, this makes our state transactions correspond to Postgres’ SERIALIZABLE transaction isolation level.

I must note that using a reentrant lock here is super important, as we want to support nested state transactions for several edge use cases.

“And that’s it?” — you may ask.

Literally yes. There is a small caveat to this though: you must understand that we introduced synchronization logic to our code which will make the state updates sequential by nature. The lock introduces some overhead in terms of performance each time we try to update the state, so you may want to consider creating a “fallback” approach or an option to disable serializable state transactions for a given update operation or a whole BLoC to prevent resources from being wasted on synchronization when state updates are very frequent. In my personal experience, these slow-downs are seldom noticeable and will not lead to jank if run on the main thread.

Afterword

The biggest benefit of the approach is not solving a single problem or accounting for an edge case, in my opinion, but is that we never have to think about problems of state management again by changing the paradigm under which we operate. We can write fully asynchronous code, run as many parallel processes as we want, and create as complicated state hierarchies and features as we want, all without ever stopping even for a second to doubt if our code will always behave as expected. Using this approach freed an enormous amount of cognitive resources of mine when creating applications, and that’s ultimately what I value the most. I believe that writing code should be an easy, fluid process, where you ideally don’t have to stop to consider another edge case or a possible issue.

I hope that armed with knowledge from this article, you will now be able to make an educated opinion and grab the practices outlined here or implement ideas that will help your apps become better and your workflow more fluid.

After reading this, you may still have a couple of questions left:

1. Where can I see this approach in action?
2. Where can I see an example implementation?
3. What if I don’t want to do all of the things mentioned above on my own, and just want to have a ready-made solution I can set up?

I got you here. Everything we discussed in this article I implemented fully in the architectural framework that I and my teams are using — FlowMVI.

The framework:

• Is making state transactions fully serializable with reentrant locks and the ability to disable serialization for a single transaction or a whole business logic unit
• Has a nice DSL like the one above that simplifies type checks and safe state updates
• Manages the subscription lifecycle for you to run, stop, and relaunch state update jobs
• Allows you to make business logic fully async and switch to any number of threads you want
• Is implemented using coroutines as a first-class citizen
• Makes states consistent and allows to easily unify them into a single source of truth by design
• Handles all errors for you and allows you to update the state accordingly without awkward try/catches for every function
• Abstracts away all the nitty-gritty of state updates and parallel processing so that you don’t have to worry about them ever
• Manages background jobs for you and frees resources at the right moment automatically
• Supports caching, atomic, sequential, or parallel command processing and decomposition of business logic into asynchronous data sources
• Supports persisting your state as needed for an additional layer of safety

I will be happy if you give it a try and let me know what you think of this new approach to state management!

This article is previously published on proandroiddev.com