HTML Manuscript

The frozen UI problem and callback hell - the main thread

Before we go deeper into what coroutines are, we need to understand the fundamental problem that Android developers have had to deal with since the early days of the platform. This problem comes from one key concept: the Main Thread.

Every Android application you run lives and dies inside one main process. Inside that process there is one extremely important thread, known as the Main Thread or the UI Thread.

This thread is responsible for everything the user sees and interacts with:

• Drawing the interface: updating views and calling @Composable functions.
• Handling events: reacting to clicks, scrolling and text input.
• Animations: smoothly moving elements on the screen.

The UI thread is essentially an infinite event loop that must run at least at 60 frames per second (newer devices can refresh at 144 Hz). If it ever stops working, even for a fraction of a second, the user immediately notices it. The application stutters and lags. On 60 Hz screens, we have about 16 ms to perform all operations, including UI rendering (Fig. 2.1).

Let us analyze an example:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            AnrappTheme {
                BlockingUiDemoScreen()
            }
        }
    }
}

@Composable
fun BlockingUiDemoScreen() {
    var statusText by remember { mutableStateOf("Press the button to start the operation.") }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp).background(Color.Cyan),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        Text(
            text = "UI thread blocking demonstration",
        )
        Spacer(modifier = Modifier.height(50.dp))

        Text(
            text = statusText,
            fontSize = 18.sp,
            textAlign = TextAlign.Center,
            modifier = Modifier.height(80.dp)
        )
        Spacer(modifier = Modifier.height(20.dp))

        Button(
            onClick = {
                statusText = "Operation started..."

                try {
                    Thread.sleep(10000)
                } catch (e: InterruptedException) {
                }

                statusText = "Operation completed!"
            },
            modifier = Modifier.fillMaxWidth()
        ) {
            Text("Run a 10-second blocking operation")
        }
        Spacer(modifier = Modifier.height(40.dp))

        var sliderPosition by remember { mutableStateOf(0f) }
        Slider(
            value = sliderPosition,
            onValueChange = { sliderPosition = it }
        )
    }
}

Notice that the UI contains a button and a slider. Inside the button's onClick function we have the following code:

Button(
    onClick = {
        statusText = "Operation started..."

        try {
            Thread.sleep(10000)
        } catch (e: InterruptedException) {
        }

        statusText = "Operation completed!"
    },
    modifier = Modifier.fillMaxWidth()
) {
    Text("Run a 10-second blocking operation")
}

We call Thread.sleep(10000), which blocks the UI thread for 10 seconds. During this time:

• The button will not show its click animation.
• Other animations on the screen will be frozen.
• If the user interacts with the screen in any way, they will receive no response.

The Android operating system quickly notices that our application is not responding to events. After a few seconds it displays the message Application Not Responding (ANR) (Fig. 2.2).

All long-running operations, such as downloading data from the network, reading from a database or performing complex calculations, must run in the background.

For years, before coroutines appeared, background work meant manual thread management. If a developer wanted to download data from the network after clicking a button, the plan had to look like this:

1. In onClick (UI thread): create a new manual Thread object.
2. In the run() method of the new thread (background thread): perform the time-consuming network operation.
3. After the operation finishes: obtain the result, for example user data.
4. Problem: you cannot update the UI, for example a TextView, from this background thread. Doing so will crash the application.
5. Solution: create a Handler object associated with the UI thread.
6. Use handler.post {... } to send the result back to the UI thread, which is the only thread allowed to update the interface safely.

This process was complicated, but it became even worse when operations depended on one another. Imagine downloading user data, then using it to download the user's photo, and finally saving it in a database:

button.setOnClickListener(v -> {
    // 1. Move to the background to fetch the user
    new Thread(() -> {
        User user = api.fetchUser("123");
        
        // 2. Move to the background again to fetch the photo
        new Thread(() -> {
            ProfilePicture pic = api.fetchPicture(user.getPictureUrl());
            
            // 3. Move to the background one more time to save it in the database
            new Thread(() -> {
                database.save(pic);
                
                // 4. Return to the UI thread to show success
                mainThreadHandler.post(() -> {
                    imageView.setImage(pic);
                    textView.setText("Done!");
                });
            }).start();
        }).start();
    }).start();
});

What we see above is callback hell. The code becomes a pyramid of nested calls. It is practically unreadable, impossible to test, and error handling at every step becomes a nightmare.

This is the problem that led to a revolution. We needed a way to write asynchronous code that looked like simple synchronous code, without callbacks and without manually managing threads.

Coroutines

Introduction

After identifying the fundamental problem of blocking the Main Thread, the natural question is: What is the alternative?. For years, many solutions were tried, but Kotlin introduced the model that revolutionized Android programming: coroutines.

To understand their power, we need to define precisely what they are and what they are not.

The most common definition you will encounter says that a coroutine is a lightweight thread. This is a useful simplification, because it helps us understand that coroutines, like threads, can perform some work in the background. However, this comparison is also misleading because it hides their most important property. NOTE!!! - A coroutine is not a thread.

A better and more precise definition is: a suspendable computation.

Think of a coroutine not as a worker, but as a task or a unit of work that can be stopped (suspended) at any moment and resumed later, without blocking the worker (thread) that executes it.

Key difference: coroutine versus thread

• A Thread is managed by the Operating System (OS). It is heavy; creating and maintaining it consumes significant system resources. Switching between threads is costly for the CPU because the system must save the state of one thread and load the state of another.
• A Coroutine is managed by the Kotlin runtime. It is lightweight; in practice, it is an object in memory that tracks the state of a running task. Thousands, or even millions, of coroutines can be launched and managed by a single thread. Switching between coroutines is almost free.

A coroutine is not a thread. A coroutine runs on a thread.

Imagine a kitchen (our application) and a cook (a thread).

Scenario 1: The cook as a traditional thread (blocking model). The cook (UI thread) takes a recipe (task). The first step says: Boil water for 5 minutes. The cook turns on the stove and then stands idle for 5 minutes, staring at the pot. During that time, chaos spreads through the kitchen. The phone rings (user interaction), new guests arrive (animations), but the cook is blocked. They cannot do anything else until the water boils. This is exactly what Thread.sleep() does.

Scenario 2: The cook with coroutines (non-blocking model). The same cook (the same UI thread) takes the same recipe, now represented as a coroutine. The recipe says: Boil water for 5 minutes. The cook starts boiling the water (initiates an I/O operation), then suspends the recipe and puts it aside. Since their hands are free, they immediately move to another task, for example chopping vegetables (handling a click) or seasoning a salad (drawing an animation). When, after 5 minutes, the kettle whistles (the background operation has completed), the cook resumes the first recipe and continues from where it stopped.

In this model, one cook (one thread) juggles many recipes (coroutines) at the same time and never wastes time waiting idly. Let us add here that what we call suspension is not a pause of all work. It is a pause of this specific coroutine on this specific thread. We will explain in a moment who actually performs the work of boiling the water.

Worker thread

We need to clarify what the recipe is in our analogy. It is an entity that we call a function whose execution can be suspended, namely suspend fun.

suspend fun relates to a coroutine in the same way that a class relates to an instance of that class; we can have many instances of the same class:

• suspend fun is a definition or a blueprint. It is only a definition of steps to execute. By itself, it does nothing. It is not active. It does not have a state such as running or suspended.
• A coroutine is an instance or active execution of that blueprint. It is created when you take a suspend fun (or any suspend code block) and actually run it. A coroutine has a state: active, suspended or cancelled. It is the worker that performs the steps from the blueprint.

When you write scope.launch {... } in code (we will explain scope shortly), this launch code block, called a coroutine builder, creates and starts a new coroutine, a new instance of work. This new, live coroutine starts executing the code inside the {...} block. It can work as follows:

1. The coroutine (instance) calls a suspend fun (blueprint).
2. This suspend fun, for example delay, tells the coroutine: I need to wait for 1 second now. You can suspend me.
3. The coroutine (instance) moves to the suspended state. It releases the cook (thread), which can do something else, for example handle the UI.
4. After 1 second, delay completes.
5. The coroutine (instance) is resumed on any free thread and continues from the next line.

The suspend keyword does not mean that the function automatically runs on a background thread. It only means that the function can be suspended. If you perform an expensive operation inside a suspend function, for example heavy mathematical calculations, without explicitly switching the dispatcher (we will discuss dispatchers later), you will still block the calling thread; in this case, the UI thread.

Returning to the question: who boils the water when the cook goes to chop vegetables?

In this analogy, the cook is our UI thread (main thread), which we do not want to block with long operations. But the cook is not the only worker in the kitchen. There are also kitchen assistants (worker/background threads). Our analogy now looks like this:

1. The head chef (UI thread) takes the recipe (coroutine). They read the first step: Boil water for 5 minutes, for example fetch data from the network, which is done by a suspend fun.
2. The head chef does not boil the water personally. That would waste their valuable time because they must handle the UI.
3. Instead, they call a kitchen assistant. They give the assistant a pot of water and say: Put this on the stove (perform the network operation). When it boils, let me know.
4. The assistant goes and actually does the work. They watch the pot, meaning they wait for the network response.
5. Immediately after giving the instruction, the head chef (UI thread) suspends (suspend) this recipe and puts it aside with a note: waiting for water from the assistant.
6. Because their hands are free, the head chef (UI thread) immediately starts chopping vegetables (handles a click) and seasoning a salad (draws an animation).
7. After 5 minutes, the assistant (IO thread) finishes the work. They run to the head chef and say: The water for recipe no. 5 is ready!; the callback signal returns to the main thread.
8. The head chef (UI thread), as soon as they finish chopping the salad, takes suspended recipe no. 5 and resumes (resume) it from the next step.

CoroutineScope

A cook cannot work in a vacuum; they need a kitchen, a space prepared for handling the cook's tasks and equipped with assistants. The kitchen is the environment in which recipes are executed. Similarly, you cannot simply launch a coroutine in the air; you must launch it inside some CoroutineScope. We create and start a new coroutine with the launch method, and we can do this only on a CoroutineScope; for example, scope.launch{}. Then we are saying: I want this recipe (coroutine) to be executed in this kitchen (scope).

Every kitchen (CoroutineScope) has its own rules and resources. These rules are represented by an object of type CoroutineContext. It has a set of attributes for this particular kitchen. The two most important elements in this context are:

• Job (shift manager): the component responsible for lifecycle.
• Dispatcher (head chef of chefs): the component responsible for assigning work.

The Dispatcher, which is part of the CoroutineContext of a given kitchen, has its own assistants (its own thread pool). A Dispatcher is essentially a scheduling strategist. It says on which thread, or thread pool, a given recipe (coroutine) should be executed at a given moment. There are several main head chefs (dispatchers) we can choose:

• Dispatchers.Main: This chef has only one specialized cook under them: the UI thread. Every task you give to this dispatcher will be executed only by that one thread. It is ideal for updating the interface.
• Dispatchers.IO: This chef manages a large shared thread pool, a pool of cooks optimized for input/output tasks such as network and disk operations. When you give it 100 recipes (coroutines), it distributes them efficiently among the available cooks in its pool.
• Dispatchers.Default: This chef also manages a thread pool, but it is optimized for CPU-intensive tasks, for example sorting a huge list.

When a coroutine (recipe) launched on Dispatchers.IO must wait for a network response (it suspends), it returns the assistant (thread) back to the pool so that the assistant can handle another task. When the network response comes back, the coroutine is resumed and gets any free assistant (thread) from the Dispatchers.IO pool to continue its work. A coroutine does not own a thread pool. A coroutine uses the thread pool provided by its Dispatcher.

The second key element of CoroutineScope is Job; in our analogy, it corresponds to the shift manager. It tracks all coroutines currently being cooked in a given scope (kitchen). It acts as a parent for all coroutines launched in that scope. When you launch a coroutine with launch, this function returns a Job object.

val job = scope.launch {... }

Job is the only way to find out what is happening with a coroutine. It works like an interactive order ticket in a restaurant. It stores the current state of the recipe execution:

• New: the order has been accepted but has not started yet.
• Active: the cook is working on it or waiting for the water.
• Completed: the dish is ready.
• Cancelled: the customer left, so we throw the ingredients away.
• Thanks to Job, you can ask programmatically: job.isActive (are we still working?) or job.isCancelled.

In the world of coroutines, every Job can have a parent and children. When you create a CoroutineScope, it contains a main Job (shift manager). When you call launch in this Scope, a new Job is created and automatically becomes a child of the main Job. This creates an unbreakable dependency tree. Two strict rules of structured concurrency apply here:

• Cancellation rule (downward): If you cancel the parent, for example by closing the screen and cancelling its coroutineScope, all children are automatically cancelled. The shift manager says: We are closing the kitchen!, so all cooks immediately stop preparing their dishes. Nobody stays at work after hours.
• Waiting rule (upward): The parent cannot complete its work until all children finish. The shift manager cannot go home until the last assistant finishes washing the dishes.

Summary in our analogy: If CoroutineScope is the kitchen, then:

• Job in the scope is the shift manager. It makes sure nobody works when the restaurant is closed.
• Job returned by launch is the ticket of a specific order. It is pinned to the shift manager's cork board. If the manager removes the ticket from the board and tears it up (cancellation), the cook immediately stops working on it.

Solving the ANR problem

Let us return to the example from the beginning of the chapter. In the previous version, when we clicked the button that called Thread.sleep(10000), the entire application froze. The slider stopped working, buttons did not react, and after a while the system displayed an ANR error. Let us implement code that solves this problem. We will start by adding a recipe, meaning a suspend function.

// Change 1: the 'suspend' keyword
suspend fun fetchDataFromServer(): String {
    println("Coroutine:...")
    // Change 2: 'delay' instead of 'Thread.sleep'
    delay(10000) // delay is also a suspend function
    println("Coroutine:...")
    return "Data downloaded successfully!"
}

What we call suspension is not a pause of all work. It is a pause of this specific coroutine on this specific thread.

• Thread.sleep tells the UI thread: Stand still and do nothing for 10 seconds.
• delay tells the UI thread: I am putting this task on the shelf for 10 seconds. You go handle something else, for example draw the slider. We will return to this later.

Inside the Composable function (CoroutineSolutionScreen), a new line appears:

val scope = rememberCoroutineScope()

This is required because the button's onClick function is a regular function; it is not suspend. We cannot directly call fetchDataFromServer or delay from it. We need a gate or a bridge that allows us to enter the asynchronous world. That bridge is a CoroutineScope associated with the lifecycle of this screen.

It is worth noting that the CoroutineScope obtained through rememberCoroutineScope() in Jetpack Compose uses Dispatchers.Main by default, more precisely Main.immediate. This means that the code inside launch runs on the main thread.

The scope returned by rememberCoroutineScope() is tightly connected with the point in the composition where it was called. If the user leaves this screen and the component is removed from the UI tree, the scope is automatically cancelled. As a result, all operations still running inside it, for example our 10-second data download, are immediately interrupted, preventing memory leaks and wasted resources.

Inside onClick, we see:

Button(onClick = {
statusText = "Operation started..." // 1. Immediate UI update

scope.launch { // 2. Start the coroutine (fire-and-forget)
        val result = fetchDataFromServer() // 3. Suspension point
        statusText = result // 4. Resume and update the UI
    }
})

What happens here step by step?

• The user clicks.
• The text changes to "Operation started...".
• scope.launch creates a new coroutine.
• The coroutine enters fetchDataFromServer, reaches delay(10000) and suspends.
• The UI thread is free. During these 10 seconds, the main thread handles moving the slider, animations and other clicks.
• After 10 seconds, the coroutine wakes up, assigns the result to result and updates statusText.

Structured concurrency

Previously, we learned how to start background tasks (put water on the stove) without blocking the kitchen. But what happens when preparing a dish requires performing several actions at the same time, and we must be sure that all of them are complete before serving the meal?

This is where the join() function helps. It is one of the foundations of synchronization in the coroutine world.

Imagine that you are the head chef (parent coroutine). You need to prepare the main dish: steak with vegetables. You will not do everything yourself.

• You call Assistant 1: Fry the meat! (this will take 2 seconds).
• You call Assistant 2: Cook the vegetables! (this will take 3 seconds).

Both assistants start working at the same time (concurrency). The main coroutine is free and can handle other matters. But it cannot serve the dish until everything is ready. We perform this waiting with join().

Let us look at code that simulates this situation:

// 1. The head chef (parent) starts work
scope.launch {
    logs.add("Head chef (parent): Let's start!")

    // 2. Assign a task to Assistant 1 (Child 1)
    val jobMieso = launch {
        delay(2000) // Simulate frying
        logs.add("Cook 1: Meat fried (2s).")
    }

    // 3. Assign a task to Assistant 2 (Child 2)
    val jobWarzywa = launch {
        delay(3000) // Simulate cooking
        logs.add("Cook 2: Vegetables ready (3s).")
    }

    logs.add("Head chef: Tasks assigned, scope is waiting for completion...")

    // 4. Synchronization: the head chef waits for the results
    jobWarzywa.join()
    jobMieso.join()

    // 5. Final step
    logs.add("Head chef: Everyone finished! The dish can be served.")
}

In this example, we can see coordination of child tasks. The whole process starts when the parent coroutine, our metaphorical head chef, launches subtasks using the launch function. This is a kind of order ticket that gives us a unique handle to a specific coroutine that is currently running. In our case, we create two such handles: jobMieso and jobWarzywa, which become children of the main coroutine launched in the scope.

Both tasks start almost at the same time, which means that we do not wait to start cooking the vegetables until the meat is ready. As a result, the total operation time is not the sum of individual task times (5 seconds), but the duration of the longest task (3 seconds). However, this independence of subtasks creates a synchronization problem: what if the head chef finishes their work earlier than the assistants? Without proper control, the log message The dish can be served would appear immediately after assigning the tasks. In our metaphor, that would mean serving the customer an empty plate before the ingredients have been cooked.

The solution to this race condition is the join() function. Technically, it is a suspend function used to synchronize coroutine lifecycles. When the parent coroutine encounters jobWarzywa.join(), its execution is suspended. It is important to clearly distinguish suspension from blocking: the thread executing this coroutine is not blocked and can perform other system operations during that time. The join mechanism puts the calling coroutine into a waiting state that lasts until the observed Job reaches a terminal state (Completed or Cancelled). Only when the child task actually finishes does the state machine resume the parent coroutine from the next line of code. By explicitly calling join() on both Job objects, we implement the contract of structured concurrency: the parent consciously coordinates the work of its children and guarantees that no operation finishes too early, which preserves data consistency and makes the application flow predictable.

It is worth pausing on the aspect that makes structured concurrency safe: automatic cancellation propagation. We mentioned it earlier, but let us discuss it again.

Imagine that our head chef (parent) receives information that the customer cancelled the order and is leaving the restaurant. In the world of structured concurrency, the chef does not have to run around the kitchen and personally ask every assistant to stop working. Calling job.cancel() on the parent coroutine automatically sends the cancellation signal to all children (jobMieso, jobWarzywa). If the assistants are executing suspend functions, such as delay, they will stop immediately.

In Android application programming, this mechanism is extremely important. When the user closes a screen (Activity), the scope associated with it (viewModelScope or lifecycleScope) is cancelled. Thanks to the parent-child hierarchy, all ongoing network requests or background calculations are cleaned up automatically. This prevents memory leaks and avoids wasting battery on processes whose result nobody will ever see.

Receiving results: the async and await mechanism

Although the launch function is extremely useful, it has one important limitation: it works in a fire-and-forget mode. It returns a Job object, which allows us to check whether work is still running or to cancel it, but it does not allow us to extract any value from inside. In the real world, we do not always want only to assign a task; often we need the worker to bring us something, for example a specific ingredient from storage. For such tasks, we use the async function.

Analogy: courier and empty box

Before analyzing code, let us use an analogy of ordering a package:

• async: This is the moment when you click Buy now. The store does not give you the product immediately, but it gives you a tracking number; this is our Deferred object.
• Deferred: This is a metaphorical empty box. The box physically exists (we have a reference to it in code), but we cannot use its contents yet because they are still on the way.
• await(): This is the moment when we wait for the courier's bell. If the courier has already arrived, we receive the contents immediately. If the courier is still on the way, we suspend our other actions and wait until the box is unpacked.

Practical example: mysterious password generator

Consider the implementation of a screen that simulates a complex process of generating a secure password. This process takes 3 seconds and must return the result directly to the UI state variable.

@Composable fun PasswordGeneratorScreen() {
    var password by remember { mutableStateOf("...") }
    val scope = rememberCoroutineScope()

    // Function simulating heavy background computation
    suspend fun generatePassword(): String {
        delay(3000) // Simulate work
        return "Kotlin-Is-Super-Secure-123"
    }

    Column(
        modifier = Modifier.fillMaxSize().padding(16.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        Text("Mysterious password generator", style = MaterialTheme.typography.headlineSmall)
        Spacer(Modifier.height(20.dp))

        Button(onClick = {
            password = "Generating..."
            
            // Launch the parent coroutine (operation skeleton)
            scope.launch {
                // 1. Assign the task (async) - we immediately get the Deferred 'box'
                val deferredPassword: Deferred<String> = async { generatePassword() }
                
                // 2. Wait (await) - the coroutine suspends here for 3 seconds
                val result = deferredPassword.await()
                
                // 3. After 3 seconds, the coroutine resumes with the ready result
                password = result
            }
        }) {
            Text("Generate password")
        }

        Spacer(Modifier.height(20.dp))
        Text(password, fontSize = 20.sp, fontFamily = FontFamily.Monospace)
    }
}

In the code above, the key moment is the button click. We call scope.launch to enter the world of concurrency. Inside it, two things happen. First, the line async { generatePassword() } does not block code execution. The async function immediately returns an object of type Deferred<String>. If we checked the value of deferredPassword at that moment, we would only learn that the task is in progress. Second, calling deferredPassword.await() is an instruction for the coroutine mechanism: Stop this specific coroutine here and wait until deferredPassword delivers the value. What is extremely important is that the UI thread remains free. The user sees the text Generating..., but the application is not frozen; during this time, the system can handle other events.

When generatePassword() finishes and returns a String, await() unpacks it and assigns it to the result variable. Only then does the last line execute: password = result, which triggers recomposition of the interface and displays the password.

Bridge between worlds: runBlocking

All functions we have learned so far, namely launch and async, require an existing scope (CoroutineScope) to work. However, there are situations in which we must wait until the coroutine world finishes its work before allowing the outside, blocking world to move on. This is what runBlocking is for. As the name suggests, it is a function that blocks the current thread on which it was called until all coroutines inside its block are completed.

Imagine asynchronous code flow as a river: coroutines flow freely without disturbing one another. runBlocking is like a dam that we build across the river.

• The water (thread) stops flowing past the dam.
• The whole stream is stopped until the work inside the dam is complete.
• Only when the last coroutine inside the runBlocking block finishes does the dam open, and the thread can continue executing the next lines of code below the block.

Use cases

Because runBlocking blocks the thread, calling it on the UI thread will immediately freeze the user interface for the entire duration of the operation inside the block. This brings us back to the exact problem coroutines were meant to solve.

So when is it useful?

1. Unit tests: In tests, we want the test process to wait for the result of an asynchronous operation before checking the result correctness (assertion).
2. main() function: In simple Kotlin console programs, when we need to stop the program from closing until coroutines finish their work.
3. Integration with blocking code: When we must call asynchronous code inside a library that does not support coroutines and requires an immediate return value.

Comparison of mechanisms

The following example shows how runBlocking affects program flow compared with launch.

fun runBlockingExample() {
    println("1. Program start")

    // This block will stop the thread for 2 seconds!
    runBlocking {
        println("2. Inside runBlocking - start")
        delay(2000)
        println("3. Inside runBlocking - end")
    }

    println("4. Program end - this line waited for the dam")
}

In the code above, the text 4. Program end will appear only after 2 seconds. If we used launch instead of runBlocking in an appropriate scope, the text 4 would appear immediately after 2, because the river would continue flowing while the coroutine worked next to it.

The problem of monolithic code

At the beginning of working with Jetpack Compose, a natural instinct is to write all code inside a @Composable function. If UI is just a function, why not also put network data fetching or business logic inside it?

Let us look at code that works, but breaks software engineering principles. We call this anti-pattern "God Composable": a function that knows and does everything.

// STEP 1: naive code
@Composable
fun UserProfileScreen() {
    // UI state + logic in one place
    var userData by remember { mutableStateOf("Loading...") }
    val scope = rememberCoroutineScope() // Scope tied to the UI lifecycle

    Column {
        Button(onClick = {
            // Network operation directly in the UI
            scope.launch {
                try {
                    val user = api.getUser() // Simulate fetching (2 seconds)
                    userData = user.name.uppercase() // Business logic
                } catch (e: Exception) {
                    userData = "Error!"
                }
            }
        }) {
            Text("Fetch data")
        }
        Text(userData)
    }
}

We run the application, click the button and the data is fetched. Everything looks great until we rotate the phone. When the configuration changes, for example when the screen rotates, Android destroys and recreates the activity. The remember function loses its memory. A user who was waiting for data suddenly sees the initial Loading... screen again.

We already know the solution to this problem from the previous semester. Let us try to fix the code:

// rememberSaveable
var userData by rememberSaveable { mutableStateOf("Loading...") }

Does this solve the problem? Only superficially and only in trivial cases. When we try to apply this in a larger application, we encounter three critical problems that rememberSaveable will not solve:

• Coroutine death: rememberCoroutineScope is tightly tied to the view. If you rotate the screen while data is being fetched, for example on slow WiFi, the old view dies and the coroutine is cancelled with it. The download is interrupted halfway through. A new screen is created, but it knows nothing about the previous screen fetching anything. The user clicks, waits and gets nothing.
• Memory limitations (Bundle): rememberSaveable stores data in the system Bundle. It is intended for small data, such as text and numbers. If we try to store a list of 500 JSON objects fetched from an API, the application will throw a TransactionTooLargeException and close.
• Testability: How do we test whether a surname is correctly converted to uppercase? In the current code, it is impossible without running an emulator, because the logic is cemented inside the button.

We conclude that a Composable function is not the right place to store data or perform operations. We need a place that:

1. Survives screen rotation, unlike rememberSaveable.
2. Allows coroutines to finish work even when the view is destroyed.
3. Has no data size limit, unlike Bundle.

To understand why architecture is needed, let us use a construction analogy:

• Building a doghouse (no architecture): You can do it yourself. If you hammer a nail in the wrong place, it is easy to fix. These are small, simple applications.
• Building a skyscraper (with architecture): Here you need a plan. The electrician (data layer) does not paint walls, and the painter (UI layer) does not install gas pipes. In a large project, if a Composable handles API logic, it is like a painter trying to repair an elevator.

Therefore, we need a construction manager who keeps the plans in an office, safe from renovation work, and coordinates the tasks. The component we will introduce shortly will play that role.

Evolution of architectural patterns

Now that we know putting everything into one bag ("God Composable") is not a good solution, we need to think about how to divide an application. In software engineering, this problem is not new. Over decades, many different approaches to this issue have emerged. One of them is the MVx family of patterns, which differ in how the data layer communicates with the visual layer.

To understand the differences between them, we will use simple analogies.

MVC (Model-View-Controller)

This is the oldest approach, which can be compared to visiting a traditional shop where the seller hands you the product.

• You (View): You stand in front of the counter. You see the product, but you are passive; you cannot take it yourself.
• Seller (Controller): The seller controls the process. You say: I would like bread (interaction).
• Storage room (Model): The seller goes to the back room, checks stock and takes the product.

Conclusion: In this setup, the seller (Controller) decides everything. The seller must know what the storage room looks like and decides what to show the customer. The seller must also be able to point to the specific customer who should receive the product.

MVP (Model-View-Presenter)

This is the second variant from the MVx pattern family.

• Customer at the table (View): You sit and wait. You do not know and do not care what happens in the kitchen.
• Waiter (Presenter): The waiter takes the order and goes to the kitchen (Model).
• Key feature: The waiter comes back from the kitchen and personally places the plate on your table.

In code, this means that the Presenter (waiter) holds a reference to the View (customer). It calls a specific method on it, for example view.showDinner(). Problem: This is a rigid 1:1 connection. The waiter must know the exact table. If the customer goes to the restroom (screen rotation/view destruction), and the waiter returns with the plate and tries to place it on an empty seat, an error occurs (NullPointerException); the customer must be available.

MVVM (Model-View-ViewModel)

This approach is commonly used in modern Android development.

• User (View): The user approaches the machine and presses a button (sends an event).
• Coffee machine (ViewModel): It receives the signal, grinds coffee, fetches water and communicates with the Repository/Model.
• Result (State): The machine places a cup of coffee in the pickup tray (state emission).

Key difference - reactivity: the machine does not care who takes the cup.

• The machine only exposes state.
• If nobody is standing in front of the machine, the cup (data) simply waits in the tray.
• If the user leaves (rotates the screen) and a new one comes in (the Activity is recreated), the cup of coffee is still there. The new view simply looks into the tray and sees the ready drink.

In Compose, this tray is represented by data streams such as StateFlow. The ViewModel updates StateFlow, while the View (Composable) only observes changes. This solves our screen rotation problem: the ViewModel keeps the drink, regardless of what happens to the customer.

MVI (Model-View-Intent)

This is an evolution of MVVM that puts strict emphasis on unidirectional data flow.

• View (kiosk screen): Displays the current order state. It is read-only.
• Intent (intention/action): When you click Add fries, you do not directly change the order. You send the system an intent saying: "The user wants to add fries".
• Model (system): The system takes your current receipt, takes your intent, processes them and outputs a completely new, updated receipt (State).

Key feature - cyclicity and immutability: Unlike MVVM, where a ViewModel can have many different data streams (separate name, separate list, separate errors), in MVI we aim to have one state object, for example OrderUiState. In our metaphor: you cannot take a pen and add fries to a printed receipt. You must send a request, and the system prints a new, updated receipt for you. This makes the application predictable; we always know what led to the current screen state.

We naturally move toward MVI by using a single StateFlow<UiState> in the ViewModel.

MVVM implementation: technical analysis

In this section, we will analyze an implementation of the MVVM pattern using a simple example. We will focus on layer separation and the mechanism of preserving state during configuration changes.

The ViewModel class acts as a state manager. Note the backing property pattern, which provides full data encapsulation.

class WordViewModel : ViewModel() {
    // 1. Internal state (mutable) - private
    // We use mutableStateListOf, which is an implementation of SnapshotStateList.
    // This lets Compose track changes and trigger recomposition.
    private val _words = mutableStateListOf("Hello", "World", "Jetpack")
    
    // 2. Public state (immutable) - read-only
    // The view sees only List<String>. It cannot modify it directly.
    // This enforces unidirectional data flow.
    val words: List<String> get() = _words

    // 3. Public interface (actions/events)
    // The only way to change state is to call a method in the ViewModel.
    fun addWord(newWord: String) {
        _words.add(newWord)
    }

    fun clearList() {
        _words.clear()
    }
}

Using mutableStateListOf instead of a standard List is critical for reactivity. In Jetpack Compose, the system does not observe standard Java/Kotlin collections. Compose types, such as State<T>, implement the Observer pattern and automatically notify subscribers (Composable functions) about changes.

The View (Composable) becomes a so-called passive view. It does not own logical state; it only renders what the ViewModel provides.

@Composable
fun WordScreen(
    // Dependency injection
    // The viewModel() function uses ViewModelProvider to obtain an instance.
    viewModel: WordViewModel = viewModel()
) {
    Column {
        // State observation
        LazyColumn {
            items(viewModel.words) { word ->
                Text(text = word, style = MaterialTheme.typography.headlineSmall)
            }
        }

        // Event delegation
        Button(onClick = { 
            viewModel.addWord("New word") 
        }) {
            Text("Add item")
        }
    }
}

To use the viewmodel() function, we need to add the appropriate dependency to the dependencies block in the project configuration file.

implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.9.2")

The key advantage of ViewModel is that it survives screen rotation. This does not happen magically, but follows from the architectural lifecycle of Android components.

We can think of a ViewModel as a scoped singleton.

1. ViewModelStore: Each Activity has a ViewModelStore object. It is a map (HashMap) that stores ViewModel instances.
2. Configuration change, for example rotation:

When the user rotates the screen, the operating system destroys the Activity object and creates a new one. However, the ViewModelStore object associated with this activity is not destroyed. It is cached by the system in memory, in the NonConfigurationInstances object.

3. Reconstruction (re-attach):

A new Activity instance starts. The viewModel() function asks ViewModelProvider for a WordViewModel instance.

• The provider checks the preserved ViewModelStore.
• It finds the existing WordViewModel instance there, the same one that existed before rotation.
• It returns that instance to the new Activity.

Thanks to this mechanism, the data inside the ViewModel (our list of words) remains intact in RAM even though the UI layer has been completely rebuilt. The ViewModel dies only when the Activity is permanently finished, for example by pressing Back or calling finish(). This triggers onCleared() and clears the ViewModelStore.

Data layer: repository pattern

So far, our ViewModel has kept data in memory. In a larger application, data comes from external sources: an API (Retrofit), an SQL database (Room), files. This raises the question: Should the ViewModel know where the data comes from? According to the Separation of Concerns principle, absolutely not.

Let us return to the restaurant metaphor:

• ViewModel (waiter): It simply wants to receive a ready dish. It does not care whether the ingredients come from the market or from the fridge.
• Repository (kitchen/storage): This is where decisions are made about where to get the data from.

To decouple the ViewModel from a concrete data source, we use an interface.

// Contract: says WHAT can be ordered, but not HOW to obtain it
interface WordRepository {
    suspend fun getWords(): List<String>
}

In a simple example, a Repository may seem like an unnecessary layer, a mere "pass-through". However, in larger applications that we will build in later lectures, the Repository performs key functions:

• 1. Offline mode support (caching):

This is the most important use case, called Single Source of Truth. The Repository can check: Do we have internet?.

• Internet available: Fetch data from the API, save it in the local database (Room), and then return data from the database.
• No internet: Return data saved in the database from the previous session.

For the ViewModel, this process is invisible; it simply asks for data and receives it, regardless of network state.

• 2. Data aggregation:

Often, one screen needs data from multiple sources. For example, a profile screen may need user data from the /user endpoint and a list of recent orders from the /orders endpoint. The Repository fetches both resources in parallel (using async), combines them into one UserProfile object and only then passes this ready product to the ViewModel.

• 3. Mapping and data cleanliness:

APIs often return data in a technical (dirty) format, for example user_id_xq2, dates as timestamps, and so on. The Repository acts as a peeler; it transforms raw JSON objects (DTO - Data Transfer Object) into clean, readable domain objects that are easy to use in the UI.

The constructor-with-parameter problem: ViewModelFactory

We have reached the last technical challenge. We created WordRepository and want to pass it to our WordViewModel.

So we change the constructor:

class WordViewModel(private val repository: WordRepository) : ViewModel() { ... }

And here a problem appears. When we call the standard function in Composable code: val viewModel: WordViewModel = viewModel(), the application will throw a RuntimeException.

By default, the library function viewModel() can create only objects with an empty constructor (without parameters). It works using reflection.

To understand this, imagine a car dealership:

• ViewModel without parameters (car on the lot): You walk in and say I would like a Passat. The seller gives you keys to a standard model parked outside. Simple and fast.
• ViewModel with Repository (special order): You say I would like a Passat, but with a V6 engine (Repository). The seller shrugs; there is no such car on the lot. They must send an order to the factory, specifying exactly how the car should be assembled.

In programming, this specification is the Factory pattern.

We must provide an instruction manual that tells the system: If someone asks you for WordViewModel, first create the Repository and then put it inside.

Today, we most often implement this using a companion object inside the ViewModel class:

class WordViewModel(private val repository: WordRepository) : ViewModel() {
    
    // ... ViewModel code ...

    // Factory definition (creation instruction)
    companion object {
        val Factory: ViewModelProvider.Factory = object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(modelClass: Class<T>): T {
                return WordViewModel(
                    // Manual dependency injection (Manual DI)
                    repository = NetworkWordRepository()
                ) as T
            }
        }
    }
}

The create method is where we take control over object creation. We, not the system, decide which repository implementation goes inside.

Now that we have our factory, we need to use it in the view. We change the call in the WordScreen function:

@Composable
fun WordScreen(
    // Pass the factory as the 'factory' parameter
    viewModel: WordViewModel = viewModel(factory = WordViewModel.Factory)
) {
    // ... the rest of the code is unchanged ...
}

Thanks to this small addition, Android knows how to construct our complex object while still preserving all lifecycle benefits of ViewModel, such as surviving screen rotation.

"Do we have to write this kind of boilerplate for every screen?" At this stage, yes. This is called Manual Dependency Injection. We need to understand how objects are connected to each other under the hood.

In Lecture 11, we will introduce the Hilt library. It will do exactly what we are now doing manually, but automatically, using a single @HiltViewModel annotation. Hilt will generate this factory code for us at compile time.

Full example code: WordApp

Below is the complete implementation of the example discussed in this chapter. The code combines all introduced elements: the Repository pattern (interface and implementation), ViewModel with state and coroutine support, Factory (ViewModelProvider.Factory), and the view layer in Jetpack Compose.

You can copy this code into a single file, for example WordApp.kt, in your project to test how MVVM architecture works.

// ---------------------------------------------------------
// 1. DATA LAYER (MODEL & REPOSITORY)
// ---------------------------------------------------------

// Contract (interface) - this is all the ViewModel knows about
interface WordRepository {
    suspend fun getWords(): List<String>
}

// Concrete implementation (network simulation)
class NetworkWordRepository : WordRepository {
    override suspend fun getWords(): List<String> {
        // Simulate network delay (2 seconds)
        delay(2000)
        return listOf("Architecture", "MVVM", "in", "Practice", "Is", "Great")
    }
}

// ---------------------------------------------------------
// 2. LOGIC LAYER (VIEWMODEL)
// ---------------------------------------------------------

class WordViewModel(private val repository: WordRepository) : ViewModel() {

    // Private state (mutable)
    private val _words = mutableStateListOf<String>("Click the button...")
    
    // Public state (read-only)
    val words: List<String> get() = _words

    // Function called by the View (event)
    fun loadData() {
        viewModelScope.launch {
            _words.clear()
            _words.add("Loading...")
            
            // Fetch data from the repository (coroutine suspension)
            val newWords = repository.getWords()
            
            _words.clear()
            _words.addAll(newWords)
        }
    }

    // Factory (ViewModel Factory) - instruction for creating a ViewModel with a parameter
    companion object {
        val Factory: ViewModelProvider.Factory = object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(modelClass: Class<T>): T {
                return WordViewModel(
                    repository = NetworkWordRepository() // Dependency injection
                ) as T
            }
        }
    }
}

// ---------------------------------------------------------
// 3. PRESENTATION LAYER (VIEW / COMPOSE)
// ---------------------------------------------------------

@Composable
fun WordScreen(
    // Inject the ViewModel using the Factory
    viewModel: WordViewModel = viewModel(factory = WordViewModel.Factory)
) {
    Column(modifier = Modifier.padding(16.dp)) {
        
        // Button triggering the action
        Button(onClick = { viewModel.loadData() }) {
            Text(text = "Fetch words from server")
        }

        // List displaying the state
        LazyColumn(modifier = Modifier.padding(top = 16.dp)) {
            items(viewModel.words) { word ->
                Text(text = "* $word")
            }
        }
    }
}

Streams

In the previous chapters, especially while discussing coroutines and MVVM, we learned how to fetch data using suspending functions (suspend). A typical function in our repository looked like this:

// Old approach: return and forget
suspend fun getUserNames(): List<String> {
    // 1. Send a request
    // 2. Wait for a response
    return listOf("Anna", "John", "Peter") // 3. Return the result and finish
}

This approach has one fundamental limitation: it is a one-shot operation. The function returns a result and finishes. If a new user ("Sophia") registers on the server later, our application does not know about it. The view displays outdated data until the user manually refreshes the screen.

Modern applications rarely operate on static data. Most features we use every day are processes spread over time:

• Chat: Messages arrive one after another.
• GPS: The location changes with each step the user takes.
• File download: We want to see progress (1%, 2%, ... 100%), not wait blindly until the end.
• Stock market/crypto: Prices change dozens of times per minute.

We need a mechanism that does not return one package of data, but opens a channel through which data can flow for as long as necessary.

The answer to this need is Flow. It is an asynchronous data stream that emits values sequentially.

The differences between a classic list and a stream are fundamental:

• List<T>: Data is available immediately, as a whole group at once. To get new data, you must call the function again.
• Flow<T>: Data is computed or fetched asynchronously and emitted one by one, or in groups, over time. The application listens for changes instead of asking for them repeatedly.

We might ask: "But we used mutableStateOf, and the UI also refreshed automatically. Why do we need Flow?". Although both mechanisms are reactive, they serve different purposes:

1. mutableStateOf (UI state): This is a container for the current value used by the view. It tells Compose: redraw when this changes. It is tightly coupled to the UI layer. We should not use it in the data layer (Repository), because that would couple business logic to a UI library.
2. Flow (data transport): This is a mechanism for sending data from lower layers (database, network) to the ViewModel. It is pure Kotlin, independent of Android. It provides operators such as map, filter and combine, which allow us to transform data in flight.

The architecture pattern therefore looks like this:

The repository provides a stream of changes (Flow), and the ViewModel converts it into stable state for the view (State).

Flow - cold stream

The basic Flow type in Kotlin is a so-called cold stream. This means that the code producing data, inside the flow { ... } block, is passive. It does not run until someone requests the data.

To understand this, imagine a movie on a streaming platform such as YouTube or Netflix.

• Flow definition (file on the server): The movie exists on YouTube servers. It has its script: video frames follow one another. However, the mere existence of the file does not make the movie play. The server does not waste resources sending data into empty space.
• collect operator (Play button): Data transmission starts only when the user clicks Play. In the world of Flow, the equivalent of that button is the collect() function.
• Viewer independence: This is the most important feature. If three users start the same movie:
• User A clicked "Play" one minute ago -> they see the 60th second of the movie.
• User B clicks "Play" now -> they see the 1st second of the movie, the beginning.

Each subscriber receives their own independent copy of the stream. The stream starts from zero for that subscriber.

Let us look at an example:

// 1. DEFINITION (recipe / movie on the server)
// This code does NOT run when the value is assigned to a variable!
val numberStream: Flow<Int> = flow {
    println("Stream started!") 
    for (i in 1..3) {
        delay(1000) // Simulate work/download
        emit(i)     // Emit data (movie frame)
    }
}

// 2. USAGE (Subscriber 1)
scope.launch {
    println("Viewer 1 presses PLAY")
    numberStream.collect { value -> 
        println("Viewer 1 received: $value") 
    }
}

// 3. USAGE (Subscriber 2 - after a moment)
scope.launch {
    delay(1500)
    println("Viewer 2 presses PLAY")
    numberStream.collect { value -> 
        println("Viewer 2 received: $value") 
    }
}

Log output:

Viewer 1 presses PLAY
Stream started!
Viewer 1 received: 1
Viewer 2 presses PLAY
Stream started!  <-- Notice that it starts a second time!
Viewer 1 received: 2
Viewer 2 received: 1     <-- Viewer 2 receives the first value,
                              even though Viewer 1 is already further ahead

Let us inspect the output of our program. The logs reveal three mechanisms of Flow:

1. Multiple starts (re-evaluation):

Notice that the message "Stream started!" appears in the logs twice.
Conclusion: The code block passed to the flow { ... } builder is not a one-time initialization, like an object constructor. It is an instruction that runs from scratch for every subscriber.
If we placed an HTTP request inside that block, then with 10 subscribers we would execute 10 identical requests to the server.

2. Time independence:

When Viewer 1 is already watching and receives the number 2, Viewer 2 is only starting and receives 1.
Conclusion: Subscribers do not share progress. Each call to collect() creates a completely independent instance of the data flow. It is as if each viewer opened the same video file in a separate player window.

3. No memory (state):

When Viewer 2 joins the stream, they have no access to data emitted earlier. A cold stream does not store history; it produces it live.

This behavior, restarting on each subscription, is very dangerous in the UI layer (View). Imagine that the user rotates the phone. Android destroys and recreates the activity.

• The old activity stops listening (cancel).
• The new activity starts listening (collect).

With a regular Flow, this causes the entire data-fetching process to restart, for example another API request. To avoid this and keep data across screen rotations, we need a hot stream: StateFlow.

1. Laziness: If you create a Flow object but never call collect, the code inside flow { ... } never runs. No network or database request is sent.

Full example code

Below is complete code demonstrating the concept of a cold stream. The application lets us simulate new "viewers" (subscribers) joining the same data source.

The code visualizes logs on the screen, so we can see when the stream starts separately for each subscriber.

// 1. Cold Stream definition ("movie on the server")
// Notice: this function only returns a recipe for the stream. It does not start it.
fun numberStream(log: (String) -> Unit): Flow<Int> = flow {
    val time = SimpleDateFormat("HH:mm:ss", Locale.getDefault()).format(Date())
    log("[$time] Stream (re)starts!")
    
    for (i in 1..5) {
        delay(1000) // Simulate fetching a movie frame
        emit(i)     // Emit data
    }
}

@Composable
fun ColdStreamScreen() {
    // List of logs displayed on the screen
    val logs = remember { mutableStateListOf<String>() }
    // Helper for adding entries
    fun addLog(msg: String) = logs.add(msg)

    val scope = rememberCoroutineScope()

    Column(modifier = Modifier.padding(16.dp)) {
        Text("Cold Flow demonstration")
        
        Spacer(Modifier.height(16.dp))

        // Button simulating Viewer 1
        Button(onClick = {
            scope.launch {
                addLog("Viewer 1 clicks START")
                // collect() starts the stream FROM ZERO
                numberStream { msg -> addLog(msg) }.collect { value ->
                    addLog("  Viewer 1 watches: $value")
                }
            }
        }) {
            Text("Join as Viewer 1")
        }

        // Button simulating Viewer 2
        Button(onClick = {
            scope.launch {
                addLog("Viewer 2 clicks START")
                // collect() starts a SEPARATE stream instance
                numberStream { msg -> addLog(msg) }.collect { value ->
                    addLog("  Viewer 2 watches: $value")
                }
            }
        }) {
            Text("Join as Viewer 2")
        }

        Spacer(Modifier.height(16.dp))

        // Display logs
        LazyColumn {
            items(logs) { log ->
                Text(text = log)
            }
        }
    }
}

StateFlow - hot stream

We already know that regular Flow is a cold stream. This means that each subscription starts it from scratch. In the data layer, for example when downloading a file, this is often desired, but in the UI layer it becomes a serious problem. In the previous section we used Flow in the UI layer and considered the case of rotating the device. Because Flow is cold, the whole process starts again from the beginning. We need a stream that remembers the latest value and works independently of whether anyone is currently looking at the screen. This stream is StateFlow. It differs from a cold stream in two key ways:

• It exists independently of subscribers: It can produce data even when nobody receives it.
• It stores state (Replay = 1): It always remembers one latest emitted value. A new subscriber receives it immediately after connecting.

A good analogy for StateFlow is a live stream (Twitch):

• Streamer (ViewModel): Broadcasts a live stream. They play a game, while the score and health counters change in real time. The broadcast continues (data flows) regardless of whether there are 1000 viewers on the channel or 0.
• Viewer (View/UI):
• When a new viewer enters the channel, they do not watch the broadcast from the beginning, as with a YouTube video.
• They see what is happening right now, the current game state.
• If the viewer minimizes Twitch (the application goes to the background) and returns after a minute, they see the current action. What happened during that minute is gone, because we care about the live state.
• Shared image: All viewers watching the same channel see exactly the same state, for example the same stream image, at the same moment.

Let us move to an example:

class StreamerViewModel : ViewModel() {

    // 1. Private, mutable version (MutableStateFlow)
    // REQUIRES an initial value! The scoreboard must show something at startup, e.g. 0.
    private val _viewerCount = MutableStateFlow(0)

    // 2. Public, read-only version (StateFlow)
    val viewerCount: StateFlow<Int> = _viewerCount.asStateFlow()

    fun addViewer() {
        // State update is immediate
        _viewerCount.value += 1
    }
}

It is worth noting that MutableStateFlow requires an initial value in the constructor. This is logical: since StateFlow guarantees that it always has a value, like a scoreboard, it must have one from the moment it is created.

Full example code

The code below demonstrates how StateFlow works. We have a "Streamer" (ViewModel) that manages the viewer counter. Pay attention to the application behavior:

1. Click Add viewer in the Streamer panel.
2. Then click Join the stream as Viewer 1. You will see the current value, for example 5, not 0.
3. Join as Viewer 2. They receive the same value as Viewer 1.

// --- 1. ViewModel (Streamer) ---
class StreamerViewModel : ViewModel() {
    // Internal state (hot stream, always has a value)
    private val _viewerCount = MutableStateFlow(0)
    
    // Public state (read-only)
    val viewerCount: StateFlow<Int> = _viewerCount.asStateFlow()

    fun addViewer() {
        _viewerCount.value += 1
    }
}

// --- 2. View (UI) ---
@Composable
fun StateFlowDemoScreen(
    viewModel: StreamerViewModel = viewModel()
) {
    Column(
        modifier = Modifier.fillMaxSize().padding(16.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text("Streamer panel (StateFlow)")
        
        Spacer(Modifier.height(16.dp))
        
        // Streamer control panel
        Card() {
            Column(
              modifier = Modifier.padding(16.dp), 
              horizontalAlignment = Alignment.CenterHorizontally) {
                Text("You are the Streamer")
                Button(onClick = { viewModel.addViewer() }) {
                    Text("Add viewer (+1)")
                }
            }
        }

        Spacer(Modifier.height(32.dp))

        // Viewer simulation
        // Each ViewerScreen component independently subscribes
        // to THE SAME StateFlow
        ViewerScreen(viewModel, "Viewer 1")
        Spacer(Modifier.height(8.dp))
        ViewerScreen(viewModel, "Viewer 2")
    }
}

@Composable
fun ViewerScreen(viewModel: StreamerViewModel, viewerName: String) {
    // collectAsState() converts StateFlow into Compose State
    val count by viewModel.viewerCount.collectAsState()
    
    Card(modifier = Modifier.fillMaxWidth()) {
        Row(
            modifier = Modifier.padding(16.dp),
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            Text(viewerName, style = MaterialTheme.typography.bodyLarge)
            Text(
                text = "Sees counter: $count", 
                style = MaterialTheme.typography.titleLarge
            )
        }
    }
}

SharedFlow: handling events

We now have StateFlow, in which we store state, such as the number of viewers. However, mobile applications often deal with situations that are not state, but events.

Examples of one-shot events:

• Displaying a network connection error message (Toast/Snackbar).
• Navigating to another screen after successful login.
• Triggering phone vibration.

Why is StateFlow not suitable here? Imagine that we use StateFlow to handle errors.

1. An error occurs. We write it to StateFlow: state.value = "Error".
2. The view displays a Toast with the error.
3. The user rotates the phone.
4. The view is recreated and subscribes to StateFlow.
5. Because StateFlow remembers the latest value, the new view immediately receives Error and displays the Toast again.

Events should be consumed once and disappear. For example, we do not want a doorbell to ring forever every time we open the door. SharedFlow is used to handle such scenarios. It is also a hot stream, but by default it is configured to not remember history.

Let us return to our broadcast analogy. While the video image (StateFlow) must be continuous and available to everyone, notifications work differently.

• Donation alert (event): A message appears on the screen: Viewer1 donated 5 PLN.
• Present viewer (subscriber): Sees the message at the moment it appears.
• Absent viewer (application in the background): If the viewer is not in the room at the moment of the donation, then after returning they do not see the old alert.

It works like a doorbell: you hear it only when the courier presses it. If you come home an hour later, the doorbell does not suddenly start ringing to tell you that someone was there.

Let us look at an example. The differences compared with StateFlow are crucial:

class StreamerViewModel : ViewModel() {

    // 1. No initial value!
    // SharedFlow does not have to hold a value; it only pushes values through.
    // replay = 0 (default) -> new subscribers do NOT receive old events.
    private val _donations = MutableSharedFlow<String>(replay = 0)
    
    val donations = _donations.asSharedFlow()

    fun sendDonationAlert(message: String) {
        viewModelScope.launch {
            // 2. We use emit(), not .value
            // This is a suspending operation, because the buffer may be full
            _donations.emit(message)
        }
    }
}

1. replay = 0 parameter:

This is an important configuration for one-shot events. This parameter defines how many latest values should be stored in memory for new subscribers.

• In StateFlow, this value is fixed at 1, which is why state is restored after, for example, screen rotation.
• In SharedFlow, setting it to 0 guarantees that an event emitted at time $T_0$ will not be delivered to a subscriber that starts listening at time $T_1$. This prevents the bug of displaying messages again.
2. No .value field:

Notice that SharedFlow has no value property. We can only wait for upcoming emissions. This enforces a purely reactive approach.

3. emit() is a suspend function:

Unlike setting state.value = ..., the emit() method in SharedFlow is a suspending function. SharedFlow supports the backpressure mechanism. If subscribers cannot keep up with event processing and the internal buffer becomes full, the emit function suspends the producer coroutine until space becomes available in the buffer. This ensures thread safety and protects the application from being flooded with excessive data.

Full example code

The code below combines both worlds. We have StateFlow for the viewer counter (persistent) and SharedFlow for donation alerts (transient).

Pay attention to the use of LaunchedEffect in the view: this is a special Compose block used to handle one-shot coroutine events.

// --- ViewModel ---
class EventsViewModel : ViewModel() {
    // Events
    private val _donationEvents = MutableSharedFlow<String>()
    val donationEvents = _donationEvents.asSharedFlow()

    fun triggerDonation() {
        viewModelScope.launch {
            _donationEvents.emit("Someone donated 10 PLN!")
        }
    }
}

// --- View ---
@Composable
fun EventsDemoScreen(
    viewModel: EventsViewModel = viewModel(),
    snackbarHostState: SnackbarHostState // Component for showing Toasts/Snackbars
) {
    // Receiving events in Compose
    // LaunchedEffect(Unit) runs ONCE when entering the screen.
    // If you rotate the screen, it runs again,
    // but SharedFlow is empty (does not remember history),
    // so the old message will not appear.
    LaunchedEffect(Unit) {
        viewModel.donationEvents.collect { message ->
            // Reaction to the event: show Snackbar
            snackbarHostState.showSnackbar(message)
        }
    }

    Column(
        modifier = Modifier.fillMaxSize().padding(16.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text("Event handling (SharedFlow)")
        Spacer(Modifier.height(32.dp))
        
        Button(onClick = { viewModel.triggerDonation() }) {
            Text("Send donation (event)")
        }
        
        Spacer(Modifier.height(16.dp))
        Text("Click and watch the Snackbar. After screen rotation, the message will not return.", 
             textAlign = TextAlign.Center)
    }
}

Summary

Choosing the right stream type is important for the correct functioning of an application. A common mistake is using StateFlow for everything, including events, which leads to repeated messages, or using regular Flow in the UI, which causes unnecessary restarts of network requests. The table below summarizes the most important differences using our multimedia analogies.

When you write code and wonder which one to use, ask yourself these questions:

• Is this state that the view must always see, even after rotation? -> Use StateFlow.
• Is this a one-shot signal, for example "Logged in" or "Error"? -> Use SharedFlow.
• Are you fetching data from a database/network and processing it sequentially? -> Use regular Flow.

Safe data collection in UI

Finally, we need to discuss performance. In Android, an application may be in the background, for example when the user switches to another app, but still be alive in memory.

If we use regular collect or collectAsState() in a Composable function, the stream subscription may remain active even when the application is in the background. This means that if the ViewModel keeps emitting data, for example GPS location, the application will process that data and consume battery even though the user does not see it. The recommended standard is to use collectAsStateWithLifecycle(), an extension function provided by the androidx.lifecycle:lifecycle-runtime-compose library.

This function is lifecycle-aware:

1. When the application enters the STOPPED state (background) -> it cancels the stream subscription, stopping data collection.
2. When the application returns to the STARTED state (visible) -> it resumes the subscription and receives the latest state.

// Required dependency in build.gradle in the dependencies block:
// implementation("androidx.lifecycle:lifecycle-runtime-compose:...")

@Composable
fun UserProfileScreen(viewModel: UserViewModel) {
    // Less efficient:
    // val state = viewModel.uiState.collectAsState()

    // Standard:
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    Text(text = "Hello, ${state.userName}!")
}

Thanks to this simple step, our application is not only reactive, but also battery-friendly for the user.

Back to basics

In the previous chapters we learned how to create coroutines, use launch, async, and synchronize tasks with join. Before we move on to more advanced architectural patterns, we need to clarify one of the most common misunderstandings about concurrency in Kotlin.

Let us return to the examples discussed in Chapter 3. We will analyze exactly which thread executes each line of code.

Look at the password generator. We used async, which strongly suggests asynchronous execution. But where does the work actually happen?

@Composable fun PasswordGeneratorScreen() { 
    var password by remember { mutableStateOf("...") } 
    // The default Compose scope uses Dispatchers.Main.immediate
    val scope = rememberCoroutineScope()

    // Function simulating heavy computation
    suspend fun generatePassword(): String {
        // We are still on the MAIN THREAD here!
        // delay only suspends the coroutine; it does not change the thread.
        delay(3000) 
        return "Kotlin-Is-Super-Secure-123"
    }

    Column(...) {
        Button(onClick = {
            password = "Generating..."
            
            // 1. START: We are on the Main Thread (click handling)
            // launch without arguments inherits the context (here: Main)
            scope.launch { 
                // 2. INSIDE THE COROUTINE: still Main Thread.
                
                // 3. ASYNC: starts a new coroutine, but
                // inherits the dispatcher from the parent (Main Thread).
                val deferredPassword: Deferred<String> = async { 
                    generatePassword() // Function executed on Main Thread
                }
                
                // 4. AWAIT: suspends the parent coroutine (on Main Thread).
                // The UI is not blocked only because we used 'delay',
                // which is a non-blocking function.
                // If generatePassword() calculated hashes for 3 seconds (CPU),
                // the application would freeze (ANR).
                val result = deferredPassword.await()
                
                // 5. RESUME: still Main Thread. UI update.
                password = result
            }
        }) { Text("Generate password") }
    }
}

Conclusion: The whole operation, from the click, through async, to the result, happened on one and the same thread (Main). It worked smoothly only because delay is a suspending function. If we inserted real CPU work there, the UI would freeze.

The second example with cooks showed concurrency: doing two things at the same time. But does this mean parallelism, that is, using multiple CPU cores?

// 1. Head Chef (Parent)
// scope.launch uses Dispatchers.Main by default
scope.launch {
    // THREAD: Main Thread
    logs.add("Head chef (parent): We are starting")

    // 2. Assign task to Helper 1
    // launch inherits context -> Dispatchers.Main
    val jobMieso = launch {
        // THREAD: Main Thread
        // The coroutine suspends on the main thread, giving room to others
        delay(2000) 
        logs.add("Cook 1: Meat fried (2s).")
    }

    // 3. Assign task to Helper 2
    // launch inherits context -> Dispatchers.Main
    val jobWarzywa = launch {
        // THREAD: Main Thread
        delay(3000) 
        logs.add("Cook 2: Vegetables ready (3s).")
    }

    // THREAD: Main Thread
    logs.add("Head chef: Tasks assigned...")

    // 4. Synchronization
    // join() is a suspension point on Main Thread.
    // The parent coroutine "waits" (without blocking the thread) until children finish.
    jobWarzywa.join()
    jobMieso.join()

    // 5. Finale
    // THREAD: Main Thread
    logs.add("Head chef: Everyone is done!")
}

Conclusion: Even though we have three coroutines (Parent, Cook 1, Cook 2), all of them jump around the same main thread.

Of course, both launch and async accept an optional CoroutineContext argument, which lets us explicitly choose a dispatcher.

// We can force another thread at startup
scope.launch(Dispatchers.IO) {
    // Now we are on a background thread.
    // Good for writing to a file.
    saveToFile()
    
    // PROBLEM: We cannot safely touch the UI from here
    // textLabel.text = "Saved" // ERROR!
}

Although this is possible, in MVVM architecture we rarely use this approach directly in the UI layer. It causes problems with updating the interface, because we must manually return to the Main Thread, and it makes testing harder. Instead, we use an approach where the coroutine starts on the UI thread, so it can access the UI, and jumps to other threads only when necessary.

There are two main thread-switching patterns that we will discuss in this chapter:

1. Imperative approach (withContext): Used inside functions. We say: execute this block of code on another thread and return to me with the result.
2. Reactive approach (flowOn): Used in streams. We say: all data above this point should be produced on another thread.

Imperative approach: function safety with withContext

Let us return to the problem of blocking the UI. We already know that calling a computationally expensive function inside viewModelScope.launch will block the screen.

The solution to this problem in the imperative approach is the withContext function:

1. It accepts a Dispatcher as an argument, for example Dispatchers.Default or IO.
2. It suspends the current coroutine without blocking the thread from which it was called.
3. It executes the code block on the selected dispatcher.
4. After the work finishes, it resumes the coroutine on the original dispatcher.
5. It returns the result of the last line of the code block, so it works like an expression.

This makes the code look sequential, even though complex thread switching happens underneath.

// Definition of a Main-Safe function (safe for UI)
suspend fun performHeavyCalculation(): Int {
    // 1. Change context to a computation thread
    return withContext(Dispatchers.Default) {
        // 2. Simulate heavy work (e.g. image processing)
        // This will not block the UI, even though 'sleep' normally blocks a thread.
        // Here we block a worker thread, not the main thread.
        Thread.sleep(2000) 
        
        // 3. Calculate the result
        val result = 42 * 100 
        
        // 4. Return the result (last line)
        result 
    }
    // 5. Automatic return to the thread from which the function was called
}

// Usage in ViewModel
fun onCalculateClicked() {
    viewModelScope.launch { // Start on Main Thread
        _uiState.value = UiState.Loading // UI update
        
        // Call - here the coroutine "suspends" on Main Thread
        // The UI remains responsive (e.g. the loader keeps spinning)
        val result = performHeavyCalculation()
        
        // Return to Main Thread with the ready result
        _uiState.value = UiState.Success(result)
    }
}

Reactive approach: stream safety with flowOn

While withContext works very well for functions that enter and exit, the situation is more complex for streams (Flow). A stream is a pipeline through which data flows over time.

In Flow, the rule is: code inside the flow { ... } block runs in the same context in which collect() was called.

Because in Android we usually collect data (collect) in the view layer (Activity/Composable), which runs on the main thread, this means that by default the data producer would also run on the main thread.

// INCORRECT APPROACH
// Repository
val usersFlow = flow {
    // This runs on Main Thread if collect is called on Main!
    // This will freeze the UI on every database read.
    val data = database.readUsers() // Blocking IO operation
    emit(data)
}

// ViewModel / UI
viewModelScope.launch { 
    // We collect on Main Thread (default in viewModelScope)
    usersFlow.collect { show(it) } 
}

To change the thread on which data is produced, we use the flowOn operator. Its behavior is specific: it changes the execution context only for operators located above it, that is, upstream.

// CORRECT APPROACH
val usersFlow = flow {
    // 1. This runs on Dispatchers.IO
    val data = database.readUsers()
    emit(data)
}.map { users -> 
    // 2. This also runs on Dispatchers.IO (because it is above flowOn)
    users.filter { it.isActive }
}.flowOn(Dispatchers.IO) // <--- CONTEXT-SWITCH BOUNDARY
.map { users ->
    // 3. This runs in the collector context (usually Main)
    // Because it is BELOW flowOn
    users.map { it.name }
}

Thanks to flowOn, we can safely execute database or network operations in the repository and deliver a result ready for display on the UI thread.

Comparing withContext and flowOn

Let us summarize the differences between these two mechanisms:

Stream transformation

Before we learn the stateIn operator, we need to understand the architectural problem it solves. This requires recalling the fundamental difference between cold and hot streams and analyzing the Android application lifecycle.

In Chapter 5, we defined two types of streams. Let us now look at them from the perspective of performance:

• Cold stream (Flow): This is a recipe for data.
• It does not store data.
• The code inside the flow { ... } block does not run until someone starts listening (collect).
• Each new subscriber causes the producer code to run again from the beginning.
• Hot stream (StateFlow/SharedFlow): This is a ready meal on the table.
• It stores data (state) in memory.
• It produces data independently of whether anyone is listening.
• A new subscriber immediately receives the current state (a plate with food), without having to cook everything again.

In Android, a configuration change, such as screen rotation or switching between light and dark mode, causes the Activity to be completely destroyed and recreated. If the UI layer listens to a cold stream (regular Flow) coming directly from the repository, resources are wasted.

Let us follow this scenario step by step:

1. The user opens a screen. The Activity calls collect().
2. Cold Flow starts: The repository connects to the database, executes an SQL query and processes the results. The data reaches the screen.
3. The user rotates the screen.
4. The old Activity is destroyed -> collect() is cancelled.
5. The new Activity is created -> it calls a new collect().
6. Cold Flow starts FROM SCRATCH: The repository again connects to the database and again executes the same SQL query.

// --- REPOSITORY ---
// Cold stream - code inside runs on EVERY subscription
fun getTasks(): Flow<List<Task>> = flow {
    println("Fetching data from database...") // This logs on every rotation!
    val tasks = database.queryAll()
    emit(tasks)
}

// --- VIEWMODEL (INCORRECT APPROACH) ---
// ViewModel only forwards the cold stream
val tasksFlow = repository.getTasks() // This is still a cold Flow

MVVM architecture gives us an ideal place to solve this problem. The ViewModel survives device configuration changes.

Therefore, we need to:

1. Fetch the data once (start the cold stream).
2. Store the result in ViewModel memory (convert it into hot state).
3. After rotation, the new Activity should receive data from ViewModel memory instead of hitting the repository.

The stateIn operator, discussed in the next section, is used for this transformation.

stateIn and shareIn operators

Now that we know we need to turn a cold stream (recipe) into a hot one (meal), Kotlin provides two dedicated operators for this: stateIn and shareIn.

The stateIn operator converts any Flow<T> into StateFlow<T>. Recall that StateFlow is an observable data container that always has a value. Therefore, this operator requires an initial value.

// ViewModel
val uiState: StateFlow<UiState> = repository.getDataStream()
    .map { data -> UiState.Success(data) } // Data transformation
    .stateIn(
        scope = viewModelScope, // 1. Where should the stream live?
        started = SharingStarted.WhileSubscribed(5000), // 2. When should it run?
        initialValue = UiState.Loading // 3. What should be shown first?
    )

The started parameter is crucial for saving resources. The most commonly used Android strategy is SharingStarted.WhileSubscribed(5000).

• Behavior: Keep the connection to the source (upstream) as long as someone is listening in the UI.
• Timeout (5000 ms): If the number of subscribers drops to zero, for example because the user rotated the screen and the old Activity disappeared, do not close the connection immediately. Wait 5 seconds.

A configuration change is often almost instantaneous. The old Activity disappears (subscribers = 0), and a moment later the new Activity appears (subscribers = 1).

• Thanks to the 5s delay, the stream does not notice this short break. The database connection is not closed, and the new Activity immediately receives data from memory.
• If, however, the user presses Home and leaves the application for more than 5 seconds, the stream is stopped and resources are released, for example a network connection is closed.

The shareIn operator converts Flow<T> into SharedFlow<T>. We use it for data that has an event character, not a state character. Examples include notifications, toasts and navigation signals.

Differences compared with stateIn:

1. It does not require an initial value, because events do not have to exist at startup.
2. It allows the replay parameter to be configured, defining how many old events should be remembered for new subscribers.

Imagine a stream of alerts from a server. We want these alerts to reach all screens in the application, but we do not want a newly opened screen to display old, outdated messages.

val notificationEvents: SharedFlow<String> = repository.getAlerts()
    .shareIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000),
        replay = 0
    )

If we set replay = 1, every newly opened screen would immediately receive the latest message.

Summary:

Combining data: the combine operator

In applications, screen state (UI State) rarely comes from a single source. Often we need to combine data from two or more independent streams.

Typical scenarios:

• E-commerce: Product price (from database) + discount code (from text field).
• Profile: User data (from network) + privacy settings (from DataStore).
• Lists: Task list (from database) + selected category filter (from ViewModel).

The combine operator is used for this. It listens to several streams at the same time. Its behavior can be compared to a spreadsheet formula, for example =A1+B1.

1. It waits until all streams emit their first value (initial synchronization).
2. Whenever any stream emits a new value, the operator takes that new value and the latest known values from the remaining streams.
3. It runs a lambda block where we combine those values into one result object.

Assume that we have a repository providing the current cart total and a text field in the ViewModel where the user enters a discount code.

class CartViewModel(repository: CartRepository) : ViewModel() {

    // 1. Stream from repository (e.g. from database)
    // Changes rarely (only when we add a product)
    val cartTotalFlow: Flow<Double> = repository.getCartTotal()

    // 2. Stream from the text field
    // Changes often (on every key press)
    val promoCodeFlow = MutableStateFlow("")

    // 3. Combine into one UI state
    val uiState: StateFlow<CartUiState> = combine(
        cartTotalFlow,
        promoCodeFlow
    ) { total, code ->
        // This lambda runs when either the price OR the code changes
        
        val discount = if (code == "PROMO20") 0.20 else 0.0
        val finalPrice = total * (1.0 - discount)

        // Return the state object
        CartUiState(
            totalPrice = total,
            discountApplied = discount > 0,
            finalPriceToPay = finalPrice
        )
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000),
        initialValue = CartUiState() // Initial state (empty)
    )
    
    fun onCodeChanged(code: String) {
        promoCodeFlow.value = code
    }
}

Thanks to combine, our UI is fully reactive. If the user enters a valid code, the price is recalculated immediately. If, in the meantime, a price update arrives from the database in the background, the price is also recalculated automatically, taking the entered code into account.

Complete implementation examples

Below are complete source-code examples for the topics discussed, ready to be copied into a project.

Example 1: safe calculations with withContext

This example shows the imperative approach. We execute a heavy operation, simulating video rendering, after a button click without blocking the progress indicator on the screen.

// 1. UI state definition (sealed interface)
sealed interface UiState {
    data object Idle : UiState                    
    data object Loading : UiState                 
    data class Success(val result: Int) : UiState 
}

// 2. ViewModel (business logic)
class CalculationViewModel : ViewModel() {

    private val _uiState = MutableStateFlow<UiState>(UiState.Idle)
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()

    fun onCalculateClicked() {
        viewModelScope.launch {
            _uiState.value = UiState.Loading

            val result = performHeavyCalculation()

            _uiState.value = UiState.Success(result)
        }
    }

    private suspend fun performHeavyCalculation(): Int {
        return withContext(Dispatchers.Default) {
            Thread.sleep(2000) 
            42 * 100
        }
    }
}

// 3. View (Composable)
@Composable
fun CalculationScreen(viewModel: CalculationViewModel = viewmodel()) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    Box(
        modifier = Modifier.fillMaxSize(),
        contentAlignment = Alignment.Center
    ) {
        Column(
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            // React to a specific state
            when (val currentState = state) {
                is UiState.Idle -> {
                    Text(text = "Ready for calculations")
                }
                is UiState.Loading -> {
                    CircularProgressIndicator()
                    Text(text = "Processing...")
                }
                is UiState.Success -> {
                    Text(
                        text = "Result: ${currentState.result}"
                    )
                }
            }
            Button(
                onClick = { viewModel.onCalculateClicked() },
                enabled = state !is UiState.Loading
            ) {
                Text("Start heavy work")
            }
        }
    }
}

Example 2: stream optimization with flowOn

This example shows the reactive approach. We move stream-data processing (filtering and sorting) to a background thread, while the repository and view remain clean.

// 1. Data model
data class User(val name: String, val isActive: Boolean)

// 2. Repository (data-layer simulation)
class UserRepository {
    // The function returns a "cold" stream (Cold Flow)
    fun fetchUsersFromDb(): Flow<List<User>> = flow {
        // SIMULATION OF BLOCKING IO
        // Normally this would block the UI if not for flowOn
        Thread.sleep(2000) 
        
        val users = listOf(
            User("Anna Kowalska", true),
            User("John Novak", false),
            User("Mark Clock", true),
            User("Sophia Example", true)
        )
        emit(users)
    }
}

class UserViewModel : ViewModel() {
    private val repository = UserRepository()

    val uiState: StateFlow<UiState> = repository.fetchUsersFromDb()
        .map { users -> users.filter { it.isActive }}
        .flowOn(Dispatchers.IO) // <--- CONTEXT-SWITCH BOUNDARY (upstream on IO)
        .map { users ->
            // This map is AFTER flowOn, so it runs in the collector context (Main)
            UiState.Success(users.map { it.name.uppercase() }) as UiState
        }
        .onStart {
            // Emit loading state at the beginning of the subscription
            emit(UiState.Loading)
        }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = UiState.Loading
        )
}

// View state definition
sealed interface UiState {
    data object Loading : UiState
    data class Success(val userNames: List<String>) : UiState
}

// 4. View (Composable)
@Composable
fun UserListScreen(viewModel: UserViewModel = viewModel()) {
    val state by viewModel.uiState.collectAsState()

    Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
        when (val currentState = state) {
            is UiState.Loading -> {
                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                    CircularProgressIndicator()
                    Spacer(modifier = Modifier.height(8.dp))
                    Text("Fetching database...")
                    Text("(Check Logcat)")
                }
            }
            is UiState.Success -> {
                LazyColumn(
                    modifier = Modifier.fillMaxSize(),
                    contentPadding = PaddingValues(16.dp)
                ) {
                    item {
                        Text(
                            "Active users:",
                            modifier = Modifier.padding(bottom = 16.dp)
                        )
                    }
                    items(currentState.userNames) { name ->
                        Card(
                            modifier = Modifier
                                .fillMaxWidth()
                                .padding(vertical = 4.dp),
                            elevation = CardDefaults.cardElevation(defaultElevation = 2.dp)
                        ) {
                            Text(
                                text = name,
                                modifier = Modifier.padding(16.dp)                            )
                        }
                    }
                }
            }
        }
    }
}

Example 3: combining data streams with combine

// 1. UI state model
data class CartUiState(
    val baseTotal: Double = 0.0,
    val finalPrice: Double = 0.0,
    val discountApplied: Boolean = false,
    val currentCode: String = ""
)

// 2. Repository (external-data simulation)
class CartRepository {
    // Simulates a cart that changes over time
    fun getCartTotal(): Flow<Double> = flow {
        // Initial cart price
        emit(100.0) 
        
        // After 5 seconds, simulate that a product was added on another device
        delay(5000) 
        emit(200.0) // Price increases. Combine automatically recalculates the result.
    }
}

// 3. ViewModel (stream-combination logic)
class CartViewModel : ViewModel() {
    private val repository = CartRepository()

    // Stream 1: price from database (read-only Flow)
    private val cartTotalFlow = repository.getCartTotal()

    // Stream 2: code entered by the user (MutableStateFlow)
    private val promoCodeFlow = MutableStateFlow("")

    // combine operator
    val uiState: StateFlow<CartUiState> = combine(
        cartTotalFlow,
        promoCodeFlow
    ) { total, code ->
        // This lambda runs when EITHER the price OR the code changes
        
        // Business logic for the discount
        val isPromoValid = code.trim() == "PROMO20"
        val discount = if (isPromoValid) 0.20 else 0.0
        val finalPrice = total * (1.0 - discount)

        // Return the new combined state
        CartUiState(
            baseTotal = total,
            finalPrice = finalPrice,
            discountApplied = isPromoValid,
            currentCode = code
        )
    }.stateIn(
        scope = viewModelScope,
        started = SharingStarted.WhileSubscribed(5000),
        initialValue = CartUiState()
    )

    // Function called from UI when typing text
    fun onCodeChanged(newCode: String) {
        promoCodeFlow.value = newCode
    }
}

// 4. View (Composable)
@Composable
fun ShoppingCartScreen(viewModel: CartViewModel = viewModel()) {
    // UI reacts to every change in uiState (coming from any stream)
    val state by viewModel.uiState.collectAsStateWithLifecycle()

    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(24.dp),
        horizontalAlignment = Alignment.CenterHorizontally,
        verticalArrangement = Arrangement.Center
    ) {
        Text("Your cart")
        
        Spacer(modifier = Modifier.height(32.dp))

        // Summary card
        Card(
            elevation = CardDefaults.cardElevation(defaultElevation = 4.dp),
            modifier = Modifier.fillMaxWidth()
        ) {
            Column(modifier = Modifier.padding(16.dp)) {
                Row(
                    modifier = Modifier.fillMaxWidth(),
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    Text("Product price:")
                    Text(
                      "${state.baseTotal} PLN", 
                      fontWeight = FontWeight.Bold
                    )
                }

                // Row: discount
                if (state.discountApplied) {
                    Row(
                        modifier = Modifier.fillMaxWidth(),
                        horizontalArrangement = Arrangement.SpaceBetween
                    ) {
                        Text("Discount (PROMO20):")
                        Text(
                          "-20%", 
                          fontWeight = FontWeight.Bold
                        )
                    }
                }

                Divider(modifier = Modifier.padding(vertical = 8.dp))

                // Row: final total
                Row(
                    modifier = Modifier.fillMaxWidth(),
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    Text("To pay:")
                    Text(
                        "${state.finalPrice} PLN", 
                    )
                }
            }
        }

        Spacer(modifier = Modifier.height(24.dp))

        // Text field for entering the code
        OutlinedTextField(
            value = state.currentCode,
            onValueChange = { viewModel.onCodeChanged(it) },
            label = { Text("Discount code") },
            placeholder = { Text("Enter: PROMO20") },
            singleLine = true,
            modifier = Modifier.fillMaxWidth(),
            isError = state.currentCode.isNotEmpty() && !state.discountApplied,
            supportingText = {
                if (state.currentCode.isNotEmpty() && !state.discountApplied) {
                    Text("Invalid code")
                } else if (state.discountApplied) {
                    Text("Code accepted!", color = Color(0xFF2E7D32))
                }
            }
        )
    }
}

In the previous chapters we used streams (Flow) to transfer data. A stream worked like radio: a broadcasting station emitted a signal, and everyone who tuned in their receiver (collect) received the same data.

But what if we need precise one-to-one communication? Imagine a factory: one machine produces screws, and another machine packages them. Every screw produced by machine A must reach machine B. We do not want a screw to get lost, and we do not want it to end up in two packages at once. For such tasks, Kotlin provides a separate synchronization primitive: Channels.

A Channel is conceptually a conveyor belt connecting two coroutines.

• Sender (Producer): Puts data into one end of the pipe.
• Receiver (Consumer): Takes data out from the other end.

The key feature of channels is that they are used not only for transferring data, but also for synchronizing coroutine work. If the pipe is empty, the receiver waits. If the pipe is full (for buffered channels), the sender waits.

Channel vs Flow (SharedFlow)

The difference is fundamental and concerns the data-distribution model.