We are currently witnessing the most significant shift in mobile computing since the invention of the App Store. We have officially entered the Era of Agentic AI, where the "search bar" is being replaced by the "chat bubble."

For a decade, we’ve obsessively optimized for Deep Links and SEO to make our Android apps discoverable and openable from Google Search. But in a world where users ask an AI Agent to "book a flight" or "summarize my notes" instead of opening an app, those old tools are becoming obsolete. If an AI Agent can’t "see" inside your app, your app doesn't exist. So, how do you make your app's functionalities discoverable to the brains of the future? The answer is Android AppFunctions. It's the new bridge that lets your app's core logic step out of the UI and into the world of autonomous agents. 🚀

What is AppFunctions?

Android AppFunctions allows apps to share data and functionality with AI agents and assistants by enabling developers to create self-describing functions that agentic apps can discover and execute using natural language, providing an on-device solution for Android apps similar to backend capabilities declared via MCP cloud servers. Read more about it here on the official blog by Google.

Last year, when I first encountered the API, I shared my thoughts on it, recognizing the vast array of potential use cases.

According to the official blog, while not every interaction has a dedicated integration yet, Google is developing a UI automation framework for AI agents and assistants to intelligently execute generic tasks on users' installed apps, ensuring user transparency and control. Unless an app wants to provide a structured communication method with greater control, implementing AppFunctions is optional.

Currently, as I write this, it's only available on the Samsung S26 Ultra and Google Pixel 10. Users with these devices can access app functions from installed apps through the Gemini app.

💡How to integrate AppFunctions?

AppFunctions are part of the SDK from Android 16 and are also available through the Jetpack library, enabling seamless integration into apps without compatibility issues. It utilizes the interprocess communication framework like AIDL, ensuring security measures are in place so that not just any app can call the functions of another app. More details will be covered in the later section.

Source: Overview of AppFunctions (Android Developers)

The Jetpack library includes an annotation processor that simplifies creating type-safe schema models and functions. You just need to declare what the function does, what it requires, and what it returns. This annotation processor then generates a contract, allowing the agent app to understand how to call the app's function, including the necessary parameters and types. This process is similar to how an LLM agent knows how to call a function when MCP is configured.

As of now, the latest version of AppFunctions is v1.0.0-alpha08, so if you're reading this much later, expect many changes. I already have my note taking sample app on my GitHub, so thought of integrating it there. So apps need to add the following dependencies in the project.

dependencies {
  val appfunversion = "1.0.0-alpha08"

  implementation("androidx.appfunctions:appfunctions-service:$appfunversion")
  implementation("androidx.appfunctions:appfunctions:$appfunversion")
  ksp("androidx.appfunctions:appfunctions-compiler:$appfunversion")
}

// Configure KSP
ksp { 
  arg("appfunctions:aggregateAppFunctions", "true") 
  arg("appfunctions:generateMetadataFromSchema", "false") 
}

NotyKT is a simple note-taking app that supports the following operations: create, insert, update, and delete.

// A model to expose via AppFunctions
@AppFunctionSerializable(isDescribedByKDoc = true) 
data class Note( 
  /** The note's identifier */ 
  val id: String, 
  /* The note's title */ 
  val title: String, 
  /* The note's content */ 
  val content: String, 
)

// Function's entry point
class NotyAppFunctions @Inject constructor(
  @LocalRepository private val repository: NotyNoteRepository
) { 
   /**
     * Lists all available notes.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun listNotes(appFunctionContext: AppFunctionContext): List<Note> =
        repository.getAllNotes().map { Note(it.id, it.title, it.note) }

    /**
     * Adds a new note to the app.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     * @param title The title of the note.
     * @param content The note's content.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun createNote(
        appFunctionContext: AppFunctionContext,
        title: String,
        content: String,
    ): Note? = /* Implementation */

    /**
     * Edits a single note.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     * @param noteId The target note's ID.
     * @param title The note's title if it should be updated.
     * @param content The new content if it should be updated.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun editNote(
        appFunctionContext: AppFunctionContext,
        noteId: String,
        title: String?,
        content: String?,
    ): Note? = /* Implementation */

    /**
     * Deletes a single note.
     *
     * @param appFunctionContext The context in which the AppFunction is executed.
     * @param noteId The target note's ID.
     *
     * @return Whether the note was deleted or not.
     */
    @AppFunction(isDescribedByKDoc = true)
    suspend fun deleteNote(
        appFunctionContext: AppFunctionContext,
        noteId: String,
    ): Boolean = /* Implementation */
}

Notice how it's clearly defined. The annotation processor handles the heavy lifting. The @AppFunction(isDescribedByKDoc = true) annotation generates a structured schema, providing a description of the function, detailing each parameter, and outlining the return model from the KDoc.

Since this function requires a repository as a dependency, how can the app create an instance of it on demand? Ideally, if this function were declared without dependencies, its instance could be automatically created. However, with a dependency present, a factory must be provided. Most apps use DI frameworks, so here's how to handle it: In the app's Application implemented class, implement the new interface and override its method as shown, using Dagger Hilt in this example.

// 1. Implement the interface
@HiltAndroidApp
class NotyApp : Application(), AppFunctionConfiguration.Provider {

  @Inject lateinit var appFunctions: Provider<NotyAppFunctions>
   
  /*other impl*/
  
  override val appFunctionConfiguration: AppFunctionConfiguration
    get() = AppFunctionConfiguration
        .Builder()
        .addEnclosingClassFactory(NotyAppFunctions::class.java) { 
          appFunctions.get() 
        }
        .build()
}

That's it! This is how AppFunctions can be implemented in the app 😄.

🧪How to test?

Currently Gemini app can't directly invoke them but the ADB command utility can help here in testing the integration. Make sure you've platform-tools installed in the SDK and following ADB commands can help.

1. Listing functions

# Lists all the app functions exposed by all apps installed on the device.
adb shell cmd app_function list-app-functions

# Package specific
adb shell cmd app_function list-app-functions --package dev.shreyaspatil.noty.composeapp

Upon running this, it could give output like this

This allows you to see the complete details of all functions, including their IDs, descriptions, parameter types and descriptions, types, nullability, and the same information for the return type model.

2. Executing app functions

The command to execute the app functions is:

adb shell cmd app_function execute-app-function \
    --package <PACKAGE_NAME> \
    --function <FUNCTION_ID> \
    --parameters <PARAMS_IN_JSON>

Let's say I want to run the app function to perform simple READ operation: getting the list of notes in the app:

adb shell cmd app_function execute-app-function \
    --package dev.shreyaspatil.noty.composeapp \
    --function dev.shreyaspatil.noty.appfunctions.NotyAppFunctions#listNotes \
    --parameters {}

Currently when I tried, it was forcing me to pass the parameters, so I had to provide {}.

It provides JSON output as follows, aligning with the contract model defined in our app:

{
  "androidAppfunctionsReturnValue": [
    {
      "id": ["TMP-053ffdbe-7997-4ba6-9187-3a4ef6be0833"],
      "title": ["💡Ideas"],
      "content": ["- Android AppFunctions demo\n- Android Foldable device APIs\n- Generative AI"]
    },
    {
      "id": ["TMP-58832e3e-da0f-4542-aa55-68fbc9edea19"],
      "title": ["👨🏻‍💻 Today's tasks"],
      "content": ["Work on the open-source sample to demonstrate the use of Android AppFunctions"]
    }
  ]
}

Let's say we want to create a note, the command for it could look as follows:

adb shell "cmd app_function execute-app-function \
  --package dev.shreyaspatil.noty.composeapp \
  --function dev.shreyaspatil.noty.appfunctions.NotyAppFunctions#createNote \
  --parameters '{\"title\":\"hello from shell\",\"content\":\"created from the terminal\"}'"

When you execute this command, the note is created in the app and might appear as follows:

This is what testing looks like!

This is a PR with all changes for reference.

💰Bonus - Agent App

I attempted to mimic the agent app to get a sense of it (though it's not an actual agent, just hardcoded actions triggered by specific messages), and it appears as follows:

You can find this sample app here and play around it if interested.

However, this doesn't mean any random app can be installed as an agent app to invoke functions from any app that exposes them. If an app attempts this, a SecurityException will occur because this is a restricted API, accessible only to system apps. In the demo above, I installed the mock agent app as a system app in the emulator, which allowed me to experiment with it. The agent app must declare a permission in the manifest: <uses-permission android:name="android.permission.EXECUTE_APP_FUNCTIONS" />. Therefore, only official apps like those from Google/Gemini and OEMs are permitted to call these app functions. The agent apps can use AppFunctionManager to query all the apps and their exposed functions. It works as follows:

What are your thoughts on this new thing? I'm genuinely excited about its potential widespread use in apps. With the advancements in voice support and AI agents, this could become a standout feature in the future trends of Android development. Can imagine how it could be used:

• "Repeat the last ordered Indian dish for me on Zomato"

• "I need to make a chocolate cake for four people; please order all the necessary ingredients from Swiggy Instamart."

• "Schedule a cab for airport for tomorrow 05:45 AM via Uber"

• "Compose a lovely poem to wish my friend X a happy birthday and send it to him on WhatsApp."

• "Send 500 to X for cab share via UPI app" then it finds the X's details from phonebook and just prompts to enter the pin for payment, that's it!

and so on...

If you found this useful, share it, it really helps 🙏

"Sharing is caring" 🤝🏻

Let's catch up on X or visit my site to know more about me 😎.

📚References

• AppFunctions

• NotyKT

• Agent demo app

Every time I made breaking changes in a library, I had to manually explain them to the consumer app's Claude session. Copy-paste the diff. Re-explain what changed. Every single time. So I built a plugin to fix that.

Oh, and I built the plugin with Claude Code as well. The irony isn't lost on me 😄

This post is about that plugin, how I designed it, what broke, what I completely rethought, and what I finally shipped.

The Situation 😮

Here's what kept happening.

I have two separate Git repositories: my-library and my-app. They live in completely different directories on my machine. my-app depends on my-library as a published dependency — either from a remote package registry or a local Maven/npm/whatever repository.

These are separate repos for a reason. Different release cycles. Different teams. Different codebases. You can't just open a common root directory in Claude Code and get both into the same session. They're unrelated at the filesystem level. (Claude Code's --add-dir flag lets one session access multiple directories, but only when the code is on disk together — not when your library lives as a published package in a registry.)

So naturally I have two Claude Code sessions. One for each repo.

I'm in the library session, deep into making breaking API changes. Renamed functions, changed type signatures, removed deprecated stuff. My agent knows everything about what I did and why. It has the full conversation, the full diff, the full context.

Now I need to update the consumer app to use the new library version.

New terminal. New Claude session for my-app.

Zero context.

I'm copy-pasting diffs. Explaining what changed. Why the build broke. What to update. Manually.

Every. Single. Time.

The library agent and the consumer agent existed in complete isolation. They had no way to talk.

I thought: why not give them a way to talk?

The Idea 💡

I decided to build a Claude Code plugin for this. I called it session-bridge. Here's what I had in mind.

In the library session:

> /bridge listen
Session ID: a1b2c3
Listening for peer messages...

In the consumer session:

> /bridge connect a1b2c3
> /bridge ask "What breaking changes did you make?"
Response from my-library:
  3 changes in v2.0:
  1. login() -> authenticate() (takes Config object now)
  2. getUser() -> getCurrentUser() (returns UserProfile)
  3. Removed refreshToken() (automatic now)

The library agent responding with full context, because it's the same agent that made the changes. No copy-pasting. No explaining. Just agents talking.

First Design Decisions 🧠

Before writing any code, I spent time on the architecture. A few decisions shaped everything.

Transport: Files. Each session gets a directory at ~/.claude/session-bridge/sessions/<id>/ with inbox/ and outbox/ folders. Messages are JSON files. I considered MCP (Model Context Protocol, Claude Code's native plugin API for external tools) and local HTTP. Both are more elegant architecturally. But files have one big advantage: they're debuggable. You can literally cat a message to see what happened. No logs needed. No server to start. Files it is.

Message format. Each message is a JSON file with id, from, to, type, status, and content. The status field is the most important part. Messages start as pending. The moment a session picks one up, it atomically rewrites the file with status: "read". This prevents the same message from being processed twice, no matter how many things are polling the inbox simultaneously.

Session IDs. When a session starts a bridge, it generates a 6-char ID like a1b2c3. You copy that to the other terminal. Simple, but it works.

The core is 9 bash scripts and a jq dependency. No Node.js, no Python, no runtime. I wrote tests first — 124 test cases across 10 test files — and the tests caught so many edge cases before I ever ran the plugin manually.

The Hook System Did Not Cooperate 😤

My original plan was to use Claude Code's UserPromptSubmit hook to auto-check the inbox before every agent response. The hook fires before the agent processes each user message. I could inject inbox messages as context automatically.

First I tried a command hook — a shell script that runs on every prompt. But the working directory when hooks execute isn't the project root, so the script couldn't find the bridge session file. After hours of debugging I rewrote the inbox scanner to not depend on working directory at all.

Then I switched to a prompt-type hook, one that tells Claude what to do rather than running a script directly. My prompt said something like: "Before responding, check if bridge-session exists, then run check-inbox.sh".

Claude's reply:

"This is a hook evaluation context without shell access to the user's system."

Right. 🙃

Hooks were basically not going to work for what I needed. I ended up putting the inbox-check logic in the bridge-awareness skill, a piece of context that loads alongside the session and tells the agent how to behave with the bridge. Reliable enough, but not as automatic as I wanted.

The Background Watcher Detour 🤖

At this point, the plugin worked if the user typed commands explicitly. But I wanted automatic responses even when the user wasn't actively typing in the library session.

So I built bridge-watcher.sh. A background bash process that polls the inbox every 5 seconds. When a query arrives, it calls claude -p (Claude Code's non-interactive mode) to generate a response. It gathered context from git diffs, recent commits, CLAUDE.md, and even read Claude Code's internal session JSONL files to approximate the conversation history.

This worked. But it had problems:

• Every query triggered a claude -p call. That costs real money on your Anthropic account.

• The responses were generated from approximated context. I was sampling the agent's session history from outside and feeding it to a separate Claude process. Close, but not the real thing.

• The watcher was a whole separate process to manage: PID files, orphan detection, cleanup on crash.

The more I looked at it, the more it felt like I was solving the wrong problem. But it took one more bug to make that obvious.

The Bug That Ate Sessions 🐛

While the watcher was still in the picture, I hit a nasty bug: sessions were disappearing.

When you close Claude Code, it fires a SessionEnd hook which runs cleanup.sh. My cleanup script deletes the session directory. Fine.

But here's the problem: if you restart Claude quickly, the new session re-registers before the old session's cleanup hook finishes. Then the old cleanup runs and deletes the brand new session. Peers try to connect and get "session not found."

The fix: cleanup.sh now checks the session's lastHeartbeat before deleting. If the session was updated recently, it means another Claude instance just claimed it. So cleanup exits silently and leaves it alone.

This was fixable. But every fix revealed another crack. I was maintaining an architecture I didn't believe in.

The Insight That Changed the Architecture 🤯

I was looking at the watcher code and feeling like something was fundamentally wrong. It was calling claude -p for every incoming query. That costs money. And it was generating responses from a sampled approximation of the session context, not the real thing.

Then someone asked a simple question: "Why don't we just have the session answer directly?"

I stopped. Thought about it.

The library agent has complete context. It was there for every change. Every decision. Every reason why auth.login() became auth.authenticate(). Why am I sampling its conversation history and feeding it to a separate Claude process to approximate that knowledge?

What if the agent just... entered a listening loop?

> /bridge listen
Session ID: a1b2c3
Listening for peer messages... (Ctrl+C to stop)

The agent runs bridge-listen.sh, which polls the inbox every 3 seconds. A message arrives. The agent reads it, formulates a response from its actual live context, and replies. Then it calls bridge-listen.sh again. Continuously. Until you press Ctrl+C.

This is it. This is what the plugin should have been from day one. The watcher was trying to approximate the agent's context from outside when the agent itself was already right there.

bridge-watcher.sh got deleted. The plugin shrank by ~300 lines. API costs for auto-responses dropped to zero. Context quality went from "pretty good" to "perfect."

Agents Can Ask Each Other Questions Too 💬

While testing, I realised the agents sometimes need to ask each other clarifying questions before they can answer. Here's what that looked like:

Consumer: "How should I handle the new error types?"

Library: "What error types are you currently catching? Send me your error handler." Consumer: (reads its own code, sends the relevant snippet)

Library: "Replace AuthError with AuthException. Here's the updated hierarchy..."

This could deadlock. The consumer is blocked waiting for a response. The library wants to send a question back instead, but the consumer is waiting for an answer.

The solution: the library sends its question as a response, with inReplyTo pointing to the original message ID. The consumer finds it (it's a match on inReplyTo), reads the question, sends a new query with the answer, and waits again. The library's listen loop picks that up and gives the final answer.

No deadlock. One extra round trip. The conversation flows naturally.

What It Looks Like Today 🎯

Two terminals. Two projects. One bridge.

# Terminal 1 — Library (the session that has the answers)
> /bridge listen
Bridge auto-started! Session ID: a1b2c3
Listening for peer messages... (Ctrl+C to stop)

# Terminal 2 — Consumer (the session that needs answers)
> /bridge connect a1b2c3
Connected to 'my-library'
> /bridge ask "What changed in v2?"
Response from my-library:
  3 breaking changes:
  1. login() -> authenticate() (takes Config object)
  2. getUser() -> getCurrentUser() (returns UserProfile)
  3. Removed refreshToken() (automatic now)

That's the explicit way. But you don't even need to think about commands.

Just tell your agent what you want:

> Update our app to use the new version of my-library. Fix any breaking changes.

The agent detects it's a version bump, queries the library peer, gets the migration info, and applies the changes itself. You never type /bridge ask. You never copy-paste anything.

Agent: Asking my-library about breaking changes in v2...
Response from my-library:
  login() → authenticate() (takes Config object)
  getUser() → getCurrentUser() (returns UserProfile)
  refreshToken() removed (automatic now)
Applying changes:
  - Updated AuthService.kt: login() → authenticate()
  - Updated UserRepository.kt: getUser() → getCurrentUser()
  - Removed manual token refresh in SessionManager.kt
Build passing. Done.

I was honestly surprised when this worked the first time. I typed a plain English instruction, watched both sessions exchange messages I didn't initiate, and got back a passing build. Took maybe 30 seconds. The 45 minutes I used to spend copy-pasting context just... disappeared.

This is the real goal. Not new commands to learn. Just two agents coordinating on your behalf while you describe the outcome you want.

How it's helping me at least?

At work, we manage numerous repositories, and I've been using git worktrees frequently in Claude. I prefer to keep worktrees close to the project directories, so I avoid opening a single Claude session in the parent directory, as it would create too much context. Instead, I make significant changes in one repository, and when I need to modify another, I simply ask it to connect via bridge, sharing the session's working context. The sessions then communicate and resolve issues without manual context sharing—it's all automated. The interesting part? Recently, while integrating work, my agent discovered a bug in the library. It immediately sent the details via bridge, and the library module quickly fixed the bug, published the update, and asked the consumer module to test it. Everything happened synchronously through their communication. I was thrilled to see this in action 😄.

See it in the action

What's Missing (Being Honest) 🤔

Single machine only. Everything runs through the local filesystem. Two developers on different machines? Not supported. You'd need a relay server, which defeats the simplicity goal.

Context is only what the agent knows. The library agent responds from its own active conversation context. If the session was just started fresh and the agent hasn't worked on the library yet in this session, the responses will be shallow. The agent's context doesn't persist across sessions.

Response latency is ~5-10 seconds end-to-end (3-second poll interval plus the agent's response time). That's fine for this use case — cross-project coordination isn't real-time chat. But it's worth knowing.

Why This Matters 🌍

Claude Code sessions are isolated by design. That isolation is usually good. Each session focuses deeply on one project.

But we work in multi-repo, multi-service worlds. The library that breaks the consumer. The backend that changes the contract. The shared module that everything imports. In those situations, isolation gets in the way.

The agents we use are smart enough to coordinate. They just need a mechanism to do it. session-bridge is that mechanism: a file-based mailbox, a handful of bash scripts, and a skill that teaches agents the protocol.

Could the MCP version be cleaner? Yes. Would native Agent Teams integration be even better? Absolutely. But this v1 works today, with no dependencies beyond jq, on any machine running Claude Code.

Sometimes the simplest thing that could possibly work... is the right thing. ✌️

The plugin is open source at github.com/PatilShreyas/claude-code-session-bridge. Try it, break it, tell me what's missing. And if you found this useful, share it, it really helps 🙏

"Sharing is caring" 🤝🏻

Let's catch up on X or visit my site to know more about me 😎.

Fun fact: This blog was drafted by Claude Code, in the same session where I built the plugin😉

In this post, we are going to dive deep into the internals of Composition Local API of Jetpack Compose.

When you call LocalContentColor.current in your Compose code, a lot happens behind the scenes. Behind that simple property access lies a smart system of persistent maps, value holders, and composer integration that passes values down your composition tree efficiently. In this deep dive, we'll trace that journey through the actual AndroidX source code and understand exactly how CompositionLocal works under the hood.

🤔 What Problem Does CompositionLocal Solve?

Compose passes data through the composition tree explicitly via parameters to composable functions. While this is often the simplest approach, it becomes annoying when:

• Data is needed by many components deep in the tree (prop drilling)

• Components need to pass data between one another while keeping implementation details private

CompositionLocal provides an implicit way to have data flow through a composition hierarchy without explicitly passing it through every intermediate composable. Think of it like "ambient" data that's just there when you need it.

If you need a quick refresher, here is the basic usage pattern:

// 1. Create the Local
val LocalUser = compositionLocalOf { "Guest" }

@Composable
fun App() {
    // 2. Provide a value
    CompositionLocalProvider(LocalUser provides "Alice") {
        UserProfile()
    }
}

@Composable
fun UserProfile() {
    // 3. Consume the value (magic!) 🪄
    val name = LocalUser.current
    Text("Hello, $name")
}

📋 Prerequisites

This article assumes you're familiar with:

• Compose basics (composables, recomposition, remember)

• State in compose (MutableState and mutableStateOf for state management)

• Basic Kotlin features (data classes, lambdas, lazy delegate)

• Have used Composition local API (like LocalContext, LocalContentColor, etc)

🗺️ What We'll Explore

In this deep dive, we'll cover:

1. The Type Hierarchy - How CompositionLocal, ProvidableCompositionLocal, and their variants are structured

2. Factory Functions - What compositionLocalOf, staticCompositionLocalOf, and compositionLocalWithComputedDefaultOf actually create

3. Providing & Consuming - How CompositionLocalProvider and .current work, plus passing locals between compositions

4. Under the Hood - The internal machinery: Value Holders, Persistent Maps, and Composer integration

5. Practical Insights - Performance considerations and common pitfalls to avoid

Let's start by understanding the class hierarchy that makes it all possible.

🏗️ The Type Hierarchy

At the heart of the CompositionLocal system is a carefully designed class hierarchy:

Understanding the hierarchy:

• CompositionLocal<T> is the sealed base class that holds the current property you use to read values. It's sealed so that all implementations are controlled within the Compose runtime.

• ProvidableCompositionLocal<T> adds the ability to provide values using provides, providesDefault, and providesComputed.

• The three concrete implementations (Dynamic, Static, Computed) decide how values are stored and how changes trigger recomposition.

The Base Class: CompositionLocal

// Source: CompositionLocal.kt
@Stable
public sealed class CompositionLocal<T>(defaultFactory: () -> T) {
    // Stores the default value lazily - only computed when actually needed
    internal open val defaultValueHolder: ValueHolder<T> =
        LazyValueHolder(defaultFactory)

    // Called during recomposition to check if the ValueHolder 
    // can be reused or if a new one needs to be created
    internal abstract fun updatedStateOf(
        value: ProvidedValue<T>,
        previous: ValueHolder<T>?,
    ): ValueHolder<T>

    // The public API - asks the Composer to find the current value
    @OptIn(InternalComposeApi::class)
    public inline val current: T
       
    @ReadOnlyComposable @Composable get() = currentComposer.consume(this)
}

The @Stable annotation tells the Compose compiler that this class has stable equality - two instances with the same data are considered equal. The current property is marked @ReadOnlyComposable, meaning it only reads from the composition and doesn't change it. This lets the compiler make certain optimizations.

What if you try to access .current outside a @Composable function? You'll get a compile-time error:

"@Composable invocations can only happen from the context of a @Composable function".

The Compose compiler enforces this because current needs access to currentComposer, which only exists during composition.

ProvidableCompositionLocal: The Provider Interface

// Source: CompositionLocal.kt
@Stable
public abstract class ProvidableCompositionLocal<T> internal constructor(defaultFactory: () -> T) :
    CompositionLocal<T>(defaultFactory) {

    // Subclasses implement this to create the right ProvidedValue
    internal abstract fun defaultProvidedValue(value: T): ProvidedValue<T>

    // Always overrides any parent-provided value
    public infix fun provides(value: T): ProvidedValue<T> = defaultProvidedValue(value)

    // Only provides if no ancestor has already provided this local
    public infix fun providesDefault(value: T): ProvidedValue<T> =
        defaultProvidedValue(value).ifNotAlreadyProvided()

    // Provides a lambda that computes the value on each read
    // The lambda runs in CompositionLocalAccessorScope, letting 
    // it read other locals
    public infix fun providesComputed(
        compute: CompositionLocalAccessorScope.() -> T
    ): ProvidedValue<T> =
        ProvidedValue(
            compositionLocal = this,
            value = null,          // No static value
            explicitNull = false,
            mutationPolicy = null,
            state = null,
            compute = compute,     // Store the computation lambda
            isDynamic = false,
        )
}

The infix modifier enables the clean DSL syntax: LocalColor provides Color.Red. The three methods serve different purposes:

• provides - Always sets the value, overriding any parent-provided value

• providesDefault - Only sets the value if no ancestor has already provided it. Useful for library components that want to offer a default but respect app-level overrides:

  // Library code: provide a default, but let app override
  @Composable
  fun LibraryUsage() {
      CompositionLocalProvider(
          LocalAnalytics providesDefault NoOpAnalytics()
      ) {
          LibraryComponent()
      }
  }
  
  // App code: this takes precedence over the library's default
  @Composable
  fun App() {
      CompositionLocalProvider(
          LocalAnalytics provides RealAnalytics()
      ) {
          LibraryUsage()  // Uses RealAnalytics, not NoOpAnalytics
      }
  }
  

• providesComputed - Derives the value from other CompositionLocals

The providesComputed option is powerful - it lets you derive values from other CompositionLocals. The lambda runs in CompositionLocalAccessorScope:

// Source: CompositionLocal.kt 
public interface CompositionLocalAccessorScope {
    // Extension property to read other locals inside computed lambdas
    public val <T> CompositionLocal<T>.currentValue: T
}

Inside a providesComputed lambda, you use LocalXxx.currentValue (not .current) to read other locals.

Why .currentValue instead of .current? The .current property requires being inside a @Composable function (it's marked @Composable), but the providesComputed lambda isn't composable - it's just a regular lambda. The .currentValue extension property reads directly from the scope's map without needing a composition context.

Here's a complete example:

// Define the locals
val LocalBaseColor = compositionLocalOf { Color.Blue }
val LocalAccentColor = compositionLocalOf { Color.Blue }

@Composable
fun ThemedContent() {
    // Provide both: one with a value, one computed from the other
    CompositionLocalProvider(
        LocalBaseColor provides Color.Red,
        LocalAccentColor providesComputed {
            // 'this' is CompositionLocalAccessorScope, 
            // so we use .currentValue
            LocalBaseColor.currentValue.copy(alpha = 0.5f)
        }
    ) {
        // When LocalBaseColor changes, LocalAccentColor 
        // automatically reflects it
        val accent = LocalAccentColor.current  // Color.Red with 0.5 alpha
        Text("Accent color applied", color = accent)
    }
}

Note: The compute lambda runs on every read of the local, not reactively. Keep computations cheap.

⚡ Dynamic vs Static: The Performance Trade-off

The two main implementations differ in a single but important flag:

// Source: CompositionLocal.kt 
internal class DynamicProvidableCompositionLocal<T>(
    // Controls when values are "different"
    private val policy: SnapshotMutationPolicy<T>,  
    defaultFactory: () -> T,
) : ProvidableCompositionLocal<T>(defaultFactory) {

    override fun defaultProvidedValue(value: T) =
        ProvidedValue(
            compositionLocal = this,
            value = value,
            explicitNull = value === null,
            mutationPolicy = policy,// Used for change detection
            state = null,
            compute = null,
            isDynamic = true,       // ← This flag changes everything!
        )
}

// Source: CompositionLocal.kt 
internal class StaticProvidableCompositionLocal<T>(
    defaultFactory: () -> T
) : ProvidableCompositionLocal<T>(defaultFactory) {

    override fun defaultProvidedValue(value: T) =
        ProvidedValue(
            compositionLocal = this,
            value = value,
            explicitNull = value === null,
            mutationPolicy = null,      // No mutation policy needed
            state = null,
            compute = null,
            isDynamic = false,          // ← Static behavior
        )
}

The isDynamic flag decides the recomposition strategy:

Why two strategies?

First, a quick note on the snapshot system: This is Compose's change-tracking mechanism. When you read state.value, Compose records that your composable depends on that state. When the state changes later, Compose knows exactly which composables need to recompose - it's like an automatic subscription system.

• Dynamic wraps values in MutableState, so the snapshot system tracks exactly which composables read the value. When the value changes, only those specific composables recompose. This is great for values that change often (theme colors, user preferences).

• Static stores values directly without snapshot tracking. When the value changes, Compose doesn't know who read it, so it must recompose the entire subtree under the provider. This sounds wasteful, but it skips the overhead of snapshot tracking - perfect for values that rarely or never change (Android Context, configuration objects).

🏭 Factory Functions

These are the APIs you use to create CompositionLocals:

// Source: CompositionLocal.kt
// Creates a dynamic local with optional custom equality policy
public fun <T> compositionLocalOf(
    policy: SnapshotMutationPolicy<T> = structuralEqualityPolicy(),
    defaultFactory: () -> T,
): ProvidableCompositionLocal<T> = DynamicProvidableCompositionLocal(policy, defaultFactory)

// Creates a static local - use for values that rarely change
public fun <T> staticCompositionLocalOf(defaultFactory: () -> T): ProvidableCompositionLocal<T> =
    StaticProvidableCompositionLocal(defaultFactory)

// Creates a local whose default is computed from other locals
public fun <T> compositionLocalWithComputedDefaultOf(
    defaultComputation: CompositionLocalAccessorScope.() -> T
): ProvidableCompositionLocal<T> = ComputedProvidableCompositionLocal(defaultComputation)

The policy parameter in compositionLocalOf is often ignored but important. By default, it uses structuralEqualityPolicy() which compares values using ==. For large objects or objects with expensive equality checks, you might want referenceEqualityPolicy() (uses ===) or a custom policy.

🔗 Providing and Consuming Values

Now that we know how to create CompositionLocals, let's see how to provide and consume values. This is the API you'll use most often.

ProvidedValue: The Key-Value Pair

When you write LocalColor provides Color.Red, the provides infix function creates a ProvidedValue:

// Source: Composer.kt
public class ProvidedValue<T>
internal constructor(
    // The CompositionLocal key this value is for
    public val compositionLocal: CompositionLocal<T>,
    // The actual value (may be null if using state or compute)
    value: T?,
    // True if null was explicitly provided (vs. unset)
    private val explicitNull: Boolean,
    // For dynamic locals: how to compare values for changes
    internal val mutationPolicy: SnapshotMutationPolicy<T>?,
    // For dynamic locals: an existing State to reuse
    internal val state: MutableState<T>?,
    // For computed locals: the computation lambda
    internal val compute: (CompositionLocalAccessorScope.() -> T)?,
    // True if this should use snapshot tracking
    internal val isDynamic: Boolean,
) {
    private val providedValue: T? = value

    // Whether this value can override a parent-provided value
    // Set to false by providesDefault()
    public var canOverride: Boolean = true
        private set

    // Gets the effective value, handling the different ways a 
    // value can be stored
    internal val effectiveValue: T
        get() = when {
            explicitNull -> null as T
            state != null -> state.value      // Read from State
            providedValue != null -> providedValue  // Use direct value
            else -> composeRuntimeError("Unexpected form of a provided value")
        }

    // Returns this with canOverride = false (for providesDefault)
    internal fun ifNotAlreadyProvided() = this.also { canOverride = false }
}

The multiple nullable fields (value, state, compute) represent different "modes" of providing a value. Only one is typically active at a time:

The isDynamic flag determines whether the value eventually gets wrapped in a MutableState (by the ValueHolder), not which field is used in ProvidedValue itself.

CompositionLocalProvider

The composable that sets up a new scope:

// Source: CompositionLocal.kt

@Composable
@NonSkippableComposable  // Must always execute - can't be skipped even if inputs unchanged
public fun CompositionLocalProvider(
    vararg values: ProvidedValue<*>,
    content: @Composable () -> Unit,
) {
    // Tell the composer we're starting a provider block
    currentComposer.startProviders(values)
    // Execute the content with the new scope active
    content()
    // Tell the composer we're done - restore the previous scope
    currentComposer.endProviders()
}

The @NonSkippableComposable annotation is important - even if the provided values haven't changed, we must execute this composable to maintain the scope stack correctly.

API Variants:

The withCompositionLocal variants are useful when you need to return a value from the content block instead of just rendering UI:

// Example: Measure text with a specific density
@Composable
fun measureTextWidth(text: String, customDensity: Density): Int {
    val textMeasurer = rememberTextMeasurer()

    // Temporarily use custom density and return the measured width
    return withCompositionLocal(LocalDensity provides customDensity) {
        textMeasurer.measure(text).size.width  // Returns Int, not Unit
    }
}

🔀 Passing Locals Between Compositions

Sometimes you need to pass CompositionLocals to a composition that isn't a direct child - like a Dialog, Popup, or a custom composition created via Composition(). Compose provides CompositionLocalContext for this:

// Source: CompositionLocal.kt
public class CompositionLocalContext internal constructor(
    internal val compositionLocals: PersistentCompositionLocalMap
) {
    // Wraps the persistent map and provides equals/hashCode
}

Capturing the current context:

// Source: Composables.kt 
public val currentCompositionLocalContext: CompositionLocalContext
    @Composable
    get() = 
        CompositionLocalContext(
            currentComposer.buildContext().getCompositionLocalScope()
        )

When do you need this? Components like Dialog and Popup create separate window compositions - they're not children in the composition tree. Without special handling, your theme colors and other locals wouldn't flow through.

Realistic example - Custom Dialog:

@Composable
fun MyScreen() {
    var showDialog by remember { mutableStateOf(false) }

    // We're inside MaterialTheme, so LocalContentColor is available
    Button(onClick = { showDialog = true }) {
        Text("Show Dialog")
    }

    if (showDialog) {
        // Capture ALL current locals before entering the dialog
        val capturedContext = currentCompositionLocalContext

        Dialog(onDismissRequest = { showDialog = false }) {
            // Dialog creates a NEW composition (separate window)
            // Without this, LocalContentColor would be the default, 
            // not the theme's!
            CompositionLocalProvider(capturedContext) {
                Surface {
                    Text(
                        "This text uses the theme's content color!",
                        color = LocalContentColor.current // ✅ Works
                    )
                }
            }
        }
    }
}

How it works internally: The CompositionContext abstract class has a getCompositionLocalScope() method. When you create a child composition (like inside Dialog), it calls this method on its parent context to inherit locals. By providing capturedContext, you're bridging the gap between separate compositions.

🔧 Under the Hood: The Internal Implementation

Now that we've covered how to use CompositionLocals, let's dive into how they actually work. We'll explore three key pieces:

1. Value Holders - How values are stored

2. Persistent Maps - How scopes are organized

3. Composer Integration - How the runtime manages it all

📦 Value Holders: The Storage Mechanism

Values in the CompositionLocal system are wrapped in ValueHolder instances. This abstraction allows different storage strategies depending on whether the value is dynamic, static, computed, or a default:

The four holder types serve different purposes:

StaticValueHolder

The simplest holder - a direct wrapper around the value:

// Source: ValueHolders.kt 
internal data class StaticValueHolder<T>(val value: T) : ValueHolder<T> {
    // Simply returns the stored value - no indirection
    override fun readValue(map: PersistentCompositionLocalMap): T = value

    override fun toProvided(local: CompositionLocal<T>): ProvidedValue<T> =
        ProvidedValue(
            compositionLocal = local,
            value = value,
            explicitNull = value === null, // Handle explicit null vs unset
            mutationPolicy = null,
            state = null,
            compute = null,
            isDynamic = false,
        )
}

Because it's a data class, equality comparison is automatic - two StaticValueHolders with the same value are equal. This helps with efficient change detection during recomposition.

DynamicValueHolder

The key to fine-grained recomposition:

// Source: ValueHolders.kt
internal data class DynamicValueHolder<T>(val state: MutableState<T>) : ValueHolder<T> {
    // Reading state.value registers a read in the snapshot system
    // This is how Compose knows to recompose only the readers 
    // when value changes
    override fun readValue(map: PersistentCompositionLocalMap): T = 
        state.value

    override fun toProvided(local: CompositionLocal<T>): ProvidedValue<T> =
        ProvidedValue(
            compositionLocal = local,
            value = null,
            explicitNull = false,
            mutationPolicy = null,
            state = state, // Pass the State so it can be reused across recompositions
            compute = null,
            isDynamic = true,
        )
}

The magic happens in readValue(): accessing state.value is a snapshot read. The snapshot system records this read against the current RecomposeScope. Later, when state.value is written, only the scopes that read it get invalidated. 🎯

ComputedValueHolder

For values derived from other locals:

// Source: ValueHolders.kt
internal data class ComputedValueHolder<T>(
    val compute: CompositionLocalAccessorScope.() -> T
) : ValueHolder<T> {
    // The map IS the scope - it implements CompositionLocalAccessorScope
    // This lets the compute lambda access other locals via 
    // `LocalXxx.currentValue`
    override fun readValue(map: PersistentCompositionLocalMap): T = 
        map.compute()

    override fun toProvided(local: CompositionLocal<T>): ProvidedValue<T> =
        ProvidedValue(
            compositionLocal = local,
            value = null,
            explicitNull = false,
            mutationPolicy = null,
            state = null,
            compute = compute, // Store the lambda, not the computed value
            isDynamic = false,
        )
}

Notice that readValue calls map.compute() - the map itself implements CompositionLocalAccessorScope. Inside your compute lambda, you can call LocalOtherThing.currentValue to read other locals. This creates a dependency chain: if the upstream local changes, your computed value updates automatically.

LazyValueHolder

Used for default values to avoid unnecessary computation:

// Source: ValueHolders.kt
internal class LazyValueHolder<T>(
    valueProducer: () -> T
) : ValueHolder<T> {
    // Kotlin's lazy delegate - computed once on first access
    private val current by lazy(valueProducer)

    override fun readValue(map: PersistentCompositionLocalMap): T = current

    // Defaults can't be re-provided - this is an error
    override fun toProvided(local: CompositionLocal<T>): ProvidedValue<T> =
        composeRuntimeError("Cannot produce a provider from a lazy value holder")
}

Note this is a class, not a data class - each instance is unique. The lazy delegate makes sure the default factory runs at most once, even if multiple composables read the default.

🗺️ The Persistent Map Architecture

CompositionLocals are organized in persistent (immutable) maps. Understanding this architecture is key to understanding how scopes work:

How scope resolution works:

When you call LocalXxx.current, the composer looks for the key in the current scope. Each CompositionLocalProvider creates a new scope that contains its provided values merged with the parent scope. The arrows show inheritance - Provider 3's scope contains all values from providers 1, 2, and 3, plus any unprovided defaults from the root.

The "persistent" in persistent map means these maps use structural sharing. When Provider 3 adds one value to Provider 2's scope, it doesn't copy the entire map - it creates a new map that shares most of its structure with the parent. This makes scope creation O(log n) instead of O(n).

The Read Function

The core lookup logic is simple:

// Source: CompositionLocalMap.kt 
internal fun <T> PersistentCompositionLocalMap.read(
    key: CompositionLocal<T>
): T =
    // Try to find the key in the map; if not found, 
    // use the key's default holder, then call readValue 
    // to get the actual value from the holder
    getOrElse(key as CompositionLocal<Any?>) {
        key.defaultValueHolder 
    }.readValue(this) as T

This single line does a lot:

1. Look up the key in the current scope map

2. If not found, fall back to the key's defaultValueHolder

3. Call readValue() on the holder to get the actual value

4. Cast back to T (the unchecked cast is safe because the key and value types are linked)

Concrete Implementation

The actual storage uses a trie-based persistent hash map from kotlinx.collections.immutable. A trie is a tree structure where keys are broken into smaller pieces (like individual hash digits) - this allows multiple maps to share common branches, making copy-on-write operations efficient:

// Source: PersistentCompositionLocalMap.kt 
internal class PersistentCompositionLocalHashMap(
    node: TrieNode<CompositionLocal<Any?>, ValueHolder<Any?>>,
    size: Int,
) :
    // Extends the immutable collections library's PersistentHashMap
    PersistentHashMap<CompositionLocal<Any?>, ValueHolder<Any?>>(node, size),
    PersistentCompositionLocalMap {

    override fun <T> get(key: CompositionLocal<T>): T = read(key)

    override fun putValue(
        key: CompositionLocal<Any?>,
        value: ValueHolder<Any?>,
    ): PersistentCompositionLocalMap {
        // put() returns null if the value is unchanged (optimization)
        val newNodeResult = node.put(key.hashCode(), key, value, 0) 
            ?: return this

        // Create new map with updated node and size delta
        return PersistentCompositionLocalHashMap(
            newNodeResult.node, 
            size + newNodeResult.sizeDelta
        )
    }
}

The putValue method shows the immutability pattern: instead of changing the map, it returns a new map (or this if nothing changed). The trie structure means only the path from root to the changed leaf is copied - everything else is shared.

🧠 Composer Integration: The Heart of It

Now we reach the core implementation in GapComposer. This is where the value holders and maps come together with the composition runtime.

1. CompositionLocalProvider calls currentComposer.startProviders(values) - since currentComposer is a GapComposer instance (which implements the Composer interface), it goes directly there

2. GapComposer saves the current scope and creates a new merged scope containing the provided values

3. The content lambda executes with the new scope active

4. When content calls LocalXxx.current, it calls consume() on the same GapComposer, which reads from the current scope

5. After content finishes, CompositionLocalProvider calls endProviders(), which restores the previous scope

This push/pop pattern means nested providers work correctly - inner providers shadow outer ones, and exiting a provider restores the outer scope.

Getting the Current Scope

Before diving into the code, a quick note on reader: Compose stores the composition tree in a SlotTable - a flat, array-based data structure using a gap buffer algorithm. The reader is a SlotReader that navigates this structure. It provides methods like:

• parent / parent(group) - get parent group index

• groupKey(group) - get the key identifying a group type

• groupAux(group) - get auxiliary data stored with a group (like provider maps)

Think of it as a cursor that can walk up and down the composition tree.

// Source: GapComposer.kt 
private fun currentCompositionLocalScope(): PersistentCompositionLocalMap {
    // Fast path: return cached scope if available
    providerCache?.let { return it }
    // Slow path: walk up the tree to find the nearest provider
    return currentCompositionLocalScope(reader.parent)
}

private fun currentCompositionLocalScope(
    group: Int
): PersistentCompositionLocalMap {
    // ... inserting path omitted for simplicity ...

    if (reader.size > 0) {
        var current = group
        // Walk up the group tree looking for a provider group
        while (current > 0) {
            if (
                reader.groupKey(current) == compositionLocalMapKey &&
                reader.groupObjectKey(current) == compositionLocalMap
            ) {
                // Found it! Check for pending updates first, 
                // then fall back to stored value
                val providers = providerUpdates?.get(current)
                    ?: reader.groupAux(current) as PersistentCompositionLocalMap
                providerCache = providers  // Cache for later reads
                return providers
            }
            current = reader.parent(current)  // Move to parent group
        }
    }
    // No provider found - use root scope
    providerCache = rootProvider
    return rootProvider
}

The providerCache is a performance optimization. During a single composition pass, many composables might read locals. Caching avoids repeated tree walks. The cache is cleared when entering/exiting provider groups.

Starting a Provider

// Source: GapComposer.kt 
override fun startProvider(value: ProvidedValue<*>) {
    val parentScope = currentCompositionLocalScope()
    startGroup(providerKey, provider)

    // Get the previous ValueHolder for this local (if any)
    val oldState = rememberedValue().let {
        if (it == Composer.Empty) null else it as ValueHolder<Any?>
    }

    // Ask the CompositionLocal to create/update the ValueHolder
    val local = value.compositionLocal as CompositionLocal<Any?>
    val state = local.updatedStateOf(value as ProvidedValue<Any?>, oldState)

    // If the holder changed, remember the new one
    val change = state != oldState
    if (change) {
        updateRememberedValue(state)
    }

    // Create the new scope by adding this value to the parent scope
    val providers: PersistentCompositionLocalMap
    val invalid: Boolean

    if (inserting) {
        // First composition: create new scope
        providers = if (value.canOverride || !parentScope.contains(local)) {
            parentScope.putValue(local, state)
        } else {
            parentScope  // providesDefault and parent already has value
        }
        invalid = false
        writerHasAProvider = true
    } else {
        // Recomposition: check if scope actually changed
        // ... change detection logic omitted for simplicity ...
    }

    // Push invalidation state and set new scope as current
    providersInvalidStack.push(providersInvalid.asInt())
    providersInvalid = invalid
    providerCache = providers
    start(compositionLocalMapKey, compositionLocalMap, GroupKind.Group, providers)
}

The key insight here is the updatedStateOf call. This is where dynamic vs static behavior splits:

// Source: CompositionLocal.kt
override fun updatedStateOf(
    value: ProvidedValue<T>,
    previous: ValueHolder<T>?,
): ValueHolder<T> {
    return when (previous) {
        is DynamicValueHolder ->
            if (value.isDynamic) {
                // REUSE the existing MutableState, just update its value
                // This triggers snapshot invalidation for readers ✨
                previous.state.value = value.effectiveValue
                previous  // Return the same holder
            } else null  // Switching from dynamic to static

        is StaticValueHolder ->
            // Only reuse if value unchanged
            if (value.isStatic && value.effectiveValue == previous.value) previous
            else null

        is ComputedValueHolder ->
            // Only reuse if same lambda instance
            if (value.compute === previous.compute) previous
            else null

        else -> null
    } ?: valueHolderOf(value)  // Create new holder if can't reuse
}

For dynamic values, the same MutableState instance is reused across recompositions. When previous.state.value = value.effectiveValue runs, the snapshot system notifies all readers of that state. This is the mechanism for fine-grained recomposition!

Consuming a Value

After all that complexity, consumption is refreshingly simple:

// Source: GapComposer.kt
override fun <T> consume(key: CompositionLocal<T>): T =
    currentCompositionLocalScope().read(key)

It gets the current scope and calls read(), which we saw earlier handles the lookup and default fallback.

Ending a Provider

// Source: GapComposer.kt
override fun endProvider() {
    endGroup()
    endGroup()
    providersInvalid = providersInvalidStack.pop().asBool()  // Restore parent's invalid state
    providerCache = null  // Clear cache so next read walks the tree
}

Why two endGroup() calls? Looking back at startProvider(), it creates two nested groups:

1. First group (providerKey) - Wraps the provider itself and stores the ValueHolder via rememberedValue()

2. Second group (compositionLocalMapKey) - Stores the merged scope map as auxiliary data

This nesting allows Compose to store both the individual value holder (for reuse across recompositions) and the merged map (for scope resolution) in the slot table.

🔄 Putting It All Together: The Complete Flow

Now that we've seen all the pieces, let's trace what happens when you write LocalColor.current:

The critical difference is in the DynamicValueHolder path: calling state.value records a snapshot read. The snapshot system links this read to the current RecomposeScope. Later, when the state changes, only this scope (and others that read the same state) will recompose.

🔁 Invalidation and Recomposition

Now that we've seen the implementation details, here's a quick summary of how the two recomposition strategies play out in practice:

Dynamic CompositionLocal Flow

1. Provider calls startProvider() with a new value

2. updatedStateOf() finds the existing DynamicValueHolder

3. It updates holder.state.value = newValue

4. The snapshot system marks all readers of this state as invalid

5. On next frame, only those specific composables recompose ✨

Static CompositionLocal Flow

1. Provider calls startProvider() with a new value

2. updatedStateOf() sees the value changed

3. It creates a new StaticValueHolder (can't reuse the old one)

4. The new scope map is different from the old one

5. providersInvalid is set to true

6. The entire content subtree must recompose because Compose doesn't know who read this value 🌳

When to Use Which (Examples):

💡 Practical Insights

Performance Things to Know

1. Dynamic locals have per-read overhead: Each LocalXxx.current records a snapshot read. For locals read in tight loops or many places, this adds up.

2. Static locals have per-change overhead: Changing a static local recomposes everything below the provider. But if it never changes, there's no overhead.

3. Computed locals run on every read: The lambda runs each time you call .current. Keep computations cheap, or use dynamic locals with remembered computed values.

The CompositionLocal system shows thoughtful API design:

• Simple surface API: provides and .current cover 99% of use cases

• Layered complexity: Value holders, persistent maps, and composer integration work together smoothly

• Clear trade-offs: Dynamic vs static makes the performance implications obvious

• Efficient implementation: Structural sharing, lazy evaluation, and precise invalidation minimize overhead

The sealed class hierarchy ensures type safety. Value holders abstract storage strategies. Persistent maps enable efficient scope management. And the composer integration ties it all together with the rest of the composition system.

Understanding these internals helps you make better decisions: use compositionLocalOf for values that might change, staticCompositionLocalOf for stable configuration, and compositionLocalWithComputedDefaultOf for derived values. Place providers as close to consumers as practical, and remember that every LocalXxx.current call has implications for recomposition tracking.

Awesome. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄 Happy composing! 😎

Let's catch up on X or visit my site to know more about me 😎.

If you've been following my blog, you know what I write about. Around 60 posts, almost all of them about Android, Kotlin, Compose, Coroutines. That was my world.

Today is different. 😉

This post is about how I changed the way I work, not what I work on. And honestly, it's the best productivity change I've made in years as a Software Engineer.

🧠 A quick fact before we begin.

Research shows that humans are actually terrible at multitasking. The brain can't do two complex tasks at the same time. It switches rapidly between them, and every switch has a cost. Psychologists call these "switch costs." They decrease your productivity by up to 40%, increase errors, and hurt short-term memory. The more you switch, the more tired your brain gets and the worse your work becomes.

Every time you drop a half-finished feature to review a PR, your brain pays a tax. Every time you jump from debugging a crash to writing new code, you pay it again.

We've always just accepted this as part of the job.

But here's the thing: AI agents don't have this problem. 😄 They don't get mentally tired. They don't lose their place. An agent working on your onboarding screen has no idea your bug fix agent even exists. It doesn't care. It just works.

That's what this post is about.

🧑🏻‍💻 Let's begin the story!

It's random day's morning and you've been in the zone for 45 minutes. Deep in a feature branch, working through some tricky state management and architecture-related logic in the app, and finally, finally, the pieces are coming together for the new feature you're going to develop. Your editor is exactly how you left it. You know exactly where everything is in the code. You are, for once, actually in flow.

Then Slack lights up ➡️ A production crash, reported overnight. Users are hitting some crashes 💣 on the login screen on certain Android devices. Now you've to fix that crash on priority and do a hotfix too. Scroll down a bit and there's a teammate waiting on your PR review. They've been blocked since yesterday, and the comment timestamp is starting to feel accusatory. You stare at your terminal. One of these has to wait. Two of them will kill your context. You'll spend the next hour not doing any of them well, jumping between half-finished thoughts and losing the thread on all three. The important thing is that all of this has to be done in the same project!

Then I found a better way.

Most developers use AI tools like a search engine. One question, one answer, one task at a time. But Claude Code (Anthropic's AI agent that runs in your terminal), combined with git's worktree feature (which most developers never read about in the docs), makes something different possible: you can run multiple AI agents in parallel, each working on a separate task, while you focus on just one thing. One developer, multiple agents, multiple tasks, all moving forward.

By the end of this post, you'll know how to set up multiple AI agents across isolated git worktrees, so you can work on a crash fix, a feature screen, and a code review all at the same time, without losing context on any of them.

If you don't know about Git worktree then let's have a quick understanding.

🌿 What Is a Git Worktree?

Most developers think of it this way: one repo, one working directory. Switch branches and your files change. Need to jump to a hotfix? Stash your work, switch branches, fix the bug, switch back, pop the stash. And hope nothing breaks.

Worktrees change that. With git worktree add, you check out a second (or third) branch in a completely separate folder. Same repo, same git history, no stashing, no switching. Both branches just exist on disk at the same time.

Think of it like having two tabs open in the same Google Doc, except each tab shows a different version of the file. What you do in one tab doesn't touch the other.

So you can have main, feature/onboarding-screen, and fix/login-crash all checked out at the same time, in separate folders, with no conflicts. Three commands get you there:

# Create a new worktree for a branch
git worktree add ../myapp-feature feature/onboarding-screen

# List all active worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../myapp-feature

That's it. No extra setup needed. It ships with git.

🤖 Which AI agent?

This could work with any AI agent of your choice. Be it Claude Code CLI, Gemini CLI, Codex, Copilot, or anything. I'm using Claude Code CLI a lot since many months now. That's why you'll find mentions and usages of Claude in this blog but you can try it with your favourite agent. If you've not yet tried Claude Code CLI, it's an AI agent from Anthropic that runs in your terminal. Unlike a chat interface, it doesn't just answer questions. It reads your actual codebase, runs commands, writes and edits files, and works on its own. You point it at a problem and it goes.

Here's what makes it really useful: AI agent in terminal only sees the folder it's running in. Start a session inside /myapp-feature and it sees that branch, its files, its history, its context. Start a separate session in /myapp-bugfix and it sees that one. The two sessions don't know about each other at all.

This is the thing that clicked for me: one worktree + one Claude Code session = one autonomous agent. 🎯

"Three worktrees, three Claude Code sessions: three agents working in parallel while you stay focused on what only you can do."

⚡ Let's continue: Three Tasks, Zero Blocking

Back to our story. same three tasks, except this time you don't pick one and let the others wait.

"Here's exactly what I do now when this happens."

The three tasks:

1. Feature: implement a new onboarding feature in the app (feature/onboarding-screen). I already have a plan ready as I was in the zone for ~45m.

2. Bug: fix the crash in the app (fix/login-crash). This was an ad-hoc requirement and priority too!

3. PR review: teammate's work (in main). This was a work backlog.

Here's how to set up a worktree and a Claude Code agent for each one.

Step 1: Create the Worktrees

From your main repo directory, create a worktree for each branch. Each folder is fully isolated. Same git history, but completely separate working trees.

# From your main repo directory
git worktree add ../myapp-feature feature/onboarding-screen
git worktree add ../myapp-bugfix fix/login-crash

# Verify
git worktree list

Git creates the ../myapp-feature and ../myapp-bugfix folders for you. You don't need to create them first.

You should see all three worktrees listed:

/Users/you/myapp           abc1234 [main]
/Users/you/myapp-feature   def5678 [feature/onboarding-screen]
/Users/you/myapp-bugfix    ghi9012 [fix/login-crash]

If the branch doesn't exist yet, git worktree add creates it automatically. If it already exists remotely, use -b to create a proper local tracking branch: git worktree add -b feature/onboarding-screen ../myapp-feature origin/feature/onboarding-screen. Without the -b flag, passing a remote ref directly creates a detached HEAD instead of a named branch.

Step 2: Launch Claude Code in Each Worktree

Open three terminal windows (or tmux panes) and point each one at its folder:

# Terminal 1 — onboarding screen feature
cd ../myapp-feature && claude

# Terminal 2 — login crash fix
cd ../myapp-bugfix && claude

# Terminal 3 — your main repo (for PR review)
cd ~/myapp

Each Claude session starts fresh and only sees its own folder. The agents don't know about each other. No shared state, no bleed-over between sessions. Terminal 3 is yours for the PR review. No agent needed there unless you want one.

💰Claude CLI Bonus tip

In the previous section, I used raw git commands for creating worktrees so that you can use any AI agent with it but if you're only using Claude, then it has built-in command for quick worktree

# Start Claude in a worktree named "feature-auth"
# Creates .claude/worktrees/myapp-feature/ with a new branch
claude --worktree myapp-feature

# Start another session in a separate worktree
claude --worktree myapp-bugfix

# Auto-generates a name like "bright-running-fox"
claude --worktree

So yeah, if you don't want to manage worktrees manually, this is the way to go 🚀.

Step 3: Give Each Agent Its Task 📝

Let's write prompts that say exactly what done looks like.

For the feature agent (Terminal 1):

"Implement the onboarding screen as described in docs/onboarding-spec.md. It should be built in Jetpack Compose and: (1) show a 3-step progress indicator, (2) validate each field before allowing the user to advance to the next step, (3) call /api/onboarding/complete via the existing OnboardingRepository on the final step. Write unit tests for the ViewModel logic. Don't touch the auth flow or LoginActivity."

For the bug agent (Terminal 2):

"Investigate and fix the NullPointerException on the login screen described in bug-reports/2026-02-27-login.md. The crash reproduces on API 28 and below. Reproduce it first with a unit test, then fix the root cause. Don't change the login UI or touch LoginViewModel."

(as this is just an example, the actual prompts would be very detailed).

Meanwhile: You Do the PR Review 👀

You hit Enter on both prompts, watch the agents start up, then switch to Terminal 3. Pull up the PR diff. Your teammate's work, 400 lines, needs a proper look. You open the first file. Launch agent in # Terminal 3 as well and maybe you could use it to understand your teammate's work or take help in reviewing that.

Review the <TASK_NAME> PR of my colleague: .

- Check if <condition 1>
- Give me a review summary including suggestions
- Why there is usage of API in the change?
- Or anything else here...

Behind you, Terminals 1 and 2 are still running. Agent is reading files, making a plan, running commands. You can peek over or ignore it completely. The work is happening either way.

A few minutes in, you take a quick look at Terminal 1:

  Reading app/src/main/java/com/example/app/onboarding/OnboardingScreen.kt
  Reading docs/onboarding-spec.md
  Writing app/src/main/java/com/example/app/onboarding/OnboardingViewModel.kt

  OnboardingViewModelTest > validates required fields before advancing PASSED
  OnboardingViewModelTest > calls complete endpoint on final step PASSED

BUILD SUCCESSFUL in 18s
2 tests, 0 failures

Tests are green. ✅ It found the spec, read the composable, wrote the ViewModel logic, and confirmed everything works. All while you were reading someone else's code.

You finish the PR review, leave your comments, approve it. Then you check back in.

Terminal 1: the onboarding feature is drafted, two ViewModel tests passing, files updated exactly where the spec said.

Terminal 2: the login crash on API 28 reproduced, root cause found (a null pointer in the token refresh path), fix committed with a test that now passes. Both agents finished without asking me anything. No interruptions, no clarifying questions on this run. It feels the same way every time.

Terminal 3: It reviewed your colleague's PR, clarified your questions and also highlighted some changes your colleague should do.

You didn't manage them. You didn't step in. You did your own work, and when you came back, so had they.

Step 4: Clean Up the Worktrees 🧹

When each agent is done and you've reviewed its work:

# Push each branch for review
cd ../myapp-feature
git push origin feature/onboarding-screen

cd ../myapp-bugfix
git push origin fix/login-crash

# Remove the worktrees
cd ~/myapp
git worktree remove ../myapp-feature
git worktree remove ../myapp-bugfix

Fact: Agents/Claude can also push and create PR on behalf of you! So you don't even need to run these above commands these days.

One thing worth knowing: removing a worktree only deletes the folder. Your branches and commits are still there. You can check them out, open PRs, or delete them later in the usual way.

Two PRs open, one PR reviewed and approved. All from a single morning session. That's the whole workflow.

🔧 Patterns That Make This Work

Naming convention

Use ../projectname-<branch-slug> as your worktree path. Easy to find with a quick ls.

When all your worktrees follow the same prefix, a quick ls .. shows you everything that's active: myapp, myapp-feature, myapp-bugfix. No guessing which folder belongs to which task.

Shell aliases

Typing out the full git worktree add command every time gets old. Two aliases handle the common cases:

# Add to .zshrc / .bashrc

## Create a new worktree (works for both new and existing branches)
alias wt-new='f() { local slug="\({1//\//-}"; local wt_path="../\)(basename \(PWD)-\)slug"; git worktree add "\(wt_path" "\)1" 2>/dev/null || git worktree add -b "\(1" "\)wt_path"; }; f'

## Remove a worktree (does NOT delete the branch)
alias wt-clean='f() { local slug="\({1//\//-}"; git worktree remove "../\)(basename \(PWD)-\)slug"; }; f'

# Usage
wt-new feature/onboarding-screen
wt-clean feature/onboarding-screen

wt-new builds the worktree path from your repo name and the branch you pass in. wt-clean removes it using the same pattern. One argument, done.

When NOT to use worktrees ⚠️

Worktrees don't work well for every situation. Skip them when:

• Tasks share a build cache with side effects (common in multi-module projects)

• Both tasks modify the same build files (such as build.gradle, gradle/libs.versions.toml)

• Task B depends on task A finishing first

In these cases, running agents in parallel will cause conflicts or wasted work. Run them one at a time instead, and keep the parallel setup for tasks that are truly independent of each other.

⏱️ The Time Math

Let's put some real numbers on this. Those three tasks from this morning (new onboarding screen, login crash fix, PR review) are a pretty normal engineer morning. Here's roughly how the time looks across three different ways of working:

• The first row is the usual dev day: context switching, stashing, losing focus.

• The second is what most people think of when they say they "use AI": faster, but still one task at a time.

• The third is what this whole post is about.

That's not a small difference. That's shipping three things in a morning instead of one. Over a week, that's actually clearing your backlog instead of just feeling busy.

The bottleneck was never your skill. It was the one-task-at-a-time model. AI agents remove that limit, if you let them.

💡 What This Actually Changed

The speed improvement was real, but that's not what I think about. What changed was how day feel. I stopped staring at three tasks trying to figure out which one to sacrifice. Instead of "what do I have to skip today?" it became "what do I want to work on while the rest gets handled?"

You're not just a developer anymore. You're the person who decides what gets built and reviews what comes back. The agents handle the actual execution.

I remember the moment it really hit me. There was a bug that another team's member was supposed to fix, something that only showed up in a very specific edge case. I gave it to an agent as a side task while I worked on a new feature. Ten minutes later I looked over and it was fixed. A day of putting it off, gone in the time it took to write one decent prompt.

Do definitely try it on your next feature. Set up two worktrees, give your AI agent specific tasks with clear acceptance criteria, and go review that PR you've been putting off. See what's done when you come back. And when you ship more things early, tell me what you built in the comments below. 🚀

Awesome. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄 Happy vide coding! 😎

Let's catch up on X or visit my site to know more about me 😎.

📚References

• https://www.apa.org/topics/research/multitasking

• https://git-scm.com/docs/git-worktree

• https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees

It was an absolutely amazing experience at DroidCon India 2025. Seeing so many Android engineers under one roof at the world's largest Android conference was something special. The energy at DroidCon India 2025 was high. There were incredible speakers, people from different backgrounds, and so many ideas coming together.

Watch the Talk

If you could not make it or want to watch the talk again, the recording is now out.

📺 Session Recording

📊 Slides

My Session: Android App Performance ⚡

I got the chance to speak on a topic I really care about: Android App Performance.

My session was the very last one of the event, so I was surprised by the crowd. The room was full with almost ~400 developers! It was great to see so many people stay until the end to learn about performance. The feedback I got was really nice, and I am glad people found the talk useful.

I have always been a big fan of DroidCon. This event is very special to me. The last time DroidCon happened in India, I was just a student in college. I looked up to the experts on stage back then.

Now in 2025, it felt great to see it return to India. It was even better to be part of the Program Committee. It felt like a full circle moment for me to contribute to the event that inspired me when I was starting out.

The Community

Meeting people outside the sessions was just as good as the talks. I met so many passionate developers and had great conversations. Met my friends with whom I always have Android-ish tech chats.

One of the best parts was when people came up to me to say that my blogs or open-source work helped them. That feeling is hard to describe. It is exactly why I love this community. 🙌

Some photos:

A big thank you to everyone who attended, the organizers, and the volunteers who made DroidCon India 2025 a success. See you at the next one! 👋

It’s awesome to see Jetpack Compose being adopted in so many apps. If you're using Compose, you've almost certainly worked with its powerful LazyList APIs like LazyColumn and LazyRow. They are incredibly efficient for displaying list of items.

However, there's a tiny parameter in the items function that can cause some seriously confusing behavior if overlooked. In this blog, we're going to explore how missing one small thing: the key and how it can lead to tricky state management issues.

Preface

A while back, I posted a poll on X and LinkedIn asking developers a simple question:

The results were interesting and mostly similar across both platforms!

• 🟢 Always use — 60%

• 🟡 Sometimes — 32%

• 🔴 Never/Didn’t know — 8%

This poll inspired me to write this post to shed some light on this important detail especially for 40% of Android developers.

Before we dive into the problem, let's quickly understand what this key parameter actually does.

What is key {} in LazyColumn

When you provide a list of items to a LazyColumn or LazyRow, you can also provide a key for each item. This key is a stable and unique identifier for that specific piece of data.

LazyColumn {
    items(
        items = myItems,
        key = { item -> item.id } // Provide a unique ID for each item
    ) { item ->
        MyItemRow(item)
    }
}

Think of it like a primary key in a database table. It gives Compose a way to track each item individually, even if the list changes.

Why is this important?

• Performance Boost 🚀: When you add, remove, or reorder items in your list, Compose uses these keys to understand which items have changed. This allows it to be much smarter. For example, if you reorder items, Compose can just move the corresponding composables without completely redrawing them. This avoids unnecessary work and makes your app feel smoother.

• Stable Identity: The key tells Compose, "Hey, this item is the same one as before, it's just in a different position now." Remember that DiffUtil.ItemCallback in RecyclerView? 🤔

What happens if you don't specify a key?

If you skip the key, Compose falls back to using the item's position (or index) in the list as its identifier. For a list that never changes, this is perfectly fine. But for a dynamic list where items can be added or removed, this can lead to some unexpected problems. Because whenever the list changes, even if some items in the list might not have been changed, it’ll still cause recompositions for such items.

The most important rule for keys is that they must be unique. If two items have the same key, your app will crash with an error.

Now, let's get to the fun part and see what can go wrong.

What can go wrong if key is missing

Let's imagine a simple scenario. We have a LazyColumn showing a list of fruits. Each Fruit item is a composable that can be updated. When you tap the '+' or '-' buttons, it changes a quantity, and the item's background highlights to show it has been modified.

Here’s what the UI for a single fruit item looks like:

And here is the code for our Fruit composable:

@Composable
fun Fruit(fruit: Fruit, modifier: Modifier = Modifier) {
    Row(/*...*/) {
        var quantity by remember { mutableIntStateOf(0) }
        var hasChanged by remember { mutableStateOf(false) }

        Text(fruit.emojifiedImage, /*Other parameters*/)

        Column(/*...*/) {
            Text(fruit.name)
            Row {
                Button(onClick = { quantity-- }) { Text("-") }
                Button(onClick = { quantity++ }) { Text("+") }
            }
        }

        if (hasChanged) {
            Box(Modifier.background(MaterialTheme.colorScheme.tertiary)) {
                Text("$quantity", /*Other parameters*/)
            }
        }

        // 👀 Pay attention to this. This only notifies whether any changes have been made 
        // to this fruit or not.
        LaunchedEffect(Unit) {
            snapshotFlow { quantity }.filter { it != 0 }.first()
            hasChanged = true
            println("${fruit.name} has changed")
        }
    }
}

Notice that the quantity and hasChanged states are managed inside the Fruit composable using remember {}. hasChanged is a boolean state which is being mutated only from LaunchedEffect only when quantity is updated for the first time, then prints a simple log to console and it leaves the block. Since underneath it’s using a snapshotFlow {}, there’s no need to specify a key to LaunchedEffect.

Finally, we display the list on a screen and add a button to remove the first item. We are not providing a key in our LazyColumn.

@Composable
fun DemoScreen() {
    var fruits by remember { mutableStateOf(sampleFruits) }

    Column(/*...*/) {
        OutlinedButton(onClick = { fruits = fruits.removeAt(0) }) {
            Text("Remove first")
        }
        LazyColumn(/*...*/) {
            items(fruits) {
                Fruit(it)
            }
        }
    }
}

Now, let's perform a few actions on the UI:

1. Click + on Apple -> logs Apple has changed

2. Click “Remove first” on top -> It removed the first item from list i.e. Apple -> Now Banana is in 1st place. But it’s still keeping the state of old item along with highlighted background

3. Click + on Orange -> logs Grape has changed

4. Click + on Peach -> logs Strawberry has changed

See it here:

Surprised? 🤯 This shouldn’t have happened right?

This strange behavior happens because of how Compose reuses composables.

When you don't provide a key, Compose identifies each item by its position. In our example, the "Apple" item was at position 0. It had its own internal state (quantity and hasChanged) that we modified.

When we removed "Apple" from our data list, "Banana" moved into position 0. From Compose's perspective, it sees that there is still a composable at position 0. To be efficient, it decides to reuse the existing composable and just give it the new data ("Banana" instead of "Apple").

The problem is that the remembered state from the old item is still attached to that composable "slot" at position 0. So, "Banana" inherits the quantity and hasChanged state that originally belonged to "Apple".

In ideal situations, when the state comes from the ViewModel, UI state-related issues won't be noticeable. However, the concern here is with the behavior of LaunchedEffect. If you're calling some business logic from side-effect APIs or using anything related to it, it can be confusing.

The Simple Solution: Provide a key

This entire problem can be fixed with a single line of code. We just need to tell Compose how to uniquely identify each fruit.

LazyColumn(/*...*/) {
-   items(fruits) {
+   items(fruits, key = { it.id }) {
       Fruit(it)
    }
}

By adding key = { fruit -> fruit.id }, we are now telling Compose to track items by their unique ID, not by their position.

With this change, when we remove "Apple" (which has its own unique ID), Compose knows that the composable associated with that specific key is gone forever. It completely removes it, along with its state. It then creates a fresh new composable for "Banana" in its place, with a clean state. Everything works as you would expect! ✅

And console also prints valid values meaning LaunchedEffect block is actually working as expected

Apple has changed
Banana has changed
Orange has changed
Peach has changed

An Alternative (But Flawed) Solution 🤔

You might be wondering if there are other solutions. For example, you could pass the fruit object as a key to the remember and LaunchedEffect blocks inside the Fruit composable.

- var quantity by remember { mutableIntStateOf(0) }
+ var quantity by remember(fruit) { mutableIntStateOf(0) }
- var hasChanged by remember { mutableStateOf(false) }
+ var hasChanged by remember(fruit) { mutableStateOf(false) }
//...
- LaunchedEffect(Unit) {/*...*/}
+ LaunchedEffect(fruit) {/*...*/}

This tells Compose to reset the state whenever the fruit input changes, which does fix the issue.

But ideally, a composable shouldn't have to do this. Why should the Fruit composable worry that it might receive another item’s content? It's not aware that it's being used in a list. In real-world scenarios, we often read state from a ViewModel, so a situation like this might not happen. But the main takeaway is that if you're using stateful APIs like remember or side-effects like LaunchedEffect, they will be affected by this recycling behavior.

A component shouldn’t have the overhead of providing extra keys, as it shouldn't have to worry about where it’s going to be rendered. The responsibility should lie with the parent that is managing the list.

Under the Hood: How key Works? 🧙‍♂️

So what’s happening internally? It all comes down to how Compose generates and caches the composables for your list items.

Deep inside the Compose framework, there's a class called LazyLayoutItemContentFactory. Its main job is to manage the content (the composable lambdas) for each item in the lazy list. It has a cache, which is essentially a map that stores the generated composable for each item.

// From LazyLayoutItemContentFactory.kt
/** Contains the cached lambdas produced by the [itemProvider]. */
private val lambdasCache = mutableScatterMapOf<Any, CachedItemContent>()

When it's time to display an item, the factory's getContent method is called. This method is the key to our mystery.

// Simplified from LazyLayoutItemContentFactory.kt
fun getContent(index: Int, key: Any, contentType: Any?): @Composable () -> Unit {
    val cached = lambdasCache[key] // Tries to find a cached item using the key
    return if (cached != null && ...) {
        cached.content // Found it! Return the cached composable.
    } else {
        // Didn't find it. Create a new one and add it to the cache.
        val newContent = CachedItemContent(index, key, contentType)
        lambdasCache[key] = newContent
        newContent.content
    }
}

When you provide a key, that key is used to look up the item in lambdasCache. Since your key is stable and unique (like fruit.id), Compose can always find the correct composable along with its remembered state.

But if you don't provide a key, Compose uses the item's index as the key. So when "Apple" at index 0 is removed, "Banana" moves to index 0. Compose looks in the cache for index 0 and finds the old composable that belonged to "Apple", and reuses it for "Banana".

This cached content is then passed to subcompose, which is the mechanism that actually creates and manages the UI tree for that item.

// From LazyLayoutMeasureScopeImpl.kt
val itemContent = itemContentFactory.getContent(index, key, contentType)
return subcomposeMeasureScope.subcompose(key, itemContent)

By passing your stable key to subcompose, you ensure that the state is correctly associated with the data, not just the position.

Conclusion

So, what's the main takeaway?

If your list is completely static and will never change, you can get away with not using a key. However, for any list that is dynamic where items can be added, removed, or reordered then providing a key is essential. It not only improves performance but is also crucial for correct state management.

I think we should make it a habit to always add a key. You might think a list is static today, but requirements can change in future and then it’s easy to miss it in PR review. Adding a key from the start makes your code more robust and saves you from debugging some very confusing issues down the road.

I hope you got the idea about how important it is to provide key to LazyList APIs.

Awesome. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄 Happy composing! 😎

Let's catch up on X or visit my site to know more about me 😎.

This post will break down that mechanism: PausableComposition. This is internal API of compose and it’s not necessary for developers to know about it. But it’s good to know how it works under the hood. For Jetpack Compose developers who want to look behind the curtain and understand how Compose achieves its incredible performance, this exploration will give you a clearer picture. We'll dive into the runtime source code to see how it works, why it's so important for performance, and how everything is coordinated to make our UIs feel so fluid. Let's get started!

The “Why”

To get a fluid 60 frames per second (fps), our app needs to draw each frame in under 16.7 milliseconds. When a user scrolls through a LazyColumn, new items have to be created, measured, and drawn within this tiny window.

If an item is complex, with nested layouts, images, and lots of logic, the work needed to compose it can easily take longer than 16ms. When this happens, the main thread gets blocked, a frame is dropped, and the user sees a "jank" or stutter in the scroll. 😩

This is exactly the problem PausableComposition was created to solve.

The "What": A Smarter Way to Compose

Imagine you're a chef preparing a big meal for an event. 👨‍🍳 Instead of frantically trying to cook everything from scratch when the first guest arrives, you do your mise en place (the prep work) hours before. You chop vegetables, prepare sauces, and bake desserts. When it's time to serve, the final cooking and assembly are incredibly fast.

PausableComposition brings this "prep work" idea to Compose. It lets the runtime:

1. Compose Incrementally: Break down the composition of a big UI element into smaller, more manageable pieces.

2. Prepare Asynchronously: Do this composition work before the UI is actually needed on screen, often using the idle time between frames.

This pre-warming of composables means that when an item finally scrolls into view, most of the heavy lifting is already done, allowing it to show up almost instantly.

To visualize the concept, have a look on the below animation:

As scrolling occurs, let's say items A, B, C, D, and E are already visible on the screen, and the next item is F. If item F has a complex layout or structure that requires more time for layout computation or other pre-processing before rendering on the UI, this pre-processing happens in chunks within the frame timeline (i.e., 16ms). So, if it requires 2 frames, the necessary pre-processing for F is completed over 2 frames in the idle times without causing any jank to the frames. Finally, it is drawn on the UI when it needs to be visible. The same process applies to items G and H.

How It Works: The Core Components

By looking at the runtime source code, we can see how this is handled through a few key interfaces and classes. While you won't use these APIs directly, understanding them shows how LazyColumn gets its performance. 🕵️‍♂️

The Lifecycle: PausableComposition and its Controller

The journey starts with the PausableComposition interface, which extends ReusableComposition to add the ability to be paused.

Here’s how PausableComposition looks like:

// https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/PausableComposition.kt;l=66
sealed interface PausableComposition : ReusableComposition {
    fun setPausableContent(content: @Composable () -> Unit): PausedComposition
    fun setPausableContentWithReuse(content: @Composable () -> Unit): PausedComposition
}

(Note: The interface is sealed because it has a closed, limited set of implementations only inside the Compose runtime. This gives the compiler more information to make optimizations.)

Calling setPausableContent doesn't immediately compose the UI. Instead, it returns a PausedComposition object, which acts as our controller for the step-by-step process.

// https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/PausableComposition.kt;l=112
sealed interface PausedComposition {
    val isComplete: Boolean
    fun resume(shouldPause: ShouldPauseCallback): Boolean
    fun apply()
    fun cancel()
}

This lifecycle is best shown as a state machine:

• resume(shouldPause: ShouldPauseCallback): This is the engine. The prefetching system (here in the context of LazyColumn) repeatedly calls resume() to do chunks of composition work. The magic is in the shouldPause callback. The Compose runtime calls this lambda often during composition. If it returns true (for example, because the frame deadline is near), the composition process stops, giving the main thread back to more important work like drawing the current frame.

• apply(): Once resume() returns true, which signals it's finished, apply() is called. This takes all the calculated UI changes and commits them to the actual UI tree.

• cancel(): If the user scrolls away and the pre-composed item is no longer needed, cancel() is called to throw away the work and free up resources.

A Look at the Internals: PausedCompositionImpl

The state machine above is managed by the internal PausedCompositionImpl class. This class holds the state and connects all the pieces.

// https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/PausableComposition.kt;l=202
internal class PausedCompositionImpl(...) : PausedComposition {
    private var state = PausedCompositionState.InitialPending
    internal val pausableApplier = RecordingApplier(applier.current)
    // ...

    override fun resume(shouldPause: ShouldPauseCallback): Boolean {
        when (state) {
            PausedCompositionState.InitialPending -> {
                // This is the first time resume() is called.
                // It starts the initial composition of the content.
                invalidScopes =
                    context.composeInitialPaused(composition, shouldPause, content)
                state = PausedCompositionState.RecomposePending
                if (invalidScopes.isEmpty()) markComplete()
            }
            PausedCompositionState.RecomposePending -> {
                // This is for subsequent calls to resume().
                state = PausedCompositionState.Recomposing
                // It tells the Composer to continue where it left off,
                // processing any pending invalidations.
                invalidScopes =
                    context.recomposePaused(composition, shouldPause, invalidScopes)
                state = PausedCompositionState.RecomposePending
                if (invalidScopes.isEmpty()) markComplete()
            }
            // ... other states like Recomposing, Applied, Cancelled are handled here ...
        }
        return isComplete
    }

    override fun apply() {
        // ... other state checks ...
        if (state == PausedCompositionState.ApplyPending) {
            applyChanges() // The call site
            state = PausedCompositionState.Applied
        }
        // ...
    }

    private fun applyChanges() {
        // ...
        pausableApplier.playTo(applier, rememberManager)
        rememberManager.dispatchRememberObservers()
        rememberManager.dispatchSideEffects()
        // ...
    }
}

When resume() is called, it checks its internal state and acts accordingly:

1. InitialPending: On the first call, it kicks off the composition process by calling context.composeInitialPaused. This tells the core ComposerImpl to start executing the @Composable content, honoring the shouldPause callback.

2. RecomposePending: On subsequent calls, it continues the work by calling context.recomposePaused. This is used to process any parts of the composition that were invalidated (due to state changes) or to continue work that was previously paused.

3. Applier: Throughout this process, the ComposerImpl directs all its UI-changing operations to the pausableApplier (the RecordingApplier), which buffers them instead of applying them immediately.

4. This continues until the work is complete or the shouldPause callback returns true.

The RecordingApplier: Deferring the Final Touches

A key performance trick is the RecordingApplier. When resume() is called, the Composer doesn't change the live UI tree directly. Doing that in small pieces could be slow and lead to a weird, half-updated UI.

Instead, the PausableComposition uses a RecordingApplier. This special Applier just records all the UI operations it's supposed to do (like "create a Text node," "set its text property," or "add a child Image") into an internal list.

Only when PausedComposition.apply() is called does the RecordingApplier "play back" its recorded list of operations onto the real Applier, updating the UI tree in one efficient, single step. The public apply() method on PausedComposition is a simple state-machine guard. The real work happens in the internal applyChanges() method (as in the above snippet).

When applyChanges is called, it does three critical things in order:

1. It tells the RecordingApplier to play back all of its buffered commands onto the real applier. This is what makes the UI actually appear on screen.

2. It dispatches all the onRemembered lifecycle callbacks for any RememberObservers (like DisposableEffect) that were created.

3. Finally, it runs any SideEffects that were queued during the composition.

This ordered, batched process ensures the UI is updated efficiently and all lifecycle events happen at the correct time.

LazyList using PausableComposition

LazyList has started using PausableComposition API. In a LazyList, PausableComposition doesn't work alone. It's part of a well-coordinated system.

• The Conductor (Recomposer): The main Recomposer keeps the beat, driving the frame-by-frame updates for the visible UI.

• The Planner (LazyLayoutPrefetchState): As the user scrolls, this component predicts which items are about to show up.

• The Stage Manager (SubcomposeLayout): This powerful SubcomposeLayout is the foundation of LazyList. Its SubcomposeLayoutState can create and manage compositions for individual items when needed. Most importantly, it provides the createPausedPrecomposition() API.

• The Stagehand (PrefetchScheduler): This scheduler finds idle time between frames to do the pre-composition work requested by the Planner.

It's also interesting to see how this feature was developed. Inside the LazyLayoutPrefetchState file, you can find the feature flag that controls it:

// A simplified look inside LazyLayoutPrefetchState.kt: https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/lazy/layout/LazyLayoutPrefetchState.kt;l=647
if (ComposeFoundationFlags.isPausableCompositionInPrefetchEnabled) {
    // This is the future, modern path.
    performPausableComposition(key, contentType, average)
} else {
    // This is the older, non-pausable fallback.
    performFullComposition(key, contentType)
}

This flag, isPausableCompositionInPrefetchEnabled, acts as a kill-switch. While its default value in the source code is false. If you want to enable pausable composition behaviour in the Lazy layouts (LazyColumn, LazyRow, etc), then we can simply enable it as follows:

class MyApplication : Application() {
    fun onCreate() {
        ComposeFoundationFlags.isPausableCompositionInPrefetchEnabled = true
        super.onCreate()
    }
}

The Planner: LazyLayoutPrefetchState in Detail

The LazyLayoutPrefetchState is the brain of the prefetching operation. Its job is to take the prediction from the LazyLayout (e.g., "item 25 is coming up") and turn it into an actual pre-composition task.

It does this through a PrefetchHandleProvider, which creates a PrefetchRequest. This request is a unit of work that the PrefetchScheduler can execute. Inside this request, we find the heart of the pausing logic.

When the PrefetchScheduler executes a request, it enters a loop that calls resume() on the PausableComposition. The lambda passed to resume is where the decision to pause is made.

So if the above feature flag is enabled, it executes request through Pausable composition API as follows:

// https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/lazy/layout/LazyLayoutPrefetchState.kt;l=754
// Simplified from HandleAndRequestImpl inside LazyLayoutPrefetchState
private fun PrefetchRequestScope.performPausableComposition(...) {
    val composition = // get the composition for the item of the LazyLayout 
    pauseRequested = false

    while (!composition.isComplete && !pauseRequested) {
        composition.resume {
            if (!pauseRequested) {
                // 1. Update how much time is left in this frame's idle window.
                updateElapsedAndAvailableTime()

                // 2. Save how long this work chunk took, to improve future estimates.
                averages.saveResumeTimeNanos(elapsedTimeNanos)

                // 3. The Core Decision: Is there enough time left to do another
                //    chunk of work without risking a frame drop?
                pauseRequested = !shouldExecute(
                    availableTimeNanos,
                    averages.resumeTimeNanos + averages.pauseTimeNanos,
                )
            }
            // 4. Return the decision to the composition engine.
            pauseRequested
        }
    }

    updateElapsedAndAvailableTime()
    if (pauseRequested) {
        // If we decided to pause, record how long the final pause check took.
        averages.savePauseTimeNanos(elapsedTimeNanos)
    } else {
        // If we finished without pausing, record the time for the final resume chunk.
        averages.saveResumeTimeNanos(elapsedTimeNanos)
    }
}

Let's break down this logic:

1. updateElapsedAndAvailableTime(): Inside the resume lambda, the system constantly checks how much time is left before the next frame needs to be drawn.

2. averages.saveResumeTimeNanos(...): It records how long each small piece of composition work takes. This helps it build an average (averages) to predict the cost of future work.

3. !shouldExecute(...): This is the core decision. It compares the availableTimeNanos against a budget. This budget is a smart estimate: the average time it takes to do another chunk of work plus the average time it takes to pause. If there isn't enough time, pauseRequested becomes true.

4. Final Timing: After the loop exits for this cycle (either because the work is done or a pause was requested), one final updateElapsedAndAvailableTime() is called. This captures the time of the very last operation.

5. Saving Averages: The system then saves this final timing. If a pause was requested, it contributes to pauseTimeNanos. If the loop completed naturally, it contributes to resumeTimeNanos. This ensures the historical data used for future predictions is always accurate.

This self-regulating feedback loop allows the prefetcher to be aggressive when the system is idle but polite and respectful of the main thread when it's time to render the UI.

The Final Act: Applying the Pre-Composed UI

So, what happens when the pre-composed item is actually needed on screen? This is where the SubcomposeLayout takes center stage. During its normal measure pass, it calls its subcompose function for the now-visible item. Internally, this triggers the final step.

// https://cs.android.com/androidx/platform/frameworks/support/+/8d08d42d60f7cc7ec0034d0b7ff6fd953516d96a:compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/layout/SubcomposeLayout.kt;l=1186
// Simplified from LayoutNodeSubcompositionsState inside SubcomposeLayout.kt
private fun NodeState.applyPausedPrecomposition(shouldComplete: Boolean) {
    val pausedComposition = this.pausedComposition
    if (pausedComposition != null) {
        // 1. If the work must be completed now...
        if (shouldComplete) {
            // ...force the composition to finish by looping `resume`
            // and always passing `false` to the `shouldPause` callback.
            while (!pausedComposition.isComplete) {
                pausedComposition.resume { false }
            }
        }
        // 2. Apply the changes to the real UI tree.
        pausedComposition.apply()
        this.pausedComposition = null // Clear the handle.
    }
}

When an item becomes visible, its composition is no longer a low-priority background task; it's a high-priority, synchronous requirement. The shouldComplete = true parameter ensures that any remaining composition work is finished immediately, without pausing. Then, apply() is called, and the fully formed UI appears on screen instantly.

Here’s how they work together:

Conclusion

After a deep dive into the Compose runtime, the design of PausableComposition is a really smart piece of performance engineering.

• It's Not Magic, It's Deferral: The main idea is to do work before it's urgent. By composing items during idle time, the work needed on the main thread during a fast scroll is much, much smaller.

• Cooperative & Non-Blocking: The shouldPause callback is a brilliant way to handle multitasking. It lets long-running composition tasks politely step aside for the more urgent task of rendering the current frame, which directly prevents jank.

• Efficiency Through Batching: The RecordingApplier avoids the overhead of many small, separate changes to the UI tree by grouping them into a single, efficient update.

While PausableComposition is an internal feature you may never use directly, understanding its existence and operation gives you a real appreciation for the smart decisions that make Jetpack Compose so performant. The next time you effortlessly scroll through a complex LazyColumn without a single stutter, you'll know about the clever, well-orchestrated dance happening just beneath the surface. ✅ This architecture not only solves today's performance challenges but also paves the way for even more advanced rendering strategies in the future of Compose.

I hope you got the idea about how this new API works in Jetpack Compose.

Awesome. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

This post aims to demystify three such compiler annotations: @ReadOnlyComposable, @NonRestartableComposable, and @NonSkippableComposable. For Jetpack Compose developers already familiar with the basics, this exploration will provide clearer insights into how these annotations work, when to use them, and how they can help build even more polished and performant applications, complete with practical examples.

⚡ Quick Refresher

Before diving into the specific annotations, it's essential to revisit some fundamental concepts of Jetpack Compose's rendering model. These mechanisms are central to how Compose achieves its efficiency and dynamism.

Recomposition

Recomposition is the process by which Jetpack Compose re-executes composable functions when their underlying state or inputs change. This is the core mechanism that keeps the UI in sync with the application's data. Typically, a change to a State<T> object that is read within a composable will trigger its recomposition. Compose diligently tracks which composables depend on which state objects to perform these updates efficiently.

Skipping - Compose's Intelligent Laziness

To avoid unnecessary work, Compose features an intelligent skipping mechanism. If a composable's inputs have not changed since its last execution, Compose can skip re-running that composable and its children, reusing the previously emitted UI. This is a cornerstone of Compose's performance strategy, as it prevents entire subtrees from re-rendering if their data remains constant. Several conditions must be met for a composable to be eligible for skipping: its parameters must be stable, it should not have a non-Unit return type, and it must not be annotated with @NonSkippableComposable or be a non-restartable composable (which has its own skipping implications, let’s have a look on it later in this post).

Restartability - Independent Re-invocation

Restartable composables are functions that the Compose runtime can re-invoke independently during recomposition. This means they establish their own "restart scope." If a state read within a restartable composable changes, Compose can restart the execution from that specific composable. In contrast, if a non-restartable composable needs to update due to its own parameter changes, the recomposition process might be initiated from its nearest restartable parent scope.

A restartable composable function serves as a distinct "scope" where the recomposition process can initiate. It acts as a specific point of entry from which Jetpack Compose can begin re-executing code in response to state changes or updated parameters. Essentially, each non-inline composable function that returns Unit (the typical return type for UI-emitting composables) is transformed by the Compose compiler to establish such a scope. The compiler achieves this by wrapping the function's body within mechanisms that define this restartable boundary. This transformation includes injecting calls to functions like startRestartGroup and passing additional parameters such as a Composer instance and changed flags, which are instrumental in managing these scopes during runtime.

When a state object, such as a MutableState<T>, that is read within the body of a restartable composable changes its value, the scope associated with that composable is invalidated. This invalidation marks the scope as "dirty" and schedules it for recomposition. Similarly, if a parameter passed into a restartable composable changes from its previous value, this also serves as a trigger for its re-evaluation, assuming the composable is not skipped for other reasons.

Take a look here to understand it better:

So, in the above example: MainScreen and ExpandableText hoists a state that adds a capability in them to restart themselves.

Content is also a non-inline composable, so it forms its own restartable scope but the Content composable will only recompose when recomposition begins at the nearest restartable scope, such as MainScreen, which reads state changes. In short, even if Content has restartable scope (RS_2) still it’s not going to restart ever. Since it’s skippable too, it’ll skip recomposition if state is same as it was last time. However, for ExpandableText, recomposition can start from the parent restartable scope, moving from MainScreen → Content → ExpandableText if state.longMessage changes, or it can recompose itself due to reading the expand state.

Also, since Column is a inline-fun in compose, it’ll not have its own scope but it’ll take parent’s scope i.e. Content.

The Role of Parameter Stability

Parameter stability is a contract that informs Compose whether the value of a type can change and, if it does, whether Compose will be notified of that change. Primitive types (like Int, Boolean), String, and function types (lambdas) are inherently considered stable by the Compose compiler. Custom classes, however, need to meet specific criteria (e.g., all public properties are val and of stable types) or be explicitly marked with annotations like @Stable or @Immutable to be treated as stable. Stable inputs are a prerequisite for enabling the skipping optimization.

The interplay between skipping and restartability is nuanced. A composable function might be restartable, meaning it can serve as an independent starting point for recomposition, yet still be skipped if its inputs haven't changed. Conversely, a non-restartable composable might still undergo recomposition if its parent forces it to. A solid understanding of these core mechanisms: recomposition, skipping, restartability, and stability is foundational for effectively utilizing the advanced annotations discussed next. Misinterpreting these fundamentals can lead to the misapplication of these specialized tools.

Relationship Between Restartable and Skippable

A composable function can be restartable but not skippable. This typically occurs if it has one or more unstable parameters. In such a scenario, if its parent composable triggers a recomposition, this restartable-but-not-skippable child will also re-execute its body, regardless of whether its own direct inputs appear to have changed from the perspective of simple equality (because Compose cannot trust the stability of those inputs). For optimal performance, the ideal state for a composable is to be both restartable and skippable. Being restartable allows it to function as an independent unit of recomposition, and being skippable ensures that this unit will only perform work if its inputs have genuinely changed.

The connection here is fundamental: a restartable scope provides the granularity for recomposition, it defines "what can be redrawn independently." Skippability, which is heavily influenced by parameter stability, provides the intelligence to decide "whether it should be redrawn." One capability is less effective without the other. A non-restartable (inline) function, for example, cannot be skipped on its own; its parent's skippability determines its fate. Inline composables like Box, Column, Row do not create their own scopes; they are part of their parent's scope. Conversely, a restartable but non-skippable function acts as a well-defined boundary that will always redraw if its parent initiates a recomposition pass that includes it. This underscores the importance of striving for parameter stability in restartable composables to maximize performance benefits.

Summarizing concepts:

This comparative framework helps to clarify how these distinct but related concepts work together to achieve efficient recomposition.

🪧 Annotations

1. @ReadOnlyComposable: Reading Without Writing UI

The @ReadOnlyComposable annotation is a marker for @Composable functions that are intended only to read from the current composition context and must not emit any UI nodes. Such functions might access CompositionLocal values (like LocalContext.current or theme attributes) or compute values based on the compositional environment. It establishes a contract with the compiler about the function's read-only nature regarding UI output.

How it helps?

By guaranteeing that no UI nodes are written, @ReadOnlyComposable allows the compiler to perform certain optimizations. When examining the compiled code, functions annotated this way typically do not include the startReplaceableGroup and endReplaceableGroup calls that are standard for composables emitting UI elements. This directly reduces the overhead associated with managing nodes in the slot table for functions that don't contribute to the UI tree. Beyond optimization, it clearly signals the function's purpose: it's a composable designed for data retrieval or computation within the composition, not for UI construction. This promotes a cleaner separation of concerns, allowing data retrieval logic that depends on composition (e.g., current theme, screen density) to exist outside of UI-emitting composables, enhancing reusability and testability.

Examples:

1. Accessing MaterialTheme properties:

   object MaterialTheme {
       val colors: Colors
           @Composable
           @ReadOnlyComposable
           get() = LocalColors.current // LocalColors.current is a CompositionLocal

       val typography: Typography
           @Composable
           @ReadOnlyComposable
           get() = LocalTypography.current // LocalTypography.current is a CompositionLocal
   }

The MaterialTheme.colors getter needs to be @Composable to access LocalColors.current. However, it doesn't draw any UI itself; it merely returns the Colors object. The @ReadOnlyComposable annotation informs the compiler of this characteristic.

2. Accessing resources like strings or dimensions:

@Composable
@ReadOnlyComposable
fun localizedGreeting(userName: String): String {
    // stringResource is also @ReadOnlyComposable
    val greetingFormat = stringResource(R.string.greeting_format)
    return String.format(greetingFormat, userName)
}

@Composable
@ReadOnlyComposable
fun screenPadding(): Dp {
    return dimensionResource(R.dimen.screen_padding)
}

Explanation: These utility functions leverage the composable context (via stringResource and dimensionResource, which are themselves @ReadOnlyComposable) to fetch values. They don't emit UI but provide data for other composables.

When to use it:

• For utility functions that need to access CompositionLocals (e.g., LocalContext.current, LocalDensity.current, LocalLayoutDirection.current) but do not render UI.

• For theme property accessors, as demonstrated in the MaterialTheme example.

• For any function that computes and returns a value based on compositional information, which will then be used by other UI-emitting composables.

Important Constraint: A crucial rule is that @ReadOnlyComposable functions can only call other @Composable functions that are also marked as @ReadOnlyComposable. Attempting to invoke a regular UI-emitting composable from within a @ReadOnlyComposable function will lead to a compile-time error. This restriction is vital for maintaining the integrity of the "no UI emission" contract. If a @ReadOnlyComposable could call a UI-emitting composable, the compiler could no longer guarantee that the @ReadOnlyComposable itself doesn't indirectly cause UI to be emitted, thereby invalidating potential optimizations. Furthermore, these functions should not introduce (write) side effects or host State in a way that would trigger the recomposition of other UI elements. Using remember inside a @ReadOnlyComposable function can also be problematic, as remember interacts with the composer to store values in the slot table, which isn't strictly a "read-only" operation from the composer's perspective and can violate the annotation's contract.

2. @NonRestartableComposable - Controlling Recomposition Boundaries

The @NonRestartableComposable annotation is applied to a @Composable function to signal to the Compose compiler that it should not generate the usual machinery that allows this function's execution to be independently restarted or skipped during recomposition. In essence, it tells Compose that this particular composable does not require its own "restart scope". A restart scope is what allows Compose to re-execute a specific part of the UI tree without re-executing its parents if only local state changes.

In simple words: @NonRestartableComposable tells the Compose compiler that a particular composable function does not need to be independently restartable. Instead, it will always recompose if its parent composable recomposes. This can save the small overhead associated with managing its restartability.

How it helps?

This annotation can serve as a micro-optimization in specific, limited scenarios. It's potentially beneficial for small, simple composable functions that act as direct wrappers around another single composable, contain very little internal logic, and are themselves unlikely to be invalidated (i.e., recomposed due to their own parameter changes or direct state reads). By marking such a function as non-restartable, the compiler avoids allocating a restart scope for it, which can make the composition process marginally cheaper for these specific cases. If the Compose compiler reports indicate that a function is restartable but not skippable (perhaps due to one or more unstable parameters that are difficult to make stable), marking it with @NonRestartableComposable is one of the two suggested optimization paths. The alternative path is to make the function skippable by ensuring all its parameters are stable.

Example

@NonRestartableComposable // Potential candidate if 'content' rarely changes independently
@Composable
fun SimpleIconWrapper(icon: ImageVector, modifier: Modifier = Modifier) {
    // Very little logic, primarily passes parameters to Icon.
    // Assumes 'icon' and 'modifier' are stable and don't change often.
    Icon(imageVector = icon, contentDescription = null, modifier = modifier)
}

// Contrast with a composable that reads state directly:
@Composable
fun UserProfileHeader(userState: State<User>) {
    // This composable reads 'userState'. If 'userState.value' changes,
    // this composable needs to recompose.
    // @NonRestartableComposable would likely be inappropriate here as it's
    // expected to be a root of recomposition for its own state changes.
    Text(text = userState.value.name)
    //... other user details
}

Here, SimpleIconWrapper does very little beyond calling the Icon composable. If its parameters (icon, modifier) are stable and seldom change in a way that would require SimpleIconWrapper itself to be the starting point of a recomposition, it might be a candidate. The crucial factor is that it's "unlikely to be invalidated themselves".

When to consider using it?

• Simple and Stateless: It doesn't use remember to manage its own internal state. It primarily depends on the parameters passed to it. For small, stateless functions that primarily delegate to another single composable, have minimal internal logic, and are unlikely to be the "root" of a recomposition (i.e., they don't directly read state that changes frequently, and their parameters are stable).

• Frequently Used (Potentially): The benefits are more likely to be noticeable (though still often marginal) if the composable is instantiated many times, such as in a long list or a complex UI, where the saved overhead per instance might add up.

• Leaf-like or a Thin Wrapper: It often appears as a leaf node in the UI tree or as a very simple wrapper around another composable, applying a fixed modifier or a simple transformation.

• When compiler reports show a function is restartable but not skippable, and making it skippable by stabilizing all parameters is impractical or undesirable, this annotation offers an alternative optimization strategy.

Important Considerations and Caveats:

• Micro-optimization: This is for fine-tuning performance. The actual gains are often very small and may not be noticeable in most applications.

• Do profiling first: Always use profiling tools (like Android Studio's Layout Inspector or recomposition tracking) to identify actual performance bottlenecks before applying such optimizations. Premature optimization can make code harder to read and maintain for negligible benefit.

• Risk of Incorrect UI: If you incorrectly assume a composable doesn't need to be restartable (i.e., there are cases where it should be skipped but now won't be because its parent recomposed), it could lead to unnecessary recompositions or even incorrect UI if the parent recomposes but the child's specific inputs (that should have led to a skip) haven't changed.

• Not for Complex Logic: If a composable has complex logic or could truly benefit from being skipped independently, it should remain restartable.

Impact on recomposition scope

If a @NonRestartableComposable function does need to recompose (e.g., because one of its parameters changes), the recomposition will be initiated by its nearest restartable ancestor scope in the composable tree. This could potentially lead to a larger portion of the UI tree recomposing than if the function had its own dedicated restart scope. This trade-off is central to its use: a minor saving in scope allocation versus a potentially wider recomposition if the composable itself changes. This makes its ideal use case quite narrow, typically for stable passthrough wrappers. If the composable has significant internal logic or multiple child composables with their own potential state reads, the overhead of its own restart scope is likely justified to enable more granular recomposition.

3. @NonSkippableComposable - Forcing Re-evaluation

The @NonSkippableComposable annotation ensures that a composable function will always be executed (recomposed) whenever its parent composable recomposes, even if all of its own input parameters are stable and have not changed since the last composition. It effectively allows a composable to opt out of Compose's normal skipping mechanism.

How it helps?

This annotation is useful in particular situations where the default skipping behavior is undesirable.

• It can be used when a composable has important side effects or internal logic that must be re-evaluated on every recomposition cycle of its parent.

• It serves as a mechanism to opt out of "strong skipping" mode for a specific composable if there's a need for it to be restartable but explicitly non-skippable. Strong skipping, enabled by default in newer Compose versions, makes more composables skippable; @NonSkippableComposable is the explicit override.

• It can also be a tool for debugging, to ensure a specific composable is indeed being called during recomposition cycles as expected.

@NonSkippableComposable
@Composable
fun DebuggableCounterDisplay(count: Int, label: String) {
    // This composable will always execute its body if its parent recomposes,
    // regardless of whether 'count' or 'label' has changed.
    Log.d("RecompositionLogger", "DebuggableCounterDisplay executed with: $label - $count")
    Text("Label: $label, Count: $count (I always recompose with my parent!)")
}

@Composable
fun ControllingParent() {
    var parentStateTrigger by remember { mutableStateOf(0) }
    val stableCount = 5
    val stableLabel = "Current Value"

    Button(onClick = { parentStateTrigger++ }) {
        Text("Force Parent Recomposition: $parentStateTrigger")
    }

    // Even though 'stableCount' and 'stableLabel' do not change,
    // DebuggableCounterDisplay will re-execute (and log) every time
    // ControllingParent recomposes due to 'parentStateTrigger' changing.
    DebuggableCounterDisplay(count = stableCount, label = stableLabel)
}

In this scenario, DebuggableCounterDisplay will print its log message and redraw its Text component every time ControllingParent undergoes recomposition. This happens irrespective of whether the stableCount or stableLabel values have actually changed, due to the @NonSkippableComposable annotation. This represents a deliberate choice to prioritize execution over optimization for this specific composable.

When to use it (Cautiously):

• For composables that contain critical side effects that absolutely must run on each parent recomposition. However, it's important to critically evaluate if these side effects are better managed by dedicated side-effect handlers like LaunchedEffect, DisposableEffect, or SideEffect. These handlers offer more granular control over lifecycle and cancellation, and forcing a whole composable to re-run just for a side effect might be less clean.

• For debugging purposes, to confirm that a particular composable is being invoked during recomposition cycles.

• When strong skipping mode is enabled (default in Kotlin 2.0.20+), and there's a specific need for a restartable composable to not be skippable.

Performance Implication: This annotation deliberately bypasses a core Compose optimization (skipping). Consequently, its overuse can lead to performance degradation, as composables will perform more work than might be strictly necessary. While skippable composables might involve more generated code for the skipping logic, non-skippable ones incur the runtime cost of re-execution.

ReadOnlyComposable is pretty straightforward to understand but @NonRestartableComposable & @NonSkippableComposable are bif different and may sound confusing. So let’s understand the difference better.

Key Differences in NonRestartableComposable & NonSkippableComposable

While both @NonRestartableComposable and @NonSkippableComposable influence recomposition behavior and are listed as conditions that can make a composable ineligible for standard skipping , they operate on distinct aspects of the process. Confusion between them can arise because both represent deviations from "normal" composable behavior. However, the reason they deviate from the default skipping path is different.

@NonRestartableComposable primarily affects whether the composable function establishes its own restart scope. A restart scope allows Compose to re-execute just that composable and its children if its direct inputs or read state change. @NonSkippableComposable, on the other hand, directly dictates whether the composable's execution can be skipped if its inputs remain unchanged when its parent recomposes.

Crucially, @NonRestartableComposable does not imply @NonSkippableComposable. A composable function can be non-restartable (meaning it relies on its parent's restart scope if its own parameters change) but still be skippable if its own parameters are stable and haven't changed when that parent scope initiates a recomposition. Conversely, a composable can be restartable (possessing its own scope) yet be marked with @NonSkippableComposable to ensure it always re-executes with its parent.

The following table provides a side-by-side comparison to clarify their distinct characteristics:

Choosing between these annotations requires a clear understanding of why the default behavior needs to be altered. Is the goal to save the minor overhead of a scope for a trivial, stable function (@NonRestartableComposable), or is it to ensure a function always runs regardless of its inputs (@NonSkippableComposable)? Misapplying one for the other's intended purpose could lead to negligible benefits or, worse, unintended performance issues.

Interaction with Strong Skipping Mode

Strong Skipping Mode, which is enabled by default in Kotlin 2.0.20 and later versions of the Compose compiler , significantly alters the default skippability behavior of composables. This mode represents a notable shift in Compose's optimization strategy, aiming to make more composables skippable out-of-the-box and thereby reducing the developer's burden to manually ensure parameter stability just for skipping purposes.

The key changes introduced by Strong Skipping Mode are :

1. Composables with unstable parameters become skippable: Under strong skipping, even if a composable function receives parameters of types that the compiler cannot infer as stable, the function can still be skipped. The comparison for these unstable parameters is done using instance equality (===).

2. Lambdas with unstable captures are remembered/memoized: The compiler automatically wraps lambda expressions, even those capturing unstable variables, in a remember call, using appropriate keys based on the stability of captures. Essentially, with strong skipping, all restartable composable functions become skippable by default.

@NonSkippableComposable as an Opt-Out

In a strong skipping environment, the @NonSkippableComposable annotation becomes particularly important. If there is a restartable composable that should not be skipped (despite strong skipping's tendency to make it skippable), @NonSkippableComposable is the explicit way to enforce its re-execution. This gives developers precise control to override the aggressive default skipping behavior when necessary. Without it, developers would have limited recourse if the strong skipping heuristic was unsuitable for a specific restartable composable that requires guaranteed execution.

@NonRestartableComposable and Strong Skipping

Functions annotated with @NonRestartableComposable remain unskippable even when strong skipping is enabled. The rationale is that strong skipping primarily modifies the conditions under which restartable functions can be skipped. Since a @NonRestartableComposable function, by definition, lacks its own independent restart scope, the rules of strong skipping do not fundamentally alter its non-skippable nature in this context. Its non-skippability is inherently tied to its lack of a restart scope, not just parameter stability considerations.

Conclusion

The annotations @NonRestartableComposable, @ReadOnlyComposable, and @NonSkippableComposable are potent instruments in the Jetpack Compose developer's toolkit. They offer fine-grained control over the Compose compiler and runtime, enabling optimizations and enforcing behavioral contracts that go beyond the default capabilities. Still, these annotations can often seem confusing, so it's highly recommended to use them correctly by profiling and assessing performance thoroughly before implementing them and only use these annotations with proper understanding. This approach can boost confidence in your implementation. Use tools like the Layout Inspector in Android Studio (to check recomposition counts), Jetpack Macrobenchmark for broader performance testing, and Compose compiler reports (for analyzing stability and skippability).

I hope you got the idea about how exactly these annotations works in Jetpack Compose.

Awesome. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

Basics

Let’s go over some basics. Coroutines are supported by a thread pool. On the JVM, they use the java.util.concurrent.Executor API to manage execution for Dispatchers like Default and IO. On Android, they use the Handler APIs for Main dispatcher. For multi-platform, they use Promise APIs in JavaScript, and for native platforms like Apple, they use DispatchQueue under the hood. To understand this concept, I’ve wrote another blog that goes through the concept of coroutines from platform perspective and explains how delay works in coroutine. But for now let’s just talk about Android.

The CoroutineDispatcher handles dispatching tasks in coroutines, and each dispatcher must override the dispatch() method to execute tasks. HandlerContext is the implementation of Dispatchers.Main for Android platform. Here’s how its dispatch() implementation looks like:

override fun dispatch(context: CoroutineContext, block: Runnable) {
    if (!handler.post(block)) {...} 
    // ...
}

In short, each time whenever we say coroutineScope.launch(Dispatchers.Main) { doSomething() } or withContext(Dispatchers.Main) { doSomething() } under the hood it works as handler.post { doSomething() }. It justs executes that Runnable with Handler API.

Now let’s take a look at HandlerContext implementation from Dispatchers.Main.immediate perspective:

internal class HandlerContext private constructor(
    private val handler: Handler,
    private val name: String?,
    private val invokeImmediately: Boolean = false
) : HandlerDispatcher(), Delay {

    override val immediate: HandlerContext = if (invokeImmediately) this else
        HandlerContext(handler, name, true)

    override fun isDispatchNeeded(context: CoroutineContext): Boolean {
        return !invokeImmediately || Looper.myLooper() != handler.looper
    }

    override fun dispatch(context: CoroutineContext, block: Runnable) {
        if (!handler.post(block)) {
            cancelOnRejection(context, block)
        }
    }
}

When Dispatchers.Main.immediate is accessed it creates the HandlerContext instance with same Handler instance but with last parameter invokeImmediately as true. Otherwise for Dispatcher.Main its value remains false.

Now notice there’s one more method: isDispatcherNeeded. Official docs say:

So if isDispatchNeeded returns true then it submits the tasks to the threadpool/executor/handler otherwise synchronously on the current thread.

In HandlerContext, isDispatchNeeded() returns true if currently flag invokeImmediately is false and current looper is not as same as Handler’s (Main thread’s) looper. It means whenever these conditions are met, a task will be dispatched and dispatch() method will be invoked and ultimately for main thread it’ll execute task by posting the task to Handler (handler.post{}) by adding it to main thread’s event queue. It means, if currently task is being executed on the main thread and if flag invokeImmediately is true then this method will return false. In such case, dispatch won’t be performed and it’ll immediately executed on the same thread synchronously.

In Android-Kotlin extensions, lifecycleScope, viewModelScope uses Dispatchers.Main.immediate as a dispatcher context.

Understanding with example

Now let’s understand it better with an example. In this example, let’s understand it with a simple UI implementation with ViewModel based UI state emission. UI will subscribe the state provided by the ViewModel i.e. UI will be consumer and ViewModel will perform operation and produce the state i.e. producer.

So let’s create combinations of producer and consumer. Let’s try using Dispatchers.Main and Dispatchers.Main.immediate for producer and consumer combinations.

Simple code would look like:

class MainViewModel : ViewModel() {
    private val _state = MutableStateFlow<String?>(null)
    val state = _state.asStateFlow().filterNotNull()

    fun process(input: String) {
        viewModelScope.launch(PRODUCER_DISPATCHER) {
            _state.value = input
        }
    }
}

class MainActivity : ComponentActivity() {

    private val viewModel by viewModels<MainViewModel>()

    private val items = mutableStateListOf<String>()

    override fun onCreate(savedInstanceState: Bundle?) {
        /// ...
        setContent {
            Screen(
                items = items.toList(),
                onProcess = ::executeProcess,
                onClear = { items.clear() }
            )
        }
        observeState()
    }

    private fun observeState() {
        lifecycleScope.launch(CONSUMER_DISPATCHER) {
            viewModel.state.collect { state ->
                items.add(state)
                Log.d("StateStacktrace", Throwable().stackTraceToString())
            }
        }
    }

    private fun executeProcess() {
        (1..5).forEach {
            viewModel.process(it.toString())
        }
    }
}

Understanding the snippet:

• MainViewModel: This ViewModel hoists a state for UI consumption. It has a method process() which upon execution launched task on viewModelScope with PRODUCER_DISPATCHER as discussed above and it just sets value coming from UI to the _state.

• MainActivity: Simple activity that renders Composable Screen

  • observeState() method observes a state coming from ViewModel and subscribed to the flow on CONSUMER_DISPATCHER. Notice that we also have logged something there with current stacktrace details. We’ll use it later to understand the sequence of execution.

  • On clicking the "Process" button on the UI, executeProcess() is called. This function calls viewModel.process() five times, passing numbers from 1 to 5.

Here’s how UI looks like (Compose preview):

In the UI, these three circle with numbered texts are displayed from list of items assuming currently items contents are [“1”, “2“, “3“].

Now let’s try the app with our examples having four combination of dispatchers as discussed above.

Example 1: Produce and Consume on 🟢 immediate

Each time “Process” is clicked, the 5 new text items are appearing on the UI. Now, if you remember, while collecting a flow of state, we logged the stack trace each time we received a new state. Let's review it.

java.lang.Throwable
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:95)
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:93)
     at kotlinx.coroutines.flow.StateFlowImpl.collect(StateFlow.kt:396)
     at kotlinx.coroutines.flow.StateFlowImpl$collect$1.invokeSuspend(Unknown Source:15)
-    at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
-    at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:108)
-    .....
-    at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch(Builders.common.kt:56)
-    at kotlinx.coroutines.BuildersKt.launch(Unknown Source:1)
-    at kotlinx.coroutines.BuildersKt__Builders_commonKt.launch$default(Builders.common.kt:47)
-    at kotlinx.coroutines.BuildersKt.launch$default(Unknown Source:1)
!    at dev.shreyaspatil.maindispatcherexample.MainViewModel.process(MainActivity.kt:61)
!    at dev.shreyaspatil.maindispatcherexample.MainActivity.executeProcess(MainActivity.kt:102)
     at dev.shreyaspatil.maindispatcherexample.MainActivity.access$executeProcess(MainActivity.kt:67)
     at dev.shreyaspatil.maindispatcherexample.MainActivity$onCreate$1$1$1$1$1.invoke(MainActivity.kt:82)
     at dev.shreyaspatil.maindispatcherexample.MainActivity$onCreate$1$1$1$1$1.invoke(MainActivity.kt:82)
-    at androidx.compose.foundation.ClickableNode$clickPointerInput$3.invoke-k-4lQ0M(Clickable.kt:639)
-    .....
!    at android.view.ViewGroup.dispatchTransformedTouchEvent(ViewGroup.java:3144)
-    .....
!    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:911)

The stack trace at the bottom starts with a click event being dispatched from a View. It then propagates a click event from a Compose API, which invokes MainActivity#executeProcess. This calls MainViewModel#process, and from there, it directly propagates through coroutines, then StateFlow APIs, and finally into MainActivity#observeState$emit (collector). This means, from a click event till flow collector, all the operations happened synchronously. Let’s visualize the process:

Since both PRODUCER_DISPATCHER and CONSUMER_DISPATCHER were using Dispatchers.Main.immediate and all operations were already running on the main thread, no separate dispatch operation occurred. Task executions were not managed by Handler#post(), even when the state was being observed in a coroutine or the ViewModel was launching a coroutine.

Example 2: Produce on immediate, consume on Main

Strange, no? On clicking “Process”, only last item i.e. “5” is rendered and then even after clearing UI’s state (not ViewModel’s) the data is never processed again! Let’s take a look at this combination’s stacktrace.

java.lang.Throwable
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:95)
     at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:93)
     at kotlinx.coroutines.flow.StateFlowImpl.collect(StateFlow.kt:396)
     at kotlinx.coroutines.flow.StateFlowImpl$collect$1.invokeSuspend(Unknown Source:15)
     at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
     at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:108)
     at android.os.Handler.handleCallback(Handler.java:995)
     at android.os.Handler.dispatchMessage(Handler.java:103)
     at android.os.Looper.loopOnce(Looper.java:239)
     at android.os.Looper.loop(Looper.java:328)
     at android.app.ActivityThread.main(ActivityThread.java:8952)
     at java.lang.reflect.Method.invoke(Native Method)
     at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:593)
!    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:911)

Nothing here. At very bottom we can see task has been newly executed on the Main thread and it is directly resuming on the StateFlow's collector. Since this log is only added on the consumer side (flow collection), and this flow is collected on the Main dispatcher this time, not immediately, it means that each time a new value is produced in the flow, the collector will add the block to the main thread’s event queue (causing it to dispatch a call to Handler.post{}).

In short, when a click event is dispatched from the View APIs, the MainViewModel#process is called synchronously on the main thread, and flow collection occurs through dispatching.

Let’s visualize how this combination is working:

Okay, why only 1 item is getting collected on the UI side?

Since we are using StateFlow here, StateFlow API has conflation behaviour. In the context of Flows (and data streams in general), conflation means that if a producer emits new values faster than a collector can process them, the intermediate, unprocessed values are effectively dropped. The collector is guaranteed to get the most recent value, but it might miss some values that were emitted while it was busy processing a previous one.

StateFlow's Conflation Behavior:

StateFlow is designed specifically as a state holder. It always holds a single, current value. Its conflation behavior is inherent and fundamental to its design:

1. Value Updates: When you update the value of a StateFlow (either by assigning to mutableStateFlow.value or using tryEmit or emit), the new value immediately replaces the previously held value. StateFlow doesn't maintain a buffer or queue of past values beyond the current one.

2. Collector Perspective: When a collector is attached to a StateFlow (using .collect { ... }), it first receives the current value. Then, whenever a new value is emitted after the collector has finished processing the previous one, the collector receives that new value.

3. The Conflation: If multiple values are emitted to the StateFlow while a collector is still busy processing a previously received value, that collector will only receive the very last value that was emitted before it became ready again. All the intermediate values emitted during its processing time are missed by that specific collector – they are conflated.

In our case, each time a value is produced by the ViewModel, it is collected from the UI side on the Main dispatcher. Before the dispatch can occur (main thread’s event queue polling) and execute the flow collection on the consumer's side (Handler.post{}), the ViewModel finishes processing all the items submitted to it from "1" to "5." This happens because it runs synchronously on the same thread, and no separate dispatch occurs while setting the state of the ViewModel. Consumer doesn’t gets chance to collect all the items and before that ViewModel finishes setting the last state as “5”, so UI just gets that. Even if the UI state is cleared and if "Process" is clicked again, the same thing happens. Since the previous state was "5" and the new state is still "5" after processing and this time as well consumer doesn’t gets chance to listen to all the updates and last state is “5” again, the emission is skipped because StateFlow only emits values if they are distinct.

Example 3: Produce on Main, Consume on immediate

The behaviour seems similar as first example’s but difference is visible if we take a look on the stacktrace:

java.lang.Throwable
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:95)
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:93)
-    at kotlinx.coroutines.flow.StateFlowImpl.collect(StateFlow.kt:396)
-    at kotlinx.coroutines.flow.StateFlowImpl$collect$1.invokeSuspend(Unknown Source:15)
-    at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
-    .....
-    at kotlinx.coroutines.flow.StateFlowImpl.updateState(StateFlow.kt:349)
-    at kotlinx.coroutines.flow.StateFlowImpl.setValue(StateFlow.kt:316)
!    at dev.shreyaspatil.maindispatcherexample.MainViewModel$process$1.invokeSuspend(MainActivity.kt:62)
     at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
     at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:108)
     at android.os.Handler.handleCallback(Handler.java:995)
     at android.os.Handler.dispatchMessage(Handler.java:103)
     at android.os.Looper.loopOnce(Looper.java:239)
     at android.os.Looper.loop(Looper.java:328)
     at android.app.ActivityThread.main(ActivityThread.java:8952)
     at java.lang.reflect.Method.invoke(Native Method)
     at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:593)
!    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:911)

The consumer side's stack trace begins with the MainViewModel#process logic, where the StateFlow's value is set, and the flow collector is called right away. On the producer side, each item from "1" to "5" is processed by dispatching a separate coroutine. This means a separate dispatch occurs five times, and the StateFlow's value is set each time. However, since the collection is immediate and doesn't require a separate dispatch for the collector (consumer), all values are directly sent to the consumer without missing any. Visualizing this would help understanding it better:

So even if the behavior of Example 1 and Example 3 looks the same, it is technically different. In Example 1, there were no dispatches on the Handler, whereas in this example, there are 5 dispatches from the producer side.

Example 4: Produce on Main, Consume on Main

The behaviour is same as Example 2’s and stacktrace would be same as well since in Example 2 as well, consumer uses Dispatchers.Main:

java.lang.Throwable
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:95)
!    at dev.shreyaspatil.maindispatcherexample.MainActivity$observeState$1$1.emit(MainActivity.kt:93)
     at kotlinx.coroutines.flow.StateFlowImpl.collect(StateFlow.kt:396)
     at kotlinx.coroutines.flow.StateFlowImpl$collect$1.invokeSuspend(Unknown Source:15)
     at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
     at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:108)
     at android.os.Handler.handleCallback(Handler.java:995)
     at android.os.Handler.dispatchMessage(Handler.java:103)
     at android.os.Looper.loopOnce(Looper.java:239)
     at android.os.Looper.loop(Looper.java:328)
     at android.app.ActivityThread.main(ActivityThread.java:8952)
     at java.lang.reflect.Method.invoke(Native Method)
     at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:593)
!    at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:911)

In this example, the producer (ViewModel) dispatches tasks on the Main thread’s event queue, and the consumer (UI) also subscribes to the flow, which needs to be dispatched on the Main thread’s event queue. Let's visualize this:

Whenever Handler.post{} is called, it internally keeps a queue of Runnables that are executed in order. In this example, both the producer and consumer need dispatching, which means the queue will first add 5 producer items, followed by the consumer’s dispatch for collection of item. According to the queue’s order, all the producer’s tasks will be processed from item “1” to “5.” By the time the consumer’s turn comes, the last value is already set to 5, so the consumer never gets a chance to collect the values from “1” to “4.”

Cool, that’s all about combinations of examples and here’s summary:

Resuming from non-main dispatcher to Dispatchers.Main.immediate

By now, you might understand how behavior changes when using combinations of Dispatchers.Main and Dispatchers.Main.immediate. As we learned earlier, the isDispatchNeeded() implementation causes this behavior. For the Main dispatcher, we learned that Dispatchers.Main.immediate doesn't dispatch a task if it's already running on the Main thread's looper. But what happens if the immediate dispatcher is used and it's being resumed from another dispatcher? Let’s see this small example:

fun example() {
    lifecycleScope.launch(Dispatchers.Main.immediate) {
        setLoading(true)
        val profileData = withContext(Dispatchers.IO) { repository.fetchProfile() }
        showProfile(profileData)
        setLoading(false)
    }
}

In this example, whenever example() is called, setLoading(true) runs immediately because it's launched with the immediate dispatcher. On the next line, fetchProfile() is called by switching to the IO dispatcher. Once fetching is complete and profileData is loaded, the context switches back to the main thread. This time, isDispatchNeeded() will return true because the current looper is not the same as the Main thread's looper, as the IO thread was just used. Therefore, dispatching occurs to the main thread, and then showProfile() and the following methods are called after dispatching to the main thread.

So, behind the scenes, the above snippet can be visualized like this:

fun example() {
    setLoading(true) // Not dispatching to handler since it's on immediate

    ioExecutor.execute {
        val profileData = repository.fetchProfile()

        // Currently it's on IO dispatcher. So will need to dispatch call to main thread.
        handler.post {
            showProfile(profileData)
            setLoading(false)
        }
    }
}

That's the beauty of coroutines. It just skips the writing of callback hell for developers and manages it well internally in such a way that we could synchronously write asynchronous code!

Why Choose immediate?

We've dug deep into how Dispatchers.Main and Dispatchers.Main.immediate work differently, especially regarding the isDispatchNeeded check and interaction with the Handler. This might leave you wondering: why would you explicitly choose immediate? And why did the AndroidX team decide to make Dispatchers.Main.immediate the default dispatcher for key extension scopes like lifecycleScope and viewModelScope?

The core reasons boil down to performance optimization and immediacy, particularly targeting the common case where coroutine work starts on the main thread and needs to interact with the UI promptly.

1. Avoiding Unnecessary Overhead:

   • As we saw, Dispatchers.Main always posts the coroutine's execution block (as a Runnable) to the main thread's Handler queue.

   • If your code launching or resuming the coroutine is already on the main thread, this post operation, while generally fast, still represents a small amount of overhead: creating the Runnable, enqueueing it, and waiting for the Looper to process it in a subsequent pass.

   • Dispatchers.Main.immediate, thanks to its isDispatchNeeded check returning false when already on the main looper, skips this handler.post() step entirely in that specific scenario. It executes the code directly and synchronously within the current execution flow. This micro-optimization avoids the queueing delay and object allocation associated with the post.

2. Enhanced Responsiveness:

   • Beyond raw performance, immediate provides, well, immediacy. Imagine a button click handler (running on the main thread) launching a coroutine using viewModelScope to update some state and maybe show a loading indicator immediately.

   • With Dispatchers.Main.immediate, that initial setLoading(true) call inside the coroutine runs right now, within the same event cycle as the button click handler.

   • With Dispatchers.Main, that setLoading(true) would be posted to the Handler and run slightly later, after the current block of main thread work finishes and the Looper processes the queued item. While often imperceptible, using immediate guarantees the operation happens synchronously when possible, which can contribute to a snappier feel for UI updates initiated from the main thread.

The AndroidX Choice:

The designers of the AndroidX libraries likely chose Dispatchers.Main.immediate as the default for scopes like lifecycleScope and viewModelScope precisely because these scopes are heavily used for tasks tightly coupled with the UI lifecycle. Many operations initiated within these scopes start from main thread callbacks (like user interactions, lifecycle events, or observing data that was updated on the main thread). Using immediate optimizes for this frequent pattern, ensuring work happens without unnecessary dispatch delays when already on the correct thread.

And crucially, as we explored earlier, immediate doesn't break things when you do need dispatching. When resuming from a background thread (like after a withContext(Dispatchers.IO) block), isDispatchNeeded correctly returns true, and the necessary handler.post{} occurs to get you back to the main thread safely. It aims to provide the best of both worlds: synchronous execution when safe and efficient, and proper dispatching when required.

But if instant execution is not needed and if we are fine to perform operations on main thread by posting task on main thread’s event queue, it’s preferred to use Dispatchers.Main.

I hope you got the idea about how exactly dispatcher Main and immediate works in the coroutine and how their behaviour changes in different cases 😃.

Awesome 🤩. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

🎬 Kickstart of journey

In 2019, during my second year of engineering college, I was just a someone who was learning and building apps in Android at that time, working on my new Android app project. I used the Firebase UI SDK to display data from the Firebase Realtime Database. I needed to show data in pages, but at that time, the official Firebase UI library didn't support pagination. Until then, I wasn't even aware of GitHub and open source. Then I learned about open source and GitHub and discovered that the FirebaseUI-Android SDK is open source, and we can contribute code to it. First, I cloned it, developed a pagination API, and open-sourced it internally on my own GitHub account (later I contributed it to the official SDK 😀). I used my version of the API in my Android app, continued using it, and saw that it was serving its purpose.

I thought I should spread the word about it since it was useful for me and could help others too if they needed it. I already had accounts on Twitter and LinkedIn (I just wasn't very active), so I logged in again and noticed that many popular Android developers were writing posts on medium.com. At that time, ProAndroidDev, MindOrks, AndroidPub, and others were well-known publishers in the AndroidDev community. So, I signed up on medium.com and wrote my first article. I decided to submit it to ProAndroidDev, and after a few hours, I received a couple of suggestions for improvements from their editors. I addressed all the feedback, and they approved my post. Finally, on April 8, 2019, I published my first tech blog 🎉. I kept the title very simple: “Firebase Database Pagination - Android 🔥“.

After publishing the blog, the next day on the 9th of April’s night, I shared it on Facebook, Android-related FB groups, Twitter and LinkedIn. Till this point, I never had thought that blogging would become my regular practice. Before publishing the blog, I was so nervous and I was getting so many negative thoughts and had fear of publishing something publicly. Do you know what motivated me to continue it? The next day I woke up in the morning and I saw this message on a Facebook messenger DM 😃

I read this early in the morning and felt so happy. It was satisfying to know that what I did helped someone. I realized that whatever we share as a learning experience can be useful to anyone, whether it's simple beginner stuff or complex advanced topics. This one message cleared all my fears that I was getting before publishing the article and boosted my confidence. That's when I decided to keep writing articles on medium.com.

As time went on, I started creating my open-source libraries on GitHub and exploring some Android APIs. Then I wrote a few more articles and published them on MindOrks and ProAndroidDev. I also published an article on the official Firebase Developers Medium publication. If you notice, all my early blogs were mostly tutorials kind of stuff and nothing more 😅. I was also getting a good response from them, so continued it. My initial blogs be like 👇🏻

As I published open-source projects and content, I began gaining followers on Twitter and making good connections on LinkedIn. Then one day, the “Google Developers Experts” account started following me on Twitter, which boosted my confidence even more (I never expected that to happen 😅*. This happened two years prior of being a GDE*).

I was also exploring Flutter for cross-platform app development during this time. I learned about Google AppScript and how I could use it as an API for data operations in Google Sheets. So, I created a simple proof of concept with Flutter, made it open-source on GitHub, and wrote an article about it. When I published it, the response was surprising. Within a day, I gained many followers on GitHub, Twitter, and LinkedIn. That repository received many stars on GitHub and became the #1 trending project in the Dart language category. I wasn't even very skilled in Flutter at that time, but I learned about the growing popularity and strong community of Flutter developers 💪🏻.

Fun fact: Even after being a native app developer, my first repo that went #1 trending on GitHub was Flutter 😃. And till the date, that blog has more views than my other Android or Kotlin related blogs.

🏠 Lockdown - The golden opportunity

In 2020, I was in the third-year of my engineering when COVID-19 started, colleges closed, and I returned to my hometown, stopping online classes as well. This was a golden opportunity for me to work full-time on open-source projects and focus more on my blogs. Although the COVID period was tough with many challenges in the family, I spent most of my time learning and experimenting with Android development, open-sourcing, blogging, etc.

As seen in the previous section, my all articles were tutorial-ish. I learnt about the concept of Dependency Injection and the Dagger framework. I noticed that in that period, there was a lot of fear about this concept around beginners. So I thought of writing an article that simplifies the concept of Dagger. Finally, I wrote an article in which I explained this DI as a concept by giving a very simple example and relating it to real-life scenarios.

After I published this, I received a lot of positive feedback, and many developers thanked me for writing it because they found it easy to understand the basics of Dependency Injection. This gave me a great sense of satisfaction and boosted my confidence, as it was a new type of article for me. So, I continued writing similar blogs.

Lockdown was ongoing, and I was in the last semester of my third year. Due to my blogs and open-source work, I got an internship opportunity at ScaleReal. The founder liked that I wrote blogs. One day, we were discussing it, and he asked me if we could implement regular blogging practices at ScaleReal and motivate other employees to contribute as well. He asked me to lead it, and I accepted. I created a Medium publication of ScaleReal and became its maintainer and editor. I started submitting all my future blogs to that publication. Over time, many others also began contributing, which boosted ScaleReal's reach significantly! 😄. I used to review every blog, which helped me gain valuable experience in blog reviewing.

During the lockdown, I wanted to encourage blogging among my friends and college students, so I used what I learned from ScaleReal’s Medium publication. Around that time, I had already initiated a Developer's Club at my college (before COVID). Then I launched a Medium publication called DevClub DYPCOE. I encouraged others to write blogs for this publication. Later that DevClub got migrated into GDSC (Google Developers Student Club). It was really a helpful initiative as many students contributed and published good blogs to that publication. It was good to see that.

🤔 That one opinionated blog

I was feeling confident in development and began forming opinions about different concepts. While reading the release notes of Kotlin Coroutines, I discovered an API called StateFlow. By looking at it, it looked like an advanced version of LiveData to me. Till that time, it was not mentioned anywhere whether it’s gonna replace LiveData or not. I wrote a simple blog explaining how the StateFlow API could be used instead of LiveData in Android. Since I wasn't sure if it was truly a replacement, I added a question mark "?" at the end of the title. The title of that blog became: “🌊 StateFlow, end of LiveData?”

The response was incredible! The blog received around 2K+ reads in one night. Even people from Google reacted to it. It became so popular that some other bloggers copied the title and parts of the content 🤦🏻. My first opinionated blog was a success, confidence++. What could boost confidence more than that? 😄. So far in the Android-related blogs of mine, this one has the highest views on the medium.com.

📐 Diving deeper into the context

Later, I began writing about under-the-hood topics, such as how certain things work internally, and deeper concepts of Android and Kotlin. I started exploring Jetpack Compose and wrote about it as well. I also wrote about architecture best practices and created a series of articles on how to use Kotlin language features effectively. The response was quite positive.I was also working on open-source projects alongside my writing. Whenever I learned something new, I would write about it in detail.

In 2021, I became the youngest Google Developer Expert for Android in India. That was huge for me!

Meanwhile, I joined Paytm and became a Senior Android Engineer. As we adopted Jetpack Compose, I encountered new challenges and learned something new about APIs every day. My experience at Paytm taught me a lot, and many of my later blog posts were inspired by the challenges we faced there.

So, blogging has helped me a lot in my career!

I continued writing blogs, and now you're reading my 51st blog here! Do you think it was always smooth? Now let me share the dilemmas and challenges that I faced as well.

📖 English

Until 2021, I wasn't very good at English (and maybe I'm still not). My general communication skills were poor. I only understood tech concepts and could write about them, but I made a lot of grammatical mistakes. If you read my early blogs, you'll notice this and easily find many English-related errors. This caused me a lot of anxiety when I was about to hit the "Publish" button for my first blog post. I used to think, "What will people think if they see my writing?" and "How will they judge me?". However, I pressed that button for the first time and continued to do so many more times. My writing was very simple; I never used complicated words in any of my blogs. I avoided fancy English words and complex language. It was straightforward enough for any beginner to understand. But still, I was not so confident about my writing style and one day, a developer from community sent me a message on Twitter (now X). He mentioned that he likes whatever I like, then he wrote this:

I was surprised after reading this. That day, I learned that we often overthink before taking action. Stop overthinking and just go for it! In my case, it was "English"; for others, it might be something else. So my advice is to ignore the negative thoughts and focus on positive actions. This can not only boost your confidence but also help others. After my first few blogs, I started using Grammarly, which helped me identify common English mistakes in my writing. In today's world, LLMs can also help refine your sentences effectively.

😨 Criticism

Everything was going well while I was writing simple blog posts. It was all positive and boosted my confidence. However, things started to change when I began writing opinionated posts and posts related to architecture. Architecture is a topic that often sparks debate, and it's natural for developers to have different opinions. So whenever I wrote articles related to architecture or engineering best practices, I’ve been always criticized for them. But that doesn't mean I've never received good reviews on it. Opinions are always mixed on such topics. Another thing is that I used to include a lot of emojis in my blog posts, which led to some criticism, mostly on Reddit. Here's a glimpse of the criticism on Reddit:

Today's world has many negative people who do nothing themselves but are always ready to criticize. We always encounter both types of people: positive and negative. So, don't just focus on the negativity. On Reddit, most comments were about my use of emojis. However, on a personal level, I once received feedback from one of my connections who actually liked how I use emojis in my blogs, saying it feels attractive. So, in my opinion, there's no perfect or wrong way here 🤷🏻‍♂️.

Many times, I've also engaged in tech debates on Twitter, LinkedIn, and Reddit about various topics, but always in a healthy way (regardless of the other person's tone 😂). But criticism is not always harmful; it can be constructive too. If I ever made a mistake, I accepted it and corrected it in my blog before it could mislead any readers. It all depends on the author's attitude towards handling criticism. Once, I wrote an article and accidentally attached the wrong code snippet from a GitHub gist. I found out about it 30 minutes after posting, thanks to a comment on Reddit, and I quickly fixed it. I learned to take such feedback positively, which ultimately helped me become a better version of myself day by day. But I also learned to ignore some comments because not all of them are helpful. Some comments are just nonsense and won't benefit anyone, neither you nor the readers. So you should know what to take and what to ignore otherwise it can impact you a lot.

🔍 Learning - Getting post reviewed

Later on, I started having my blog posts reviewed by my tech-savvy friends and colleagues. Sometimes, when I wrote in-depth about a specific concept, I reached out to experts in that field from the community for help with reviewing and proofreading the blog. I always mentioned them at the bottom of my blog. Occasionally, I even sought the help of Google DevRel Engineers to get feedback on some opinionated blogs to ensure the intention was clear. This is the best way to feel confident before publishing a blog that might be sensitive. It's a really good habit I've developed, and I highly recommend it to anyone starting their blogging journey!

📈 Self promotion is important!

Once you hit "Publish," your work isn't done! I always shared my posts on Twitter, LinkedIn, Facebook, Reddit, Hackernews, as well as on community Slack channels like Kotlinlang. Newsletters like AndroidWeekly.net and KotlinWeekly.net are fantastic for reaching the right readers. Every Sunday, when my blogs were featured in these newsletters, I noticed a spike in viewers on the analytics graph. It just works well ✈️. Many people hesitate to share what they've created (I did too when I was a beginner, but I learned by watching others). But you have to do it. If you don’t, who else will? When you share your work, there will come a time when others start sharing your blog links on their feeds if it’s really a good quality work. Over time, Google search became my top source of organic referrals for my blogs (Thanks to the SEO of Medium and Hashnode so far).

📚 Keep learning

Technology is vast, and staying updated is crucial, especially if you want to continue blogging for the long term. Blogging itself is a learning experience. Even after about five years, I still feel like a beginner in writing blogs. I admit I'm still trying to improve and learn good blogging practices. I read other blogs to learn from them. I read official tech blogs, blogs by famous developers, company blogs, and my friends' blogs, which teach me a lot about technical writing. I believe there's no limit to learning, and it will always continue. So, keep learning!

🎉 Celebrating a small milestone

As a content creator, celebrating a small milestone not only releases dopamine for us but can also inspire others. So, don't hesitate to share your achievements or small wins too. Through this post, I'm absolutely thrilled to share that I've reached a total of ~605K views for my blogs since I started! It's such an amazing feeling to know that what I've written has reached half a million screens! 🎉. But of course, this is not done yet, and there is much more to come in the future. I’m really excited to see what comes next for me in this journey.

🎬 Wrapping up this post

So, that's been my blogging journey so far, and I'm really enjoying it. Thanks to the amazing tech community, especially the Android and Kotlin communities, the readers who supported me, my friends, tech enthusiasts, and the editors of the publications who helped review some of my posts ❤️.

I'm really excited to keep blogging about tech and to improve a little each day.

I hope this article encourages anyone who isn't confident enough to hit that "Publish" button right now. I would just say, hit "Publish" and go with the flow!

If you notice, I end every blog with this line 😄👇🏻

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

💁🏻 Context

Last week, I published a blog “Skipping the composition of intermediate composables“ that sparked some controversial opinions and comments across Twitter and Reddit. This prompted me to write a post discussing the benchmarking analysis between the two approaches. So, if you’re reading this post directly, I recommend you read my previous blog post first and then continue from here.

🫴🏻 Let’s start

I found the following comment on Reddit, and it gave me an idea for an application where UI updates happen frequently across multiple components.

I whipped up a quick prototype for a screen that shows the stock market. It includes basic stuff like market indices, an overview of investments, and holdings in a scrolling list. Here's what it looks like:

So, in this post, I won't dive into the details of the Compose implementation. Instead, I'll give you a quick overview of what the Compose tree looks like with the graphic below.

Since this is just a sample app pretending to be like a real app, I added fixed data that changes randomly at intervals. For example, market indices update every 300ms, the investment summary updates every 250ms, and the holdings list updates every 500ms. This means there will be a total of 9-10 data updates per second for the UI.

🧑🏻‍💻 Implementation variants

As you already might know the implementation variants (if you’ve read the previous blog), we have named them as “Before” and “After”.

Before:

Direct state model propagation through the composable functions. For implementation detail, refer to the branch: main.

After:

State model propagation through the Kotlin Lambda function references through the composable functions. For implementation detail, refer to the branch: lambda. Can also refer to this PR to have a look on the changes.

This is how the change looks between both the variants:

Before running the benchmarks, I ensured that the composable functions of both branches are stable and that all restartable functions can be skipped with the help of compose compiler report.

📐 Benchmark

To benchmark this, let's use macrobenchmark. For our purpose, it's straightforward: we just need to run the benchmark for a certain period, and that's it. So, in our case, let's run this benchmark for 10 seconds. We’ll perform 10 iterations of this benchmark on the app to get the aggregated data and we want to track the following metrics:

• FrameTimingMetric: This will be useful to know the amount of time the frame takes to be produced on the CPU on both the UI thread and the RenderThread.

• FrameTimingGfxInfoMetric: It’s legacy than above metric but this gives the insights on the janks via dumpsys gfxinfo.

• MemoryUsageMetric: We’ll use this to check memory consumption. Only for HeapSize and GPU size and keeping mode as Mode.Max which will give us the info about maximum memory usage observed during the benchmark.

So, benchmark test looks as follows:

@RunWith(AndroidJUnit4::class)
class StockScreenBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = "com.example.stockexample",
        metrics = listOf(
            FrameTimingMetric(),
            FrameTimingGfxInfoMetric(),
            MemoryCountersMetric(),
            MemoryUsageMetric(
                mode = MemoryUsageMetric.Mode.Max,
                subMetrics = listOf(
                    MemoryUsageMetric.SubMetric.HeapSize,
                    MemoryUsageMetric.SubMetric.Gpu
                )
            )
        ),
        iterations = 10,
        startupMode = StartupMode.COLD
    ) {
        pressHome()
        startActivityAndWait()

        Thread.sleep(10000)
    }
}

That’s it!

Also, as per the best practices, we are going to run these benchmark tests obviously on the release equivalent build having R8 enabled for optimization but by disabling obfuscation (as benchmarking needs it)

Now just run these benchmarks on variety of the devices and analyse the results. I ran these benchmarks on 3 devices on total out of which 2 were physical devices and last one was an emulator.

Why 3 devices? because I was unable to believe the results, so I decided to run these on different devices.

Cool, let’s see the analysis after performing the benchmarks on the “Before” and “After” variants.

🧐 Analysis

So, first off, I kicked things off by running benchmark tests on the super low-end phone I have, which has just 2 GB of RAM. I wasn’t expecting much from these benchmark tests and guess what? Here are the results!

I couldn't believe these results! So, I ran a second round of benchmark tests on the same device for both variants, and the results from Round 2 finally gave me some relief:

Surprisingly, when comparing the lambda-based approach with the direct state approach, there was a huge reduction in the UI jank percentage by 30-33%! And not only that, but there was a reduction in maximum heap memory consumption by 800 KB to 2134 KB 🤯 (this is 10 iterations’ data and that too with running benchmark tests twice). Also, at the 99th percentile, negative results were observed.

Then I decided to run these benchmarks on another device, but I didn't have one with me. That's when I remembered that Firebase Test Lab devices are now accessible through Android Studio. There are a variety of devices available there, just like real devices in the cloud. This opened up exciting possibilities for further testing!

I found a device: Moto G20, which runs on Android 11 and has 4 GB of RAM. So, I ran these tests on that device, and here are the results:

A similar trend was observed here too! There were reductions in both the jank percentages, frame time at 99th percentile and the maximum heap memory consumption.

Then I ran the third test on the Android Emulator (Pixel 8a - Android 14):

On the emulator, according to the frame metrics, there were no janks. However, memory usage remained consistent, with the minimum, median, and maximum values all showing reduction of heap memory consumption by around 2400 KB 🧐.

UPDATE:

After this blog was published, on X we had a discussion about Full R8 mode and till above section’s benchmark results, Full R8 mode wasn’t enabled for the app, so I performed benchmark tests again on the same low-end device twice to confirm the benchmark results on the Full R8 mode and here was the result:

Round 1 (Full R8 Mode enabled):

Round 2 (Full R8 Mode enabled):

After turning on Full R8 mode, the delta for frames actually shrinked but still it’s on green side with lambdas 😄 and memory heap size usage was still the same even after R8 optimizations.

After running 6 rounds of benchmark tests on 3 different devices, I finally gained some confidence! 😃. Here are some key takeaways:

If you want to explore this project or run benchmarks, take a look at this repository.

🔍 Conclusion?

Using lambda-based state is actually improving the runtime performance across low-end devices and actually saving the heap memory by around 2000 KB even in such a sample application, so I think lambda-based states are really useful in the scenarios in which nested sub-components change really very frequently in the application.

What is causing heap memory saving?

When a function is called, memory is allocated for the function's local variables, parameters, and return value. Additionally, if the function creates new objects or data structures, these will also consume heap memory. The impact on heap memory depends on the complexity of the function and the amount of data it processes or generates.

As you might have learnt from the previous blog that even if compose compiler skips the re-composition of the UI, it’s still invoking the functions and actually performs lot of operations and also checks the equality of the state models every time the state parameters are changed. So maybe that has some cost associated with it, maybe when data changes so fast, there are so many unnecessary invocations are happening causing unnecessary memory allocation in the heap, maybe that’s what this lambda-based state approach is avoiding and that’s why we are seeing the advantages after using lambdas over direct states.

Learning?

For me, the takeaway was that using stateful lambdas doesn't really have any major downsides. In fact, it's super helpful in situations where data updates quickly and leading it to update on the UI. Plus, less janks and memory benefits observed as this approach works great on low-end devices too.

Awesome 🤩. I hope you've gained some valuable insights from this. If you enjoyed this write-up, please share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

Revising the officially recommended best practice

One of the best practices recommended officially is to defer the reads as long as possible and everyone might be familiar with this code snippet:

It explains that using offset() directly updates the value in the composition, causing recompositions whenever the value changes. However, if we use offset {}, a lambda-based modifier, it skips the composition phase entirely and goes directly to the layout phase. This improves overall performance because there is no recomposition.

Now this was about the modifier that changes the layout, but this knowledge can be applied to the composition as well.

Come to the point…

When we design a screen in Compose, it consists of components and sub-components. According to best practices, the screen is a stateful composable, and all components and sub-components within the screen should receive their state from the screen, making them stateless composables. Therefore, it is the screen's responsibility (actually taken from the ViewModel) to supply the data needed for the components.

In the real applications, this is actually very big. Sometimes, it’s more than 15-20 state parameters for a single screen in the real app. When any of the sub-component’s state gets changed, it flows from screen to the components in the journey.

Now let’s say from the above figure, if Component 2.2’s (C 2.2) state gets updated, then how compositions will occur? So, it’ll be as follows:

In this case, Screen and Component 2 won't be recomposed (unless they're unstable). Recomposition means their UI logic won't run, but some parts will still execute. Before recomposition, it checks if it can be skipped. To do this, part of the function runs. If it can be skipped, the UI logic won't run; otherwise, it will.

Understand this with this simple example:

See how the composable code looks like after the compilation (i.e. after reverse engineering)

Notice the yellow highlighted line that checks whether the composition can be skipped. Only then is Text() called; otherwise, it is not. However, this means some lightweight operations will still occur in the Content() composable even if the composition is skipped. This skipping is decided based on the equality of previous and next state i.e. equals() method of the state parameter types. Now let’s see this actual code which we’ll try to improve:

So have a look on the snippet:

In this example, we first create a UI model to represent the state of the UI Name and RemainingSeconds. Although it's a data class, I've intentionally implemented the equals() method and added logs there. Screen composable is a stateful composable that decreases remaining seconds value every 100ms. Also, do notice that we have added logging statements to each block ⬆️.

Now, this is how our other composable looks:

Overall, this is how our structure looks:

Now, we can run this. What do you think logs will be? 🧐. So logs will be like these:

 Content(Name(value=John Doe), RemainingSeconds(value=60))
 Detail(Name(value=John Doe))
 Timer(RemainingSeconds(value=60))
 -----------------
 RemainingSeconds#equals
! Screen$Column
! Name#equals})
 RemainingSeconds#equals
! Content(Name(value=John Doe), RemainingSeconds(value=59))
 Timer(RemainingSeconds(value=59))
-----------------
 RemainingSeconds#equals
! Screen$Column
! Name#equals})
 RemainingSeconds#equals
! Content(Name(value=John Doe), RemainingSeconds(value=58))
 Timer(RemainingSeconds(value=58))
 -----------------
 RemainingSeconds#equals
! Screen$Column
! Name#equals})
 RemainingSeconds#equals
! Content(Name(value=John Doe), RemainingSeconds(value=57))
 Timer(RemainingSeconds(value=57))
 -----------------

Now you can see that in our simple application, we are just updating remainingSeconds every 1000ms but still every time Screen$Column, Content() block is called (obviously we knew that) then equality of both Name and RemainingSeconds is checked and by compose compiler magic only Timer is recomposed and Detail is not recomposed (i.e. skipped).

If we get this remainingSeconds value via lambda, can it change this behaviour? Let’s try. So quickly making changes in the code:

And run the app now and see the results ⬇️.

Screen$Column
Content(Name(value=John Doe), dev.shreyaspatil.composelambda.example.MainActivityKt$$ExternalSyntheticLambda2@233875c)
Detail(Name(value=John Doe))
Timer(60)
-----------------
RemainingSeconds#equals
Timer(59)
-----------------
RemainingSeconds#equals
Timer(58)
-----------------
RemainingSeconds#equals
Timer(57)
-----------------

This time, we are just seeing the equality check for RemainingSeconds and recomposition of Timer composable and this way little execution of Screen$Column and Detail composable functions is also skipped 🎉.

I believe we are not making any major improvements here, but we are saving a small amount of code execution time. This optimization can be particularly useful for screens where a deeply nested component is updated frequently, such as for animation states or similar scenarios. In such cases, it can reduce the number of equality checks and the number of times composable functions are invoked.

Some examples could be:

Example 1: When a component is updated often, like a timer or a frequently changing list of data, based on the state produced by the ViewModel.

Example 2: When a component is performing animations on the UI, and its state comes from the screen or ViewModel.

Additionally, this approach can be beneficial when intermediate composables are not marked as stable by the Compose compiler, allowing them to be skipped. Ultimately, decisions like these should be made based on the specific needs of the use case, as the Compose compiler already does an excellent job of skipping unnecessary recompositions. By carefully considering when to apply these optimizations, developers can ensure their applications run efficiently without unnecessary overhead.

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

Have you ever seen or declared Exceptions as object in Kotlin? Something like this:

object NoConnectivityException : Exception("No internet connectivity!")
object ResourceNotFoundException : Exception("Blah Blah Blah!")

Can you think what it can lead to? 🤔

Let’s understand it with a simple example. Have a look at the following snippet:

/**
 * Represents a network failure
 */
object NoConnectivityException : Exception("No internet connectivity!")

class Repository {
    fun getUserData(): Result<String> = runCatching {
        // Imagine user fetching operation here and 
        // it fails due to connectivity issue!
        throw NoConnectivityException
    }

    fun getAppData(): Result<String> = runCatching {
        // Imagine some data fetching operation here and 
        // it fails due to connectivity issue!
        throw NoConnectivityException
    }
}

Here, we have declared NoConnectivityException as an object and both the repository methods throw that Exception when these methods are called.

Then let’s simulate a real app flow:

val repository = Repository()

fun main() {
    val userDataResult = repository.getUserData()

    // << Few Moments Later in the real app >>

    val appDataResult = repository.getAppData()
    appDataResult.exceptionOrNull()?.printStackTrace()
}

So we want to print the stack trace if an error has occurred while getting the app data via getAppData() method. Now, can you guess what would be the output of this🌚? Here you go ▶️

Wrong stack trace for the wrong method! 😏This was expected because object creates a singleton instance of class lazily when it’s accessed for the first time. In the above sample, we called the method getUserData() before getAppData() and inside getUserData() method when throw NoConnectivityException was executed, the instance was created and kept forever. Next time when getAppData() throws the Exception, it’s throwing an Exception which was earlier created by getUserData() method 🤷🏻‍♂️.

Now imagine what would happen if it's a critical exception that gets logged into your app's dashboard (like 🔥Crashlytics or any other tool). It could mislead developers 🌚.

Ideally, Exception instances shouldn’t be singletons! If some Exceptions are only used internally to represent state or info that won't be monitored at scale, it might be okay to make them singletons. In places where the stack trace is important and shouldn't be ignored, it can be dangerous🔴 for the app.

These little things can easily be overlooked, but they have a big impact overall. Make sure to handle exceptions safely in your app 👍🏻.

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

To do this, the Compose compiler report helps you check the status of a Composable function, whether it's a restartable function or a skippable function. The report includes statistics of composable functions based on various parameters, details of classes, and specifics of a composable function (which is our main focus).

After following the steps mentioned here for generating a report, the report of composable functions looks like this (this is a sample report) ⬇️.

This text file contains all the information about the composable functions in the module. It shows whether each function is restartable, skippable, or inline. Additionally, it includes details about each parameter of the function and its stability.

Now imagine an application built entirely with Jetpack Compose, containing many Composable functions. How can a developer look at this report and check what’s working well and what’s not in their project? Since this generates reports in json, csv, and txt files, they are not easily traceable for developers. Additionally, the reports on Composable functions and classes become large and difficult to review. It’s quite tedious, isn't it?

💡Solution

I've developed a utility (Gradle plugin as well as CLI) that you can simply apply to your module. That's all you need to do, and the plugin will handle the rest, helping you focus on the areas that need your attention. In this post, let's focus on the usage of the Gradle plugin which is super easy to plug and play.

This tool parses the reports and metrics generated by the Compose compiler and converts them into an HTML page. It intelligently highlights problematic and non-problematic composable functions and classes, allowing you to focus on the actual issues in your Compose implementation.

To apply the plugin, add the entry of the plugin to your module's Gradle file:

plugins {
  id("dev.shreyaspatil.compose-compiler-report-generator") version "1.3.1"
}

After syncing the project, you'll see tasks will be generated as per the variants and build types of your project. Example:

To generate the report, run the Gradle task (or directly run the task from the tasks pane available on the right side of IDE). Example:

./gradlew :app:releaseComposeCompilerHtmlReport

After the task runs successfully, you'll see the output in the console with the details of the report in HTML format:

Compose Compiler report is generated: .../noty-android/app/composeapp/build/compose_report/index.html

BUILD SUCCESSFUL in 58s
1 actionable task: 1 executed

You can also view a sample report here to get a glimpse of what the report looks like..

The report will have four sections:

1. Brief Statistics

Parses metrics from .json file and represents in tabular format.

2. Detailed Statistics

Generates report from .csv file and represents in tabular format. It includes package-wise details of functions and their statuses.

3. Composable Report

Parses the -composables.txt file, separates composables with and without issues, and highlights the associated problems. This is our main focus. With this, we can separate the composable report based on stability and instability, making it easier to find issues. It highlights the unstable parameters for better focus 👇🏻.

4. Class report

Parses -classes.txt file and separates stable and unstable classes out of it and properly highlights issues associated with them.

Cool 😎, what more could a developer need since it helps highlight the issues? After reading the report, developers can focus on fixing the problems instead of spending too much time on the raw report.

Not only that, but the plugin is highly customizable. If you want to focus only on the Composable function part, specifically the unstable composable functions, you can configure the plugin to only have this info in the report.

For example: You can configure as follows to only include the unstable composable functions in the report at the specified directory.

htmlComposeCompilerReport {
    // ONLY show unstable composables in the report without stats and classes
    showOnlyUnstableComposables.set(true)

    // Output directory where report will be generated
    outputDirectory.set(layout.buildDirectory.dir("custom_dir").get().asFile) // Default: module/buildDir/compose_report
}

And then, this is how the report would look like ⬇️.

Only Composables with issues. Isn't this nice? 😎

You can explore the plugin and its usage further by visiting the official documentation. You can also see how to use the CLI. If you want to extend this for your use cases, it's also available in the form of a library as a maven artifact.

View sample app with implementation of this plugin:

Currently, this plugin does not support KMP's Compose multiplatform, but it will be added soon. If you're interested in solving this, feel free to contribute.

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

📚Resources

• Official docs - Compose Report to HTML

• GitHub - Compoe Report to HTML

I'm the maintainer of a library - Capturable, that helps you to convert composable content into a Bitmap image easily. In the very first release of it, as there was no dedicated API from compose, I used to wrap composable content inside a ComposeView and then draw a View's Canvas into a Bitmap. Later in Compose 1.6.x, the API was added by which we can redirect rendering into android.graphics.Picture, which can then be used to create a Bitmap.

The official documentation has a guide for capturing the composable content into a Bitmap as follows OR see this snippet ⬇️

As this API is more efficient than my previous approach of capturing content, I adopted it in Capturable v2.0.0.

Now it's an interesting part 😁 because I started seeing issues with this and someone also opened a similar issue on GitHub which proved that the above approach is not fulfilling all the use cases. Let's understand in the detail.

Issue 🧐

Let's say we have a screen on which content can be changed at any time in the runtime i.e. stateful content then this issue was easily reproducible. For example, you want to capture content having a network image (which will be loaded in future), or a simple count-down like continuously changing screen, etc.

Let's build a simple continuous counter and try to add a capturing modifier to it. Here is what the code would look like.

@Composable
private fun Counter() {
    var count by remember { mutableIntStateOf(0) }
    Column(
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Text(text = "Count:")
        Text(text = "$count", style = MaterialTheme.typography.h4)
    }

    LaunchedEffect(key1 = Unit) {
        while (true) {
            delay(1000)
            count++
        }
    }
}

In the capturing UI, we'll put a simple button below this counter with the label "Capture" and once the user clicks on that button, the current state of the counter should be captured and will be displayed below the button. Code be like ⬇️

@Composable
fun CounterCapture() {
    val coroutineScope = rememberCoroutineScope()
    val picture = remember { Picture() }

    var imageBitmap by remember { mutableStateOf<ImageBitmap?>(null) }

    Column {
        // Content to be captured ⬇️
        Box(
            modifier = Modifier
                .drawWithCache {
                    val width = this.size.width.toInt()
                    val height = this.size.height.toInt()

                    onDrawWithContent {
                        val pictureCanvas =
                            androidx.compose.ui.graphics.Canvas(
                                picture.beginRecording(
                                    width,
                                    height
                                )
                            )
                        // requires at least 1.6.0-alpha01+
                        draw(this, this.layoutDirection, pictureCanvas, this.size) {
                            this@onDrawWithContent.drawContent()
                        }
                        picture.endRecording()

                        drawIntoCanvas { canvas -> canvas.nativeCanvas.drawPicture(picture) }
                    }
                }
        ) {
            Counter()
        }

        // Capture button
        Button(
            onClick = {
                coroutineScope.launch {
                    imageBitmap = createBitmapFromPicture(picture).asImageBitmap()
                }
            }
        ) {
            Text("Capture")
        }

        Divider()

        // Captured Image
        imageBitmap?.let {
            Text(
                text = "Captured Image",
                modifier = Modifier.padding(8.dp),
                style = MaterialTheme.typography.h6
            )

            Image(
                bitmap = it,
                contentDescription = "Captured Image"
            )
        }
    }
}

But when we run this, we run into an issue 😏. See the issue below.

Whoa! 😮. It doesn't only break the capturing but also breaks the UI state of a component. Because the counter is not working properly with this.

If we remove drawWithCache {} Modifier from the above code, then there's no issue as such and the counter will work without any issues.

Understanding the drawWithCache logic 🤔

Refer to this for step by step understanding of a flow ⬇️.

The code establishes a caching mechanism using drawWithCache. It creates a temporary picture object to render the composable's content. Once the content is drawn onto the picture, it's then transferred to the main canvas for final display. This approach avoids redundant calculations and re-drawing if the size and relevant state haven't changed, leading to improved performance for complex or frequently updated composables.

Spotting the issue 🔬

As we can understand from the logic above, it captures the content from Canvas into a Picture and later it draws the same picture on the canvas (which is going to be displayed on the UI). But this is unaware of recompositions (UI updates). So we need a solution in such a way that we should be able to capture the content with its current state without hampering the UI updates of the content.

Earlier, I faced the similar issue which was reported on Google's issue-tracker. In this issue was with image loading from a network and capturing content of it.

Solution 💡

Since this issue was also affecting my library Capturable, I solved it using the recently introduced API of Modifier from the latest release of Jetpack Compose. I leveraged Modifier.Node API for this.

Modifier.Nodeis a lower level API for creating modifiers in Compose. It is the same API that Compose implements its own modifiers in and is the most performant way to create custom modifiers.

~ Official Documentation

So I created a custom Modifier node as follows:

class CapturableModifierNode(...) : DelegatingNode(), DelegatableNode {
    // Other logic

    private suspend fun getCurrentContentAsPicture(): Picture {
        return Picture().apply { drawCanvasIntoPicture(this) }
    }

    /**
     * Draws the current content into the provided [picture]
     */
    private suspend fun drawCanvasIntoPicture(picture: Picture) {
        // CompletableDeferred to wait until picture is drawn from the Canvas content
        val pictureDrawn = CompletableDeferred<Unit>()

        // Delegate the task to draw the content into the picture
        val delegatedNode = delegate(
            CacheDrawModifierNode {
                val width = this.size.width.toInt()
                val height = this.size.height.toInt()

                onDrawWithContent {
                    val pictureCanvas = Canvas(picture.beginRecording(width, height))

                    draw(this, this.layoutDirection, pictureCanvas, this.size) {
                        this@onDrawWithContent.drawContent()
                    }
                    picture.endRecording()

                    drawIntoCanvas { canvas ->
                        canvas.nativeCanvas.drawPicture(picture)

                        // Notify that picture is drawn
                        pictureDrawn.complete(Unit)
                    }
                }
            }
        )
        // Wait until picture is drawn
        pictureDrawn.await()

        // As task is accomplished, remove the delegation of node to prevent draw operations on UI
        // updates or recompositions.
        undelegate(delegatedNode)
    }
}

In this, CapturableModifierNode inherits from two interfaces: DelegatingNode and DelegatableNode, suggesting it can delegate drawing tasks to other nodes while also being delegatable itself (as we want to re-use theCacheDrawModifierNode).

You can see that we are using the same code as we saw earlier inside of CacheDrawModifierNode.

But see the difference that this Modifier only gets attached when capturing of content is requested. drawCanvasIntoPicture is a suspend method which can be called when capturing is requested. At the time of a request (call of the method), the logic of capturing is called via delegate() method. Then we wait until the picture is drawn by observing pictureDrawn (CompletableDeferred<Unit>). The wait is completed after the picture is drawn on the UI from drawIntoCanvas {} lambda. After the picture is drawn, the same node is removed via undelegate() method that removes the delegated CacheDrawModifierNode to prevent unnecessary work.

This can help us solve UI state issues while capturing the content. Also, it ensures that content is only captured when it's requested. So our logic of drawing is only executed at the time of capturing the request and instantly undelegated after it.

After this, let's expose the Modifier element

fun Modifier.capturable(controller: CaptureController): Modifier {
    return this then CapturableModifierNodeElement(controller)
}

private data class CapturableModifierNodeElement(
    private val controller: CaptureController
) : ModifierNodeElement<CapturableModifierNode>() {
    override fun create(): CapturableModifierNode {
        return CapturableModifierNode(controller)
    }
    // ...
}

Since this has been part of my library Capturable, with it, it can be captured as follows:

@Composable
fun CounterCapture() {
    val coroutineScope = rememberCoroutineScope()
    val captureController = rememberCaptureController()

    var imageBitmap by remember { mutableStateOf<ImageBitmap?>(null) }

    Column {
        // Content to be captured ⬇️
        Box(Modifier.capturable(captureController)) {
            Counter()
        }

        // Capture button
        Button(
            onClick = {
                coroutineScope.launch {
                    imageBitmap = captureController.captureAsync().await().
                }
            }
        ) {
            Text("Capture")
        }
    }
}

All done! Let's see how it works

Outcome ▶️

🚀 Issue fixed, composable content captured 🎯. Mission accomplished! 😀

You can see this pull request as a reference for code changes I did for my library.

That's it!

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

See also

Before

In the View system, the API for Receiving rich content was already there. But there was no such straightforward API support for compose.

Imagine we are building a chat app in which users can select GIFs or images from Keyboard and these media will be directly sent on chat.

Unfortunately, while using Compose components' TextField APIs, this was not supported, and if a user tried to insert a media, a toast used shown as below:

I tried to achieve this a lot with various approaches like wrapping TextField composable inside ComposeView or AbstractComposeView and trying to establish a connection between the text field and the keyboard with onCreateInputConnection, but no luck!

The feature request was there on the issues-tracker for a long time but there was no workaround for this. The only thing that worked was wrapping View-basedEditTextinsideAndroidView but it was not gonna help much.

Now 🎉

Finally, after a long wait, In Jetpack Compose 1.7.x there is an API that can support rich media content handling.

A new Modifier has been introduced for this: Modifier.receiveContent(). In this modifier, we can specify what kind of content we wish to handle (for example: Image, plain text, HTML, or anything else). A variety of content could be received from another app through Drag-and-Drop, Copy/Paste, or from the Software Keyboard.

Let's see how can we receive content from a keyboard (for our chat app use case).

Code 🧑🏻‍💻

You might have used BasicTextField or TextField. A new foundation API has been introduced for the text field: BasicTextField2. This has been improvised and created to replace the existing BasicTextField and is currently an experimental API to use.

So instead of Text or BasicTextField, use BasicTextField2 and use the modifier receiveContent along with it to get the rich content from keyboard input:

In modifier receiveContent, first, you need to specify what type of content you want to get. MediaType holds the MIME type. As needed, you can specify your MIME type. Second is lambda which gets invoked when content is selected (in this case, content will be selected from the keyboard). Lambda has a parameter TransferableContent that contain data, metadata, etc.

That's it! Once you handle the media retrieval through Uri, you're good to go 🎉.

How simple it was, wasn't it? 😀

You can explore receiveContent Modifier for other use cases like drag-and-drop, or from clipboard, or getting different types of files, etc.

You can refer to the following sample app project to try this out: https://github.com/PatilShreyas/ComposeKeyboardMediaInput

Final notes

As commented here, there are no plans from official teams to support this BasicTextField because it's going to be deprecated and replaced with BasicTextField2. So if you need this to fulfill a use case, you anyway have to migrate to the new text field composable.

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

📚References

• https://android-review.googlesource.com/c/platform/frameworks/support/+/2909937

• https://github.com/PatilShreyas/ComposeKeyboardMediaInput

Why

Before jumping on the topic, let's understand the need.

You can consider any use case in which Flow produces a lot of data within a small period that can't even skipped. Imagine we are developing an application in which we heavily log analytics. For example, we store logs when the user clicks on the button, user interactions, scrolls, etc. It means we can assume: that whenever a user is doing something, we can say 5-6 analytic events per 2-3 seconds need to be persisted in the database (or need to be sent on the network).

Imagine we are solving the use case like above with the Flow APIs. In such cases, if we are doing operations like DB persistence or network calls frequently, then it can block our business logic for a little time. For example, presentational data saving/fetching should be prioritized over saving/fetching analytical data for any app. These DB calls or network operations happen on reserved thread pools that get busy doing unimportant things. In such cases, if we could get the data in the chunks after fixed intervals then that would solve such issues. Let's see how can we achieve that 😎.

What's the advantage of collecting Flow items in the chunks?

When a lot of data is produced within a short period, then processing each data individually becomes costly because a thread has to process it. But, if we start processing the same data in bulk, it's not as costly as it is for an individual item.

Example: Bulk insertion of items in an SQLite table is always better than inserting each item individually.

Creating an operator on the Flow - .chunked()

Have you ever tried chunked() on the Collections?

It creates a chunk (sublist) of items based on the chunk size provided. Similarly, we have to collect the Flow items in chunks. But in our use case, we want to receive the chunks based on the time intervals, not based on the size.

The API interface for this should look like this... ⬇️

val eventsFlow: Flow<Event> = // ...

eventsFlow
    .chunked(2.seconds)
    .collect { events: List<Event> ->
        // Do something with `events`
    }

So after chunked(Duration), Flow type should be changed to Flow<List<T>>. Let's start the implementation.

Design the "flow" operator function

Let's create a class first for extending the behaviour of a Flow. We call it TimeChunkedFlow which extends the type Flow<List<T>>

Now our requirement is: that we have to collect the items from upstream flow and have to emit all the items in chunks that are collected from it after the specified duration.

So, this is what basic logic looks like:

But there is a problem 🤔. Whenever the upstream Flow is ended, this TimeChunkedFlow will continue emitting [] (empty list) and will start behaving like a hot♨️ flow even if a cold🧊flow is used. It's because we have launched a child coroutine and collected its job in emitterJob and it's never canceled so collect() is never unblocked.

But wait! If we cancel it directly at the end, it will never emit the last chunk of the Flow (because the coroutine job might be cancelled before emitting the last chunked items in the collector). So we have to complete the execution of the job carefully by emitting the last chunk as well.

For this, we'll introduce a flag isFlowCompleted that will be helpful for us to break the loop whenever the flow completes ⬇️.

Again, there is an issue of race condition 🏃🏻‍♂️. If due to its async nature, if list gets accessed among various threads and read/modified without safety then there is a risk of data loss or data duplication. To solve this, we can use Mutex as a lock to safely perform the operations on the values list so that it won't get accidental reads/writes. We can quickly update our logic with Mutex's implementation:

Nice! It's ready to use 🚀. Just create an operator function for easy chaining for the Flow type.

Let's try this! Creating a sample flow and let's try collecting the items in chunks👇🏻.

Whoa! We achieved it! We can get chunked data without losing it that too with specified intervals as we wanted 😃.

You can refer to the gist here for full implementation.

Just remember that if the upstream flow doesn't produce any item within the specified duration, an empty list [] will be emitted in the collector.

Note: Similarly, if you don't want chunked data by time but you want it by size, the implementation can be designed similarly. It's already in discussion on the GitHub issues

But, There's a catch! 🔴

If the Flow gets cancelled within the emission of the next chunk, then data will be lost for that specific intermediate chunk which was going to be emitted. It means the collector will never receive data of the last chunk if it's cancelled before collecting that. So use it wisely by knowing your use cases suitably. So there'll be always a problem with cancellable CoroutineScopes. If you want a workaround for it just for a certain use case, you can wait for cancellation and emit the remaining chunk in the collector as follows:

But this kind of implementation won't be safe to be used within UI use cases. Because, this way, the collector will get the last emission even if the flow is cancelled. So this is a kind of hack and not a recommended solution ❌.

So chunked() won't be useful for you if you don't want to lose the data in the cancellation scenarios.

Remember

This is not yet a standard library implementation and is still in discussion at Kotlinx.coroutines so consider this implementation as an experiment. If you find any issues in this, feel free to comment here or on the Gist. As per my usage, it has worked so well with cold and hot flows (like SharedFlow).

Awesome 🤩. I trust you've picked up some valuable insights from this. If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

Follow my channel on WhatsApp to get the latest updates straight to your WhatsApp inbox.

The issue 🐛

We are writing a small snippet of code as below. Do you see any issue here? 👇🏻

fun getData() = "SomeData"

class Example {
    val value1: Boolean = computeValue1()
    val value2: String = getData()

    fun computeValue1(): Boolean {
        return value2.isEmpty()
    }
}

fun main() {
    Example()
}

Understanding the snippet:

• There is a class Example having two fields

• Field value1 gets initialized by computeValue1() which makes computation based on value2's value

Whenever this snippet is run, you'll see a runtime exception like this 👇🏻

Strange! 🤯 no?

Even if fields are declared as non-nullable in Kotlin, if we are still getting NullPointerException then it's a serious issue if gets missed from a developer's eye or in the code review, isn't it?

Reason 🤔

In the snippet, whenever the code is executed and Example is instantiated, first of all value1 will be evaluated. But value1 has an indirect dependency on the value2 which is not even initialized at that moment causing NullPointerException.

If we remove the computeValue1() and directly replace the logic in the place of the initializer of value1() as in the snippet 👇🏻

class Example {
!   val value1: Boolean = value2.isEmpty()
    val value2: String = getData()

    // Method removed 
}

Here, in this case, we'll directly get a compile-time error 🔴 in IDE saying "Variable 'value2' must be initialized" as below 👇🏻

So it's safe in such cases ⬆️.

Also, if value2 is declared and initialized before the value1 then there's no issue. As seen in the change below.

+   val value2: String = getData()
    val value1: Boolean = computeValue1()
-   val value2: String = getData()

That's all!

Conclusion 💡

As observed, Kotlin will generate a compile-time error if you attempt direct initialization, but it may not catch the issue when there is an indirect dependency through a method call. This situation compromises Kotlin's guarantee of non-nullability for fields on the JVM, potentially leading to runtime crashes that can significantly disrupt the implementation.

To fix such scenarios, always make sure to verify the order of declaration of fields to avoid indirect dependency on the uninitialized field.

Awesome 🤩. I trust you've picked up some valuable insights into addressing inadvertent problems that can arise when working with Kotlin. These solutions can not only streamline your workflow but also alleviate potential confusion, ultimately saving you significant effort.

If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on X or visit my site to know more about me 😎.

Follow my channel on WhatsApp to get the latest updates straight to your WhatsApp inbox.

Knowing the issue 🐞

If you are using Jetpack compose on a regular basis and utilizing LazyList APIs then you might have faced this issue in your app. So Let's build a sample app to demonstrate the issue. At the moment, imagine that we are developing our application with Jetpack Compose 1.4.x APIs. In the sample app, we are simply showing a list in which items are added continuously after some intervals and when clicking on an item in the list, the details are displayed in detail at the bottom of the screen. See the below preview.

Now here's what the code of the List's implementation looks like. Inside of LazyColumn simply all notes are passed as a list and each Note is composed.

Now when the app is run and checked for the recompositions count in the Layout Inspector, here's a surprise 😮.

As you can see, each item in the list is getting recomposed when a new item is added to a list 🤯. For example, a total of 50 items are added to a list then all 50 Composable note items are recomposed when a new (51st) item is added to a list.

After getting such issues, the first thought which comes to mind is "Stability", right? We can quickly verify the stability of models and composable functions. See, all our composable functions are stable. (Verified with this plugin)

So what's the issue here? Let's understand

Getting the root cause of the issue

After facing the issue, got a chance to study and investigate this issue in detail and the learnings were interesting.

While experimenting with a lot of code changes, tried one change that fixed the issue. Just note a difference in implementation from the below snippet.

In the previous implementation, Modifier was exposed as a parameter from a Note composable so that list can add behavior to it. Click of an item was handled inside LazyColumn of NotesScreen composable. In the new implementation, instead of exposing a modifier, we have exposed a lambda that takes care of the execution of logic on click, and internally Modifier is handled inside Note composable only without exposing it outside.

Now, after this change, see the recompositions with this new logic.

Surprised🤯? With this small change, a list item never got recomposed again and it smartly skipped recomposing the items inside the list. Also, this is not the only solution. There are several variants of potential fixes:

• Remembering a modifier

    @Composable 
    fun NotesScreen(...) {
        // ...
        items(notes) { note ->
            val clickableModifier = remember(note) { 
               Modifier.clickable { /* Do something */ }
            }
            Note(note = note, modifier = clickableModifier)
        }
    }
  

• Using a singleton modifier (not usable in our case since we need a note)

    val clickableModifier = Modifier.clickable { /* Do something */ }
  
    @Composable
    fun NotesScreen(...) {
        // ...
        items(notes) { note ->
            Note(note = note, modifier = clickableModifier)
        }
    }
  

But again, the question is "Why it's making a difference?".

To understand more in detail, I even tried using Modifier.pointerInput with old implementation and performing clicks with onTap callback and found that the same issue is not happening with this modifier but only happening with clickable{} Modifier.

So it's not an issue with all Modifiers but only with clickable{} modifier. After checking the implementation of this modifier, we can see that clickable is a composed modifier which makes it different from another modifier.

What is composed Modifier?

Docs says:

Declare a just-in-time composition of a Modifier that will be composed for each element it modifies. composed may be used to implement stateful modifiers that have instance-specific state for each modified element, allowing the same Modifier instance to be safely reused for multiple elements while maintaining element-specific state.

You can see that composed takes a factory which is a @Composable lambda that returns a value. This lambda is executed when layout nodes are created. Composable functions/lambdas that return a value are not skippable and also not automatically remembered by Compose.

Whenever such a modifier is used directly inside the LazyListScope, all existing items are recomposed because a new instance of Modifier (with clickable{}) gets created which is not equal to the previous instance of the modifier. In short, every time the function is called, it'll behave like Modifier is changed and it'll cause recompositions.

It means, if any Modifier that uses composed{} under the hood is used, then it will cause extra recompositions of composable components, despite them having the correct stability. When directly used within LazyListScope, it affects badly because it's a point where each item is laid inside LazyColumn/LazyRow.

The solution is simple to use with LazyListScope

• Avoid using composed{} modifier directly in LazyListScope

• If there's any use case that you need to use Modifier in such place, then make sure that modifier is remembered.

But... how can we live with it further? 🤔

Definitely, this is a genuine issue and we can't just live with it. That's a reason why the Jetpack Compose team is refactoring Modifiers. In this talk @ Android Dev Summit 2022, Leland Richardson had already discussed the issue in detail and the performance issues with the usage of the composed{} modifier.

Also, in the recent release of Jetpack Compose (August 2023), the team has already improved significant performance with the Modifier refactoring and has promised to fix the issues with the Clickable modifier in future releases 👇🏻.

So in the end, it's great news that we can soon get rid of this issue in the upcoming versions of Compose with which we won't even need to worry about these scenarios and we won't need to tweak solutions as we did so far. Till the time, we can fix the issues as we discussed 😀.

Awesome 🤩. I hope you learned how can we fix the performance issues so far till the time full refactoring of the Modifiers is officially made done by the Jetpack Compose team.

If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on Twitter or visit my site to know more about me 😎.

Many thanks to Ben Trengrove for helping me understand this issue better and reviewing this blog post 😀.

📚References

• Compose Modifiers Deep dive

• Issue Tracker - Recomposition is not skipped if clickable modifier is used

What is a delay() ?

Everyone who has used coroutines might have used delay() method already. This is what official docs say about delay():

"Delays coroutine for a given time without blocking a thread and resumes it after a specified time."

Example: Perform Task-2 two seconds after performing Task-1

scope.launch {
    doTask1()
    delay(2000)
    doTask2()
}

But here are things to note about delay():

• It does not block the thread that it's running on

• Allows other coroutines to run (on the same thread)

• When the delay has expired, the coroutine will be resumed and will continue executing

Interesting! 🧐

Many developers compare delay() with Thread.sleep() method of Java. But actually, there's no comparison at all since they both exist for different use cases. They might look the same but they're different. Let's compare...

What's Thread.sleep() 😴 ?

This is Java's standard multi-threading API that "causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds"

"This method is generally used for making processor time available to the other threads of an application or other applications that might be running on a computer system"

If this is used in coroutines: It's a Blocking function means that the function blocks the thread that it is running on. This means that other coroutines cannot run until the blocking function has finished executing.

Now, to understand it in detail, let's compare sleep() and delay()

Comparing sleep() and delay()

Let's compare it with an example. Imagine we want to perform some tasks concurrently but only with a single thread. Just like in Android development, there's a Main-thread which is a single thread.

Take a look at the below snippets. In this, two coroutines are launched and a delay/sleep of 1000ms is applied.

Comparison:

• When both coroutines were launched:

  • With delay(), both coroutines were launched at same-second instant (05:48:58)

  • With sleep(), the Second coroutine was launched exactly after one second.

• When both coroutines finished:

  • With delay(), it took a total execution time of 1045ms

  • with sleep(), it took a total execution time of 2044ms

This brings us to conclude the same as we described initially that delay() just suspends the coroutine and allows the other coroutine to re-use the same thread whereas Thread.sleep() directly blocks the Thread for a specified duration.

Want to see a different superpower of a coroutine? Then just look at the snippet and case below:

Case: There is a Thread pool context of a Maximum of 2 threads. The first coroutine is launched, it does some work there, and then it adds a delay() of one second and after that delay, it does some work. Concurrent with the first coroutine, a second coroutine is launched which performs heavy tasks in such a way that a Thread will be spending most of its time executing that task.

Amazing! Before a delay, it was running on a Thread Duet-1. After a delay, it resumed on another thread, Duet-2. Why so? Since the other thread was busy performing heavy work in another launched coroutine, so it resumed on a different thread after a delay.

Interesting 🧐 , isn't it? That's the thing when Coroutine's docs say...

"Coroutines can suspend on one thread and resume on another thread."

Since we now know the powers of delay(), now let's understand how it works under the hood.

Dissecting delay() under the hood 🕵🏻‍♀️

Whenever we call a delay() method, it finds for a Delay's an implementation in the current Coroutine context and returns that.

public suspend fun delay(timeMillis: Long) {
    if (timeMillis <= 0) return // don't delay
    return suspendCancellableCoroutine sc@ { cont: CancellableContinuation<Unit> ->
        if (timeMillis < Long.MAX_VALUE) {
!           cont.context.delay.scheduleResumeAfterDelay(timeMillis, cont)
        }
    }
}

Delay is an interface which has support for methods which schedules the execution of the coroutine after some delay. The methods delay(), withTimeout() are backed by the implementation of this interface.

public interface Delay {
    /**
     * Schedules resume of a specified [continuation] after a specified delay [timeMillis].
     */
    public fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>)

    /**
     * Schedules invocation of a specified [block] after a specified delay [timeMillis].
     * The resulting [DisposableHandle] can be used to [dispose][DisposableHandle.dispose] of this invocation
     * request if it is not needed anymore.
     */
    public fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
        DefaultDelay.invokeOnTimeout(timeMillis, block, context)
}

Then this interface is implemented by the coroutine executor dispatchers. It provides freedom for dispatchers to implement this functionality as they want. For example, real dispatchers like IO, Default supports delay. Test dispatchers (used in unit testing) can control the delay as needed.

CoroutineDispatcher is also an abstract class. Dispatchers make use of core threading APIs in the implementation dispatchers. For example, in JVM, Dispatchers like Dispatchers.Default, Dispatchers.IO use implementation of core java.util.concurrent APIs like Executor. In Android, Dispatchers.Main makes use of Handler APIs. So if dispatchers want to support delaying, they also implement the Delay interface. The method scheduleResumeAfterDelay() resumes a continuation of a coroutine after a specified delay of milliseconds.

This is how ExecutorCoroutineDispatcherImpl implements the method.

override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
    (executor as? ScheduledExecutorService)?.scheduleBlock(
        ResumeUndispatchedRunnable(this, continuation),
        continuation.context,
        timeMillis
    )
    // Other implementation 
}

Thus, it just schedules a resumption of continuation with the help of schedule() method of ScheduledExecutorService.

Let's also take a look at Android's implementation of a Dispatcher (HandlerDispatcher).

override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
    val block = Runnable {
        with(continuation) { resumeUndispatched(Unit) }
    }
    handler.postDelayed(block, timeMillis.coerceAtMost(MAX_DELAY))
    // Other implementation 
}

Straightforward 😄. It just posts continuation runnable on the Handler with postDelayed() with delay. That's the reason calling a delay() doesn't block the thread.

Example: So when you're writing delayed business logic in a single thread context (Android's Main thread in this example), this is how it's treated under the hood (just for imagination).

Interesting 🤨, isn't it? So whenever you call delay() in Android, it just creates a nested callback chain of Handler#postDelayed(). The same goes for JVM with Executor APIs. Whereas, if you write the same logic with Thread.sleep(), it blocks that thread till that duration. So, delay() and sleep() are two different things that are not similar.

Awesome 🤩. That's the beauty of coroutines. It just skips the writing of callback hell for developers and manages it well internally in such a way that we could synchronously write asynchronous code!

I hope you got the idea about how exactly delay() works in the coroutine 😃.

If you like this write-up, do share it 😉, because...

"Sharing is Caring"

Thank you! 😄

Let's catch up on Twitter or visit my site to know more about me 😎.