<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by sandeep dhami on Medium]]></title>
        <description><![CDATA[Stories by sandeep dhami on Medium]]></description>
        <link>https://medium.com/@sandeep84397?source=rss-9b4604feeb7a------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*ubWHyd9Iyo2aVfQ8</url>
            <title>Stories by sandeep dhami on Medium</title>
            <link>https://medium.com/@sandeep84397?source=rss-9b4604feeb7a------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 14:23:18 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@sandeep84397/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[From Keystrokes to Bytecode: How Android Compiles Your Kotlin]]></title>
            <link>https://medium.com/@sandeep84397/from-keystrokes-to-bytecode-how-android-compiles-your-kotlin-d5b28dd4acea?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/d5b28dd4acea</guid>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[android-development]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Tue, 03 Nov 2026 05:24:16 GMT</pubDate>
            <atom:updated>2026-11-03T05:24:16.066Z</atom:updated>
            <content:encoded><![CDATA[<h4>Following one Kotlin file from the characters you type to the bytes ART runs</h4><h3>Every app starts as plain text</h3><p>When you press Run in Android Studio, your Kotlin file goes through about eight steps before a phone can run it, and not a single letter you typed survives the trip.</p><p>We write code every day, but most of us treat the build as a black box. Code goes in, an APK comes out, and somewhere in between there is a progress bar. I wanted to open that box and follow one small file all the way, from the characters on my screen to the bytes that Android Runtime (ART) finally executes.</p><p>So what does compilation actually mean? In simple words, compilation is translation. A compiler reads code written in a language humans understand, checks it for mistakes, and rewrites it in a language a machine understands. Think of translating a book from English to Hindi. You cannot translate word by word. First you must understand every sentence, then you write the meaning again in the new language. A compiler does exactly that.</p><p>On Android, this translation happens three times:</p><ol><li>Kotlin source becomes JVM bytecode (.class files) on your machine.</li><li>JVM bytecode becomes Dalvik bytecode (.dex files) on your machine.</li><li>Dex becomes real CPU machine code on the phone, done by ART.</li></ol><p>This article covers the first two hops, everything that happens on your laptop. It ends at the exact moment the APK is handed to the phone. The next article in this series picks up from there and covers runtime: how ART loads, interprets, JIT compiles and AOT compiles your code on the device.</p><h3>The file we will follow</h3><p>We will track one tiny file through every step. It is small on purpose, but each line triggers something interesting inside the compiler.</p><pre>// Greeting.kt<br>package com.sandeep.demo<br><br>data class User(val name: String)<br><br>fun greet(user: User?): String {<br>    val name = user?.name ?: &quot;guest&quot;<br>    return &quot;Hi $name&quot;<br>}<br><br>fun add(a: Int) = a + 1</pre><ul><li>data class User makes the compiler generate methods we never wrote.</li><li>user?.name ?: &quot;guest&quot; uses null safety and the Elvis operator, which do not exist in bytecode.</li><li>&quot;Hi $name&quot; is a string template, which also does not exist in bytecode.</li><li>add is the smallest possible function, so we can follow it all the way down to the exact bytes.</li></ul><h3>The big picture</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*anmOJcbKZHFfg1eh0Ph_qQ.png" /><figcaption>The compile time pipeline: from Greeting.kt to a signed APK</figcaption></figure><p>Steps 1 to 6 all happen inside kotlinc. Only step 6 writes bytes; everything before it is understanding and rewriting. Keep this map in mind as we walk through each box.</p><h3>Step 0: Gradle sets the stage</h3><p>Before the Kotlin compiler reads a single character, Gradle runs code generators and builds the R class, because your code depends on both.</p><p>When you press Run, Gradle builds a graph of tasks. For a debug build, the important ones run roughly in this order:</p><ol><li>KSP or kapt generates source code for annotation-based libraries like Hilt, Room and Moshi.</li><li>AAPT2 compiles your resources and generates the R class.</li><li>compileDebugKotlin runs kotlinc on your Kotlin files.</li><li>compileDebugJavaWithJavac runs javac on any Java files.</li><li>D8 converts everything to dex (R8 does this for release builds).</li><li>The APK is packaged and signed.</li></ol><p>AAPT2 (Android Asset Packaging Tool) works in two phases:</p><ul><li>Compile: every file in res/ is turned into a compact binary .flat file.</li><li>Link: all .flat files are merged, resources.arsc (the resource table) and a binary AndroidManifest.xml are written, and every resource gets an integer ID in the R class.</li></ul><p>Those IDs look like 0x7f0e001b. The 7f means &quot;this app&quot;, the next byte is the resource type (string, layout, drawable), and the rest is the entry number. When you write R.string.app_name, your code is really just holding a number.</p><p>One more detail: Kotlin compiles before Java. kotlinc can read Java source files to understand references to them, and then javac compiles the Java files with the Kotlin .class files on its classpath. That is how both languages see each other in the same module.</p><h3>Step 1: The lexer turns characters into tokens</h3><p>The lexer reads your file one character at a time and groups characters into tokens, the “words” of Kotlin. This is the last moment your individual letters matter.</p><p>Take the line fun add(a: Int) = a + 1. To the lexer it starts as a stream of characters: f, u, n, space, a, d, d, ( and so on. It walks through them and produces this:</p><pre>Characters   Token type<br>----------   ---------------<br>fun          FUN_KEYWORD<br>add          IDENTIFIER<br>(            LPAR<br>a            IDENTIFIER<br>:            COLON<br>Int          IDENTIFIER<br>)            RPAR<br>=            EQ<br>a            IDENTIFIER<br>+            PLUS<br>1            INTEGER_LITERAL</pre><p>A few things worth noticing:</p><ul><li>Int is just an IDENTIFIER here. The lexer has no idea that it is a type. It only knows it is a name.</li><li>The lexer always takes the longest match. funny becomes one IDENTIFIER, not the keyword fun followed by ny.</li><li>Spaces, new lines and comments also become tokens (WHITE_SPACE, EOL_COMMENT). The parser simply skips them.</li><li>A string template is split into pieces. &quot;Hi $name&quot; becomes OPEN_QUOTE, REGULAR_STRING_PART (Hi ), SHORT_TEMPLATE_ENTRY_START ($), IDENTIFIER (name) and CLOSING_QUOTE.</li><li>Kotlin’s lexer is not hand written. It is generated from a grammar file by a tool called JFlex.</li></ul><p>Very few errors come from this stage. An unclosed string or a character Kotlin does not allow is about all it can catch. From here on, the compiler never looks at your characters again, only at tokens.</p><h3>Step 2: The parser turns tokens into a tree</h3><p>The parser takes the flat list of tokens and arranges it into a tree that shows the structure of your code: what is a function, what is a parameter, and what is inside what.</p><p>It follows the Kotlin grammar rules. When it sees FUN_KEYWORD, it knows a function declaration is starting, so it expects a name, then a parameter list in brackets, then an optional return type, then a body. This style is called a recursive descent parser: each grammar rule is a function, and rules call each other as they go deeper.</p><p>For add, the tree looks like this:</p><pre>Function: add<br>├── Parameter: a<br>│   └── Type reference: Int<br>└── Body: binary expression (+)<br>    ├── Left:  reference to a<br>    └── Right: literal 1</pre><p>Operator precedence is decided here. In a + b * c, the multiplication sits deeper in the tree than the addition, so it is calculated first.</p><p>Syntax errors come from this stage. If you forget a bracket, the parser is the one saying Expecting &#39;)&#39;.</p><p>One small detail: the IDE builds this tree as PSI (Program Structure Interface), which powers highlighting and refactoring. The command line compiler in K2 uses a lighter version called LightTree, because it does not need all the editor features. The shape of the tree is the same.</p><p>The parser understands structure, but not meaning. Int is still just a name in a box. The compiler does not yet know whether Int is a class, whether a + 1 is even allowed, or what add returns.</p><h3>Step 3: FIR gives the tree its meaning</h3><p>This is the brain of the compiler. The K2 frontend converts the tree into FIR (Frontend Intermediate Representation) and then works out what every single name actually refers to.</p><p>It does this in phases, each one building on the last:</p><ol><li>Imports: which packages and classes are visible in this file.</li><li>Supertypes: what each class extends or implements. User extends Any.</li><li>Types: every type name is linked to a real class. Int becomes kotlin.Int.</li><li>Status: visibility and modality, like public, final or open.</li><li>Implicit types: return types you did not write are inferred. add returns kotlin.Int, because Int + Int gives Int.</li><li>Body resolve: every call inside a function body is matched to a real function.</li></ol><p>After resolution, add looks roughly like this inside the compiler:</p><pre>public final fun add(a: kotlin.Int): kotlin.Int<br>    return a.plus(1)    // resolved to kotlin.Int.plus(other: kotlin.Int)</pre><p>Notice that + was never really an operator. It is a call to the function plus on Int. The same happens in greet: user?.name is resolved to the getter of the name property on User, and the compiler records that user can be null there.</p><p>Once everything is resolved, checkers run over the result. This is where almost every red underline in your IDE comes from:</p><ul><li>Type mismatch: passing a String where an Int is expected.</li><li>Unresolved reference: a typo in a name.</li><li>Null safety: calling user.name without ?. on a nullable User?.</li><li>Smart casts: after if (user != null), the compiler tracks the flow and treats user as non-null.</li></ul><p>Compiler plugins also hook in here. The Compose compiler and kotlinx.serialization add their own checks at this stage, which is how you get errors like calling a @Composable function from a normal function.</p><h3>Steps 4 and 5: fir2ir and lowering</h3><p>Now the compiler stops checking and starts rewriting. Your Kotlin features are taken apart, one by one, until only simple operations are left.</p><h4>Step 4: fir2ir</h4><p>The resolved FIR is converted into the backend IR. This IR is shared by every Kotlin target: JVM, JS, Native and Wasm. That is the secret behind Kotlin Multiplatform. The same frontend and the same IR feed different code generators at the end.</p><h4>Step 5: Lowering</h4><p>Bytecode has no idea what a data class, an Elvis operator or a string template is. So the backend runs a long chain of passes called lowerings. Each lowering takes one high level feature and rewrites it in terms of simpler code. The JVM backend has well over a hundred of them.</p><p>Here is our greet function before and after, written as Kotlin for readability:</p><pre>// Before<br>fun greet(user: User?): String {<br>    val name = user?.name ?: &quot;guest&quot;<br>    return &quot;Hi $name&quot;<br>}<br><br>// After lowering (roughly)<br>fun greet(user: User?): String {<br>    val tmp = if (user != null) user.getName() else null<br>    val name = if (tmp != null) tmp else &quot;guest&quot;<br>    return &quot;Hi &quot; + name<br>}</pre><ul><li>?. and ?: became plain if checks against null.</li><li>user.name became a call to the generated getter getName().</li><li>The string template became a concatenation, which ends up as a StringBuilder chain (or an invokedynamic string concat on newer JVM targets).</li></ul><p>Other lowerings in our file and in everyday code:</p><ul><li>Data class: equals, hashCode, toString, copy and component1 are generated for User.</li><li>Null checks: the User(name: String) constructor gets an inserted Intrinsics.checkNotNullParameter(name, &quot;name&quot;), so Java callers cannot sneak in a null.</li><li>Intrinsics: a.plus(1) on Int is recognized as a built-in, so it becomes a raw primitive addition instead of a function call.</li><li>Suspend functions become a state machine with an extra Continuation parameter.</li><li>Default arguments get a helper method with a $default suffix.</li><li>when becomes a chain of if checks or a switch.</li><li>The Compose compiler plugin rewrites every @Composable function here, adding the hidden $composer and $changed parameters.</li></ul><p>After all the lowerings, what is left looks a lot like Java: classes, methods, fields, if, loops and calls. Now it can be written as bytes.</p><h3>Step 6: Codegen, where the bytes are born</h3><p>This is the only step that actually writes bytecode. The JVM backend walks the lowered IR and, for every simple operation, emits the matching JVM instruction into a .class file.</p><p>The JVM is a stack machine. Instructions do not use named variables. They push values onto a stack, pop them, work on them, and push the result back.</p><p>Here is add(a: Int) = a + 1, as it lands in GreetingKt.class (top level functions live in a class named after the file):</p><pre>Instruction   Byte   What it does<br>-----------   ----   ------------------------------------<br>iload_0       1A     Push parameter a onto the stack<br>iconst_1      04     Push the number 1<br>iadd          60     Pop both, push a + 1<br>ireturn       AC     Return the value on top of the stack</pre><p>So the entire body of our function is four bytes:</p><pre>1A 04 60 AC</pre><p>That is the moment where our letters a + 1 finally became bytes. The + turned into iadd, which is just the number 0x60 from the JVM specification.</p><p>kotlinc uses a library called ASM to write these bytes, along with the rest of the class file structure:</p><ul><li>The file starts with the magic number CA FE BA BE, followed by the class file version.</li><li>A constant pool stores every string and name the class uses, like &quot;Hi &quot;, &quot;guest&quot; and com/sandeep/demo/User.</li><li>Then come the fields and methods. Each method carries a Code attribute holding bytes like the four above.</li><li>Finally, Kotlin adds a @Metadata annotation. It stores Kotlin-only information, like which types were nullable and which functions were extensions, so other Kotlin code and reflection still understand the class.</li></ul><p>This is also the stage where inline functions are pasted. The backend copies the bytecode of the inline function directly into the caller, and for reified type parameters it writes the real class in place of T.</p><p>At the end of this step, our one Kotlin file has become two class files: GreetingKt.class and User.class.</p><h3>Step 7: R8 and D8 turn class files into dex</h3><p>Android does not run JVM bytecode. ART runs Dalvik bytecode, stored in .dex files, so our class files must be compiled one more time.</p><ul><li>D8 is the dexer. In debug builds it converts each class or library to dex separately and then merges them, which keeps incremental builds fast.</li><li>R8 is used for release builds when isMinifyEnabled = true. It does four jobs in one pass, listed below.</li><li>Both also do desugaring. Newer Java language features, like lambdas compiled with invokedynamic, are rewritten so they run on older Android versions.</li></ul><p>The four jobs of R8:</p><ol><li>Shrink: starting from entry points (your Activities and Services in the manifest, plus keep rules), it removes every class and method that nothing reaches.</li><li>Optimize: it inlines small methods, removes dead branches and merges classes.</li><li>Obfuscate: it renames User to something like a, which also makes the app smaller.</li><li>Dex: it writes the final .dex output.</li></ol><p>The biggest change in this step is the instruction style. The JVM is a stack machine. Dalvik is a register machine: instructions name their inputs and outputs directly, a bit like CPU registers.</p><p>Here is add again, now as dex (shown in smali, the readable form of dex):</p><pre>.method public static final add(I)I<br>    .registers 2<br>    add-int/lit8 v0, p0, 0x1<br>    return v0<br>.end method</pre><p>Four JVM instructions became two dex instructions. “Add the literal 1 to parameter p0 and store it in v0, then return v0.” In bytes, it is something like:</p><pre>D8 00 01 01  0F 00</pre><p>A fun coincidence: the opcode for add-int/lit8 is 0xD8, the same as the name of the tool that produced it.</p><p>Why registers? Fewer instructions to fetch and decode, and a better fit for the ARM processors inside phones. Dex also shares one constant pool across all classes in a file, so the string &quot;guest&quot; is stored once even if a hundred classes use it. That makes a dex file smaller than the same classes in a jar.</p><p>One limit to know: a single dex file can reference at most 65,536 methods. Bigger apps get classes2.dex, classes3.dex and so on. This is multidex, and it is built in from Android 5.0 onwards.</p><h3>Step 8: Packaging, signing and the handoff to ART</h3><p>The last step zips everything into an APK and signs it, so the phone can trust where it came from.</p><p>An APK is just a zip file. Rename one to .zip and you can open it. Inside you will find:</p><ul><li>classes.dex, classes2.dex: your compiled code, including our D8 00 01 01.</li><li>resources.arsc: the compiled resource table from AAPT2.</li><li>res/: compiled XML layouts, images and other resources.</li><li>AndroidManifest.xml: the manifest, in binary form.</li><li>lib/: native .so libraries, one folder per CPU type.</li><li>assets/: raw files you ship as they are.</li><li>META-INF/: the older v1 signature files.</li></ul><p>Two final touches:</p><ul><li>zipalign lines up uncompressed files on 4 byte boundaries, so the phone can map them straight into memory instead of copying them.</li><li>apksigner signs the APK. Modern v2 and v3 signatures cover the whole file, so changing a single byte breaks the signature. Debug builds are signed automatically with a debug key on your machine.</li></ul><p>If you publish an AAB (Android App Bundle) instead, you upload the bundle, and Google Play builds smaller split APKs for each device, based on CPU type, screen density and language.</p><p>This is where compile time ends. When the APK is installed, PackageManager verifies the signature and hands the dex files to ART. From this point, the phone owns our code. ART will read those same D8 00 01 01 bytes, decide whether to interpret them, JIT compile them or AOT compile them into real ARM machine code, and finally run them.</p><h3>The whole journey at a glance</h3><ul><li>Step 0, Gradle, KSP and AAPT2: annotations and res/ become generated code, the R class and resources.arsc.</li><li>Step 1, Lexer: characters become tokens.</li><li>Step 2, Parser: tokens become a syntax tree.</li><li>Step 3, FIR resolve: the tree gets types and meaning, plus errors.</li><li>Step 4, fir2ir: resolved FIR becomes the shared backend IR.</li><li>Step 5, Lowering: Kotlin features become simple, Java-like IR.</li><li>Step 6, JVM codegen: simple IR becomes .class files (1A 04 60 AC).</li><li>Step 7, R8 or D8: .class files become .dex files (D8 00 01 01).</li><li>Step 8, packager and apksigner: dex and resources become a signed APK or AAB.</li></ul><p>If you remember one line, remember this: letters die at the lexer, meaning flows through the tree, and bytes are born only at codegen.</p><h3>Try it yourself</h3><p>You do not have to take my word for any of this. Every stage can be seen with tools you already have:</p><ul><li>In Android Studio, open a Kotlin file and go to Tools, Kotlin, Show Kotlin Bytecode. Click Decompile to see the Java-like version.</li><li>Run javap -c -p GreetingKt.class on the files in app/build/tmp/kotlin-classes/debug to see the raw JVM instructions.</li><li>Use Build, Analyze APK, open classes.dex, right click any method and choose Show Bytecode to see the smali.</li><li>Run dexdump -d classes.dex from your Android SDK build tools to see dex instructions with their actual bytes.</li></ul><h3>What comes next</h3><p>Our add function is now six bytes inside a signed APK, waiting on the phone. In the next and final article of this series, we follow it at runtime: how install time compilation works, how Zygote starts your process, and how ART interprets, JIT compiles and AOT compiles those bytes into ARM machine code that the CPU finally runs.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d5b28dd4acea" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[channelFlow — When One Flow Needs Multiple Producers]]></title>
            <link>https://medium.com/@sandeep84397/channelflow-when-one-flow-needs-multiple-producers-531dd68f1b78?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/531dd68f1b78</guid>
            <category><![CDATA[android-development-tools]]></category>
            <category><![CDATA[kotlin-flow]]></category>
            <category><![CDATA[jetpack-compose]]></category>
            <category><![CDATA[kotlin-coroutines]]></category>
            <category><![CDATA[kotlin]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Mon, 05 Oct 2026 06:54:14 GMT</pubDate>
            <atom:updated>2026-10-05T06:54:14.537Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A regular </em><em>flow is built for sequential emission. </em><em>channelFlow lets several structured child coroutines send values safely into one cold Flow.</em></p><blockquote><strong><em>BuildPulse series · Article 4 of 9</em></strong></blockquote><blockquote><a href="https://medium.com/@sandeep84397/callbackflow-how-a-listener-becomes-a-flow-without-leaking-a07d4f438dac"><em>Previous on Medium: </em></a><a href="https://medium.com/@sandeep84397/callbackflow-how-a-listener-becomes-a-flow-without-leaking-a07d4f438dac"><em>callbackFlow — How a Listener Becomes a Flow Without Leaking</em></a><em> · </em><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-04-channel-flow/articles/03-callback-flow.md"><em>Repository article</em></a><em> · </em><strong><em>You are here: </em></strong><strong><em>channelFlow</em></strong><em> · Next: Hot streams </em>(unpublished)</blockquote><p>Article 3 solved one boundary problem.</p><p>A CI SDK owned a callback listener. callbackFlow registered that listener when collection started, forwarded callbacks with trySend(), and removed the listener when collection stopped.</p><p>Now BuildPulse has a different problem.</p><p>The compiler, test runner, and security scanner can work at the same time:</p><pre>Compiler ───────────────┐<br>Test runner ────────────┼─→ one BuildPulse timeline<br>Security scanner ───────┘</pre><p>Each producer must report progress while it is running. The UI wants one Flow containing those reports in arrival order.</p><p>That is the Article 4 problem.</p><h3>The engineering problem: one emitter became three</h3><p>A normal cold Flow is easy when one coroutine owns the sequence:</p><pre>fun reports(): Flow&lt;BuildReport&gt; = flow {<br>    emit(compilerStarted)<br>    emit(compilerCompleted)<br>}</pre><p>The builder runs sequentially. Each emit() happens from that Flow&#39;s expected coroutine context.</p><p>But our real work is concurrent:</p><pre>flow {<br>    launch { emit(compilerReport) }<br>    launch { emit(testReport) }<br>    launch { emit(securityReport) }<br>}</pre><p>This is the wrong builder for that job.</p><p>flow {} protects context preservation. Emitting from independently launched child coroutines violates the normal Flow emission contract.</p><p>The requirement is not “make Flow ignore its rules.”</p><p>It is:</p><blockquote><em>Which Flow builder is designed for several coroutines to produce values concurrently?</em></blockquote><h3>Why is it named channelFlow?</h3><p>The name describes both halves of the mechanism.</p><ul><li><strong>Channel:</strong> a concurrency-safe sending boundary. Several coroutines can send values into it.</li><li><strong>Flow:</strong> collectors consume those sent values through the normal Flow API.</li></ul><pre>Concurrent producers  →  channel  →  Flow collector</pre><p>Inside the builder, child coroutines use send(report).</p><p>Outside the builder, callers still receive Flow&lt;BuildReport&gt; and use collect().</p><p>Memory rule:</p><blockquote><strong><em>Many children send. One Flow collects.</em></strong></blockquote><h3>The cornerstone analogy: one CI control room, three specialist desks</h3><p>Imagine a CI control room with three specialist desks:</p><ul><li>Compiler desk</li><li>Test desk</li><li>Security desk</li></ul><p>All three specialists begin work for the same build. They do not wait for one another.</p><p>Whenever a specialist has news, they place a report into one shared inbox. The control-room operator reads reports in the order they arrive.</p><p>Mapping:</p><ul><li>Start one control-room session = collect()</li><li>Open the shared inbox = channelFlow {}</li><li>Start three specialist desks = three launch {} children</li><li>Submit a report = send(report)</li><li>Read the shared timeline = Flow collector</li><li>Close the control room = cancel collection</li><li>Stop every specialist = structured cancellation</li></ul><p>The inbox does not force the compiler to wait for security. It only gives all producers one safe place to send their reports.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*aAIUj3vBvynwa0we.gif" /></figure><p>The animation shows the important order:</p><pre>Compiler: RUNNING<br>Tests: RUNNING<br>Security: RUNNING<br>Compiler: COMPLETE<br>Security: COMPLETE<br>Tests: COMPLETE</pre><p>This is arrival order, not producer-list order.</p><h3>The smallest useful example</h3><p>Assume each build task can run independently and report values:</p><pre>fun interface BuildTaskRunner {<br>    suspend fun run(<br>        buildId: BuildId,<br>        report: suspend (BuildReport) -&gt; Unit,<br>    )<br>}</pre><p>We can combine several runners with channelFlow:</p><pre>class ChannelFlowBuildReportRepository(<br>    private val runners: List&lt;BuildTaskRunner&gt;,<br>) {<br>    fun observeReports(buildId: BuildId): Flow&lt;BuildReport&gt; = channelFlow {<br>        runners.forEach { runner -&gt;<br>            launch {<br>                runner.run(buildId) { report -&gt;<br>                    send(report)<br>                }<br>            }<br>        }<br>    }<br>}</pre><p>Follow the execution:</p><pre>observeReports() called<br>    → returns a cold Flow<br>    → no runner starts</pre><pre>collect() starts<br>    → channelFlow block runs<br>    → child 1 starts compiler<br>    → child 2 starts tests<br>    → child 3 starts security scan</pre><pre>any child calls send(report)<br>    → report enters the channel<br>    → collector receives it</pre><pre>all children complete<br>    → channelFlow completes<br>    → collection completes</pre><h3>channelFlow is still cold</h3><p>The word “channel” can make this confusing.</p><p>channelFlow returns a cold Flow.</p><p>Creating it does not start any producer:</p><pre>val reports = repository.observeReports(buildId)</pre><pre>// Compiler starts: 0<br>// Test runner starts: 0<br>// Security scanner starts: 0</pre><p>Collection starts the work:</p><pre>reports.collect { report -&gt;<br>    println(report)<br>}</pre><p>Collect the same Flow twice and the whole producer group runs twice:</p><pre>Collector A  → compiler A + tests A + security A<br>Collector B  → compiler B + tests B + security B</pre><p>The two collectors do not automatically share one workshop.</p><p>Sharing comes later in this series.</p><h3>Why send() instead of emit()?</h3><p>flow {} gives you a FlowCollector. Its production operation is emit().</p><p>channelFlow {} gives you a ProducerScope. Its production operation is send().</p><pre>flow { emit(value) }</pre><pre>channelFlow {<br>    launch { send(value) }<br>}</pre><p>send() is suspending. If the internal channel cannot accept another value immediately, the sending coroutine can suspend instead of blocking a thread.</p><p>That is different from Article 3’s callback boundary:</p><ul><li>A normal callback usually cannot suspend, so callbackFlow commonly uses trySend().</li><li>A child coroutine can suspend, so channelFlow can use send().</li></ul><p>Memory rule:</p><blockquote><strong><em>Callback cannot wait: </em></strong><strong><em>trySend(). Coroutine can wait: </em></strong><strong><em>send().</em></strong></blockquote><p>This is a practical memory rule, not a claim that trySend() belongs only to callbackFlow.</p><h3>Structured concurrency owns the whole workshop</h3><p>The launch {} blocks inside channelFlow are children of its producer scope.</p><p>That gives three important lifecycle rules.</p><h3>1. Completion waits for every child</h3><p>If compiler and security finish but tests are still running, the Flow stays active.</p><pre>Compiler complete<br>Security complete<br>Tests running<br>    → channelFlow still running</pre><p>The Flow completes only after the builder block and all its children complete.</p><h3>2. Cancelling collection cancels the children</h3><p>If the user leaves the Compose screen and collection is cancelled, the channelFlow scope is cancelled. Its child producers are cancelled too.</p><pre>Collector cancelled<br>    → channelFlow cancelled<br>    → compiler child cancelled<br>    → test child cancelled<br>    → security child cancelled</pre><p>No detached GlobalScope work is needed.</p><h3>3. A child failure fails the group</h3><p>Suppose the security scanner throws:</p><pre>Security child fails<br>    → channelFlow fails<br>    → sibling children are cancelled<br>    → collector receives the failure</pre><p>That is normal structured-concurrency behavior. If your domain requires one producer to fail without cancelling the others, that is a separate error-isolation decision. Do not silently add supervision without defining the required semantics.</p><h3>flow vs callbackFlow vs channelFlow</h3><p>Use the producer shape to choose.</p><h3>Use flow when one coroutine emits sequentially</h3><pre>flow {<br>    emit(loadFirstPage())<br>    emit(loadSecondPage())<br>}</pre><p>Question it answers:</p><blockquote><em>How does one suspending producer emit values over time?</em></blockquote><h3>Use callbackFlow when an external callback API owns the timing</h3><pre>callbackFlow {<br>    val listener = Listener { value -&gt; trySend(value) }<br>    source.addListener(listener)<br>    awaitClose { source.removeListener(listener) }<br>}</pre><p>Question it answers:</p><blockquote><em>How does a listener API become a cancellable cold Flow?</em></blockquote><h3>Use channelFlow when several coroutines produce concurrently</h3><pre>channelFlow {<br>    launch { send(loadCompilerReport()) }<br>    launch { send(loadTestReport()) }<br>    launch { send(loadSecurityReport()) }<br>}</pre><p>Question it answers:</p><blockquote><em>How do several structured producers send values into one Flow?</em></blockquote><p>callbackFlow and channelFlow are closely related builders. The difference is the problem you are expressing.</p><h3>The internal buffer: know that it exists</h3><p>channelFlow uses a channel between producers and the downstream collector. Current kotlinx.coroutines documentation defines a default buffered channel for this builder.</p><p>That means a producer may send ahead of a slower collector until available capacity is used. After that, send() suspends.</p><p>You can change capacity with buffer():</p><pre>repository.observeReports(buildId)<br>    .buffer(capacity = 0)</pre><p>But capacity and overflow policy change delivery and backpressure behavior. BuildPulse keeps the default here because Article 4 is about concurrent production, not buffer tuning.</p><p>Memory rule:</p><blockquote><strong><em>First understand who produces. Then decide how much can wait.</em></strong></blockquote><h3>The BuildPulse implementation</h3><p>BuildPulse models three tasks:</p><pre>enum class BuildTask {<br>    COMPILER,<br>    TESTS,<br>    SECURITY_SCAN,<br>}</pre><p>Each simulated runner reports STARTED, waits for its own duration, then reports COMPLETED:</p><pre>class SimulatedBuildTaskRunner(<br>    private val task: BuildTask,<br>    private val startDelayMillis: Long,<br>    private val workDurationMillis: Long,<br>) : BuildTaskRunner {</pre><pre>    override suspend fun run(<br>        buildId: BuildId,<br>        report: suspend (BuildReport) -&gt; Unit,<br>    ) {<br>        delay(startDelayMillis)<br>        report(BuildReport(buildId, task, BuildReportState.STARTED))<br>        delay(workDurationMillis)<br>        report(BuildReport(buildId, task, BuildReportState.COMPLETED))<br>    }<br>}</pre><p>The repository launches every runner in the channelFlow scope and sends every report into the same stream.</p><p>The Android/Compose lab then makes two invisible ideas visible:</p><ul><li>producer state: waiting, running, complete, or cancelled;</li><li>collector order: the exact order in which reports arrived.</li></ul><p>Run the lab:</p><ol><li>Before tapping <strong>Start collection</strong>, every task is waiting.</li><li>Start collection. One cold channelFlow execution begins.</li><li>Compiler, tests, and security become active independently.</li><li>Reports appear in one merged timeline.</li><li>Wait for completion, or tap <strong>Cancel</strong> to stop the whole producer group.</li><li>Tap <strong>Run again</strong>. A fresh cold execution starts from an empty timeline.</li></ol><h3>Tests that protect the behavior</h3><p>The milestone verifies these rules:</p><pre>Flow created, not collected  → zero task starts<br>Collection starts            → all tasks run concurrently<br>Reports arrive               → one merged Flow preserves arrival order<br>Collection runs again        → every task starts a fresh execution<br>Collection cancelled         → every running child is cancelled<br>One child fails              → siblings cancel; collection fails</pre><p>The concurrency test uses virtual time:</p><pre>val repository = ChannelFlowBuildReportRepository(<br>    runners = listOf(<br>        scheduledRunner(COMPILER, completionDelayMillis = 100),<br>        scheduledRunner(TESTS, completionDelayMillis = 200),<br>        scheduledRunner(SECURITY_SCAN, completionDelayMillis = 300),<br>    ),<br>)</pre><pre>val reports = repository.observeReports(buildId).toList()</pre><pre>assertEquals(300, currentTime)</pre><p>Sequential execution would take 600 milliseconds. Concurrent execution completes at the slowest child’s 300-millisecond mark.</p><p>The cancellation test verifies ownership:</p><pre>val collection = launch {<br>    repository.observeReports(buildId).collect(received::add)<br>}</pre><pre>runCurrent()<br>collection.cancelAndJoin()</pre><pre>assertEquals(3, childCancellations)</pre><p>The UI illustrates the behavior. Tests prove it.</p><p>Supporting project:</p><ul><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/tree/article-04-channel-flow">Run the Article 04 checkpoint</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-04-channel-flow/app/src/main/java/io/github/buildpulse/simulation/ChannelFlowBuildReportRepository.kt">Read the </a><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-04-channel-flow/app/src/main/java/io/github/buildpulse/simulation/ChannelFlowBuildReportRepository.kt">channelFlow repository</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-04-channel-flow/app/src/test/java/io/github/buildpulse/simulation/ChannelFlowBuildReportRepositoryTest.kt">Read the concurrency tests</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/compare/article-03-callback-flow...article-04-channel-flow">Compare Article 03 with Article 04</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/releases/tag/article-04-channel-flow">Open the Article 04 GitHub release</a></li></ul><h3>When should you use channelFlow?</h3><p>Use it when:</p><ul><li>several coroutines must produce values concurrently;</li><li>those values must become one Flow;</li><li>child lifetimes should follow collection;</li><li>producer completion, cancellation, and failure should remain structured;</li><li>sending may happen from different coroutine contexts.</li></ul><p>Common Android and backend examples:</p><ul><li>merge progress from parallel upload parts;</li><li>combine independent device scans into one discovery stream;</li><li>report concurrent validation checks;</li><li>merge several suspending data sources;</li><li>implement a custom concurrent Flow operator;</li><li>stream progress from compiler, test, and security jobs.</li></ul><p>Do not choose it automatically when:</p><ul><li>one coroutine can emit sequentially — use flow;</li><li>an existing listener API needs registration and cleanup — use callbackFlow;</li><li>existing Flows only need a standard operator such as merge or combine;</li><li>many collectors must share one upstream execution — sharing is the next problem;</li><li>you need a worker queue where each item goes to one receiver — that points toward Channel, covered later.</li></ul><h3>Common mistakes</h3><h3>“channelFlow is hot because it contains a channel.”</h3><p>No. The returned Flow is cold. Each collection runs a new builder execution and launches a new child group.</p><h3>“channelFlow makes sequential code faster.”</h3><p>No. Concurrency appears only when you launch or otherwise run producers concurrently. A builder name does not create useful parallelism by itself.</p><h3>“The report order is deterministic.”</h3><p>Only if producer timing is deterministic. The collector receives values in actual send/arrival order.</p><h3>“I should use channelFlow whenever I see two Flows.”</h3><p>Usually not. Standard operators such as merge, combine, zip, and flatMapMerge already express common relationships. Reach for channelFlow when you are implementing a producer boundary or custom concurrent behavior those operators do not express clearly.</p><h3>“Cancellation only stops the collector.”</h3><p>Cancellation propagates into the channelFlow scope and its structured children.</p><h3>“One producer can fail while the others continue automatically.”</h3><p>Not under normal structured failure propagation. Define error isolation deliberately if the product requires it.</p><h3>“The buffer guarantees every value survives cancellation.”</h3><p>No. Cancellation can discard work or values still in flight. A Flow is not durable storage.</p><h3>The complete mental model</h3><p>When considering channelFlow, ask six questions:</p><ol><li><strong>Multiplicity:</strong> Do multiple coroutines need to produce?</li><li><strong>Start:</strong> Which collection starts those producers?</li><li><strong>Send:</strong> Which child calls send() for each value?</li><li><strong>Order:</strong> Does the product accept arrival order?</li><li><strong>Failure:</strong> Should one child failure cancel the group?</li><li><strong>Cancellation:</strong> Must all child work stop when collection stops?</li></ol><p>For BuildPulse:</p><pre>Flow created          → no task runs<br>Collector starts      → three child tasks start<br>Child sends report    → collector receives it<br>Children interleave   → timeline follows arrival order<br>All children finish   → Flow completes<br>Collector cancels     → every child cancels<br>Collector starts again→ new cold execution</pre><p>If you can predict those transitions, you understand channelFlow.</p><h3>Where we go next</h3><p>BuildPulse can now combine several concurrent producers into one cold Flow.</p><p>But a new problem appears when two screens collect it:</p><pre>Dashboard collects  → compiler + tests + security start<br>Details collects    → compiler + tests + security start again</pre><p>Sometimes that is correct. Sometimes both screens should observe one already-running upstream operation.</p><p>Next question:</p><blockquote><em>What keeps producing independently of one collector, and how can several collectors observe the same stream?</em></blockquote><p>That begins our discussion of hot streams.</p><h3>Official references</h3><ul><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/channel-flow.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/channel-flow.html">channelFlow API</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/">Kotlin Flow API and context-preservation rules</a></li><li><a href="https://kotlinlang.org/docs/flow.html">Kotlin Flow guide</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/send.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/send.html">send API</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/">Kotlin structured-concurrency guidance</a></li></ul><p><em>BuildPulse is one evolving Android/Compose system. Each article introduces only the next concept required by the engineering problem, and each GitHub milestone remains runnable.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=531dd68f1b78" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[callbackFlow — How a Listener Becomes a Flow Without Leaking]]></title>
            <link>https://medium.com/@sandeep84397/callbackflow-how-a-listener-becomes-a-flow-without-leaking-a07d4f438dac?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/a07d4f438dac</guid>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Fri, 04 Sep 2026 02:48:34 GMT</pubDate>
            <atom:updated>2026-09-04T02:48:34.359Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong><em>BuildPulse series · Article 3 of 9</em></strong></blockquote><blockquote><a href="https://medium.com/@sandeep84397/cold-flow-why-nothing-happens-until-collect-927b9b10823d"><em>Previous on Medium: Cold Flow — Why Nothing Happens Until </em></a><a href="https://medium.com/@sandeep84397/cold-flow-why-nothing-happens-until-collect-927b9b10823d"><em>collect()</em></a><em> · </em><a href="https://medium.com/@sandeep84397/cold-flow-why-nothing-happens-until-collect-927b9b10823d"><em>Repository article</em></a><em> · </em><strong><em>You are here: </em></strong><strong><em>callbackFlow</em></strong><em> · Next: </em><em>channelFlow </em>(unpublished)</blockquote><p>In Article 2, our producer already spoke Kotlin’s language:</p><pre>flow {<br>    emit(BuildStage.QUEUED)<br>    emit(BuildStage.COMPILING)<br>}</pre><p>That works when we own the suspending code that produces the values.</p><p>Real Android and backend integrations often do not look like that. A CI SDK, Bluetooth scanner, location client, WebSocket library, or legacy Java API may own the producer and call us through a listener:</p><pre>ciSdk.addListener { update -&gt;<br>    // The SDK decides when this runs.<br>}</pre><p>Our UI wants a Flow&lt;BuildSnapshot&gt;, but the SDK gives us addListener() and removeListener().</p><p>That mismatch is the Article 3 problem.</p><h3>The engineering problem: who owns the listener?</h3><p>Registering a listener is easy. Owning its complete lifetime is harder.</p><pre>ciSdk.addListener(listener)</pre><p>Now ask:</p><ul><li>When should registration happen?</li><li>How does a callback become a Flow value?</li><li>What happens if the user leaves the screen?</li><li>Who calls removeListener()?</li><li>What if two collectors observe the same Flow?</li></ul><p>If cleanup is forgotten, the SDK can keep a dead screen or repository alive. It may continue doing work, deliver duplicate updates after a new listener is added, or leak memory.</p><p>So the real problem is not “how do I call addListener()?”</p><p>It is:</p><blockquote><em>How do we make listener registration, value delivery, and cleanup follow the lifetime of Flow collection?</em></blockquote><h3>Why is it named callbackFlow?</h3><p>The name describes the bridge.</p><ul><li><strong>Callback:</strong> another component owns the timing and calls our listener when something happens.</li><li><strong>Flow:</strong> our application receives those callback invocations as a collectable stream of values.</li></ul><pre>Callback API  →  callbackFlow bridge  →  Flow collector</pre><p>It does not mean “a special hot Flow.” The resulting Flow is cold. Its block runs for every collection.</p><p>Memory rule:</p><blockquote><strong><em>A callback calls us. </em></strong><strong><em>callbackFlow carries that call into Flow.</em></strong></blockquote><h3>The cornerstone analogy: a CI control-room phone</h3><p>Imagine that BuildPulse has a control room. It announces build changes, but only to registered phone operators.</p><ul><li>CI control room = callback-based SDK</li><li>Register a phone operator = addListener()</li><li>Incoming build alert = callback invocation</li><li>Operator passes the note onward = trySend(update)</li><li>BuildPulse desk reads the note = Flow collector</li><li>Desk closes = collection is cancelled</li><li>Operator returns the phone = awaitClose { removeListener() }</li></ul><p>Before a collector arrives, no operator is registered. An alert sent at that time is missed.</p><p>When Collector A starts, one operator registers. Future alerts reach A.</p><p>When Collector B starts, a second operator registers. The SDK calls both listeners, so both collectors receive future updates.</p><p>When A stops, A’s operator unregisters. B remains registered and continues receiving alerts.</p><p>This is the complete lifecycle:</p><pre>No collector<br>    ↓<br>No listener<br>    ↓ collect()<br>addListener(listener)<br>    ↓ SDK invokes callback<br>trySend(update)<br>    ↓<br>Collector receives update<br>    ↓ collection cancelled<br>awaitClose { removeListener(listener) }<br>    ↓<br>No listener, no more delivery</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Ii9u2zPhsKWsYjDs.gif" /></figure><p>Memory rule:</p><blockquote><strong><em>Register → Forward → Unregister.</em></strong></blockquote><h3>The smallest useful example</h3><p>Assume a callback API with an explicit registration contract:</p><pre>interface BuildCallbackSource {<br>    fun addListener(listener: BuildUpdateListener)<br>    fun removeListener(listener: BuildUpdateListener)<br>}</pre><pre>fun interface BuildUpdateListener {<br>    fun onBuildUpdated(snapshot: BuildSnapshot)<br>}</pre><p>We can adapt it once:</p><pre>fun observeBuild(<br>    source: BuildCallbackSource,<br>): Flow&lt;BuildSnapshot&gt; = callbackFlow {<br>    val listener = BuildUpdateListener { snapshot -&gt;<br>        trySend(snapshot)<br>    }</pre><pre>    source.addListener(listener)</pre><pre>    awaitClose {<br>        source.removeListener(listener)<br>    }<br>}</pre><p>Now follow one collection:</p><pre>1. observeBuild(source) created        → listener count = 0<br>2. collect() starts                    → listener count = 1<br>3. SDK callback: COMPILING             → trySend(COMPILING)<br>4. collector receives COMPILING<br>5. collecting coroutine is cancelled   → awaitClose cleanup runs<br>6. removeListener(listener)             → listener count = 0<br>7. SDK callback: RUNNING_TESTS          → collector receives nothing</pre><p>Creating the Flow does not register anything. collect() does.</p><p>That is why callbackFlow is still cold.</p><h3>What exactly do trySend() and awaitClose() do?</h3><h3>trySend() forwards a callback without suspending it</h3><p>A normal callback function is usually not a suspending function. It cannot safely call the suspending send() operation directly.</p><p>trySend(value) attempts to place the value into callbackFlow&#39;s channel immediately and returns a result describing success or failure.</p><pre>val result = trySend(snapshot)</pre><pre>if (result.isFailure) {<br>    // The collector may already be gone, or capacity may be unavailable.<br>}</pre><p>BuildPulse intentionally keeps the first example small and uses the default capacity. Buffer size, overflow policy, and backpressure deserve a separate discussion because they change delivery guarantees.</p><h3>awaitClose() keeps the bridge alive and owns cleanup</h3><p>Without awaitClose, the builder block reaches its end immediately after registration. If the callback channel is still open, callbackFlow fails fast with IllegalStateException instead of allowing the listener to leak silently.</p><pre>source.addListener(listener)</pre><pre>awaitClose {<br>    source.removeListener(listener)<br>}</pre><p>awaitClose suspends while the bridge is active. When collection is cancelled or the channel closes, its cleanup block runs.</p><p>This gives one place responsibility for both sides of the lifetime:</p><pre>collect starts  → register resource<br>collect stops   → unregister resource</pre><p>The callback API’s register and unregister methods must be safe when cancellation races with a callback or registration. That requirement belongs to the callback API contract, not only to Flow.</p><h3>Two collectors mean two listener registrations</h3><p>The same cold behavior from Article 2 still applies:</p><pre>val updates = repository.observeHistory(buildId)</pre><pre>scope.launch { updates.collect { println(&quot;A: ${it.stage}&quot;) } }<br>scope.launch { updates.collect { println(&quot;B: ${it.stage}&quot;) } }</pre><p>Expected lifecycle:</p><pre>Collector A starts  → addListener(A) → listener count = 1<br>Collector B starts  → addListener(B) → listener count = 2</pre><pre>SDK: COMPILING      → A receives COMPILING<br>                    → B receives COMPILING</pre><pre>Collector A stops   → removeListener(A) → listener count = 1<br>SDK: RUNNING_TESTS  → B receives RUNNING_TESTS</pre><p>The collectors receive the same future SDK event because the SDK calls every registered listener. They are not sharing one callbackFlow execution; each collection has its own execution and listener.</p><p>If one upstream registration must be shared by many screens, we will need a sharing operator or hot stream later in the series.</p><h3>What happens to callbacks sent before collection?</h3><p>They are missed.</p><pre>SDK: QUEUED         → zero listeners → missed<br>Collector starts    → listener registered<br>SDK: COMPILING      → delivered</pre><p>callbackFlow adapts future callback invocations. It does not automatically remember the last state or replay old events.</p><p>If a new collector must immediately receive the current build state, the design needs an initial query, replay, or state holder. That is a different requirement; we will address state with StateFlow later.</p><h3>The BuildPulse implementation</h3><p>The repository now depends on a small callback abstraction instead of a concrete SDK:</p><pre>class CallbackFlowBuildHistoryRepository(<br>    private val callbackSource: BuildCallbackSource,<br>) : BuildHistoryReader {</pre><pre>    override fun observeHistory(buildId: BuildId): Flow&lt;BuildSnapshot&gt; = callbackFlow {<br>        val listener = BuildUpdateListener { snapshot -&gt;<br>            if (snapshot.buildId == buildId) {<br>                trySend(snapshot).onFailure {<br>                    // This low-rate lab deliberately drops an update that cannot be accepted.<br>                }<br>            }<br>        }</pre><pre>        callbackSource.addListener(listener)<br>        awaitClose {<br>            callbackSource.removeListener(listener)<br>        }<br>    }<br>}</pre><p>The Android/Compose lab makes the invisible lifetime visible:</p><ol><li>Advance the simulated server before listening. The update is missed.</li><li>Start Collector A. The listener count becomes one.</li><li>Advance the server. A receives the callback value.</li><li>Start Collector B. The listener count becomes two.</li><li>Advance again. Both collectors receive the new value.</li><li>Stop A. The listener count returns to one.</li><li>Advance again. Only B receives the value.</li></ol><p>The UI is not the proof of correctness; deterministic tests are.</p><h3>Tests that protect the behavior</h3><p>The milestone verifies five rules:</p><pre>Flow created, not collected  → zero listeners<br>Collection starts            → listener registered; matching events stay ordered<br>Different build event        → ignored<br>Collection cancelled         → listener removed; later callbacks not delivered<br>Two collectors stop in turn  → listener count follows 0 → 1 → 2 → 1 → 0</pre><p>The cancellation test is the most important one:</p><pre>val collection = launch {<br>    repository.observeHistory(buildId).collect(received::add)<br>}</pre><pre>runCurrent()<br>assertEquals(1, sdk.listenerCount)</pre><pre>collection.cancelAndJoin()<br>assertEquals(0, sdk.listenerCount)</pre><pre>sdk.publish(runningTests)<br>assertEquals(listOf(compiling), received)</pre><p>This test checks observable ownership, not an implementation detail.</p><p>Supporting project:</p><ul><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/tree/article-03-callback-flow">Run the Article 03 checkpoint</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-03-callback-flow/app/src/main/java/io/github/buildpulse/simulation/CallbackFlowBuildHistoryRepository.kt">Read the </a><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-03-callback-flow/app/src/main/java/io/github/buildpulse/simulation/CallbackFlowBuildHistoryRepository.kt">callbackFlow repository</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-03-callback-flow/app/src/test/java/io/github/buildpulse/simulation/CallbackFlowBuildHistoryRepositoryTest.kt">Read the behavior tests</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/compare/article-02-cold-flow...article-03-callback-flow">Compare Article 02 with Article 03</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/releases/tag/article-03-callback-flow">Open the Article 03 GitHub release</a></li></ul><h3>When should you use callbackFlow?</h3><p>Use it when all of these are true:</p><ul><li>an existing API pushes zero or many values through callbacks or listeners;</li><li>you want to expose those values as a cold Flow;</li><li>registration should begin with collection;</li><li>cancellation must release the callback resource;</li><li>callback invocations may arrive outside the collecting coroutine’s context.</li></ul><p>Common Android examples:</p><ul><li>location updates;</li><li>Bluetooth scan results;</li><li>Firebase-style listeners;</li><li>connectivity callbacks;</li><li>sensor or camera events;</li><li>a Java SDK that exposes registerListener().</li></ul><p>Do not use it automatically when:</p><ul><li>the API returns exactly one result — a cancellable suspending adapter may fit better;</li><li>you already have a Flow — use Flow operators rather than converting it back to callbacks;</li><li>many screens must share one registration — sharing is a separate decision;</li><li>several child coroutines must concurrently send values — that points toward channelFlow.</li></ul><h3>Common mistakes</h3><h3>“callbackFlow is hot because the SDK is already running.”</h3><p>No. The returned Flow is cold. Every collector runs the builder block and normally registers its own listener.</p><h3>“trySend() guarantees that every callback was delivered.”</h3><p>No. It returns a ChannelResult. Delivery can fail when the channel is closed or capacity is unavailable. Decide deliberately whether to ignore, log, retry, or fail.</p><h3>“The listener disappears automatically when the screen closes.”</h3><p>Only if collection is cancelled and the bridge unregisters it in cleanup. The lifetime must be encoded.</p><h3>“awaitClose is just an infinite delay.”</h3><p>No. It waits for channel closure or cancellation and executes the cleanup block before returning.</p><h3>“A new collector receives the latest callback value.”</h3><p>Not automatically. An event emitted before registration is not replayed by callbackFlow.</p><h3>“Two collectors share one listener.”</h3><p>Not by default. Two collections run two cold builder executions and register two listeners.</p><h3>The complete mental model</h3><p>When adapting a callback, ask five questions:</p><ol><li><strong>Register:</strong> Which collection starts the listener?</li><li><strong>Forward:</strong> How does each callback enter the Flow?</li><li><strong>Failure:</strong> What should happen if trySend() fails?</li><li><strong>Cleanup:</strong> Which cancellation path unregisters the listener?</li><li><strong>Multiplicity:</strong> How many collectors — and therefore registrations — will exist?</li></ol><p>For BuildPulse:</p><pre>Flow created          → 0 listeners<br>Collector A starts    → 1 listener<br>Collector B starts    → 2 listeners<br>SDK emits             → A and B receive the future update<br>Collector A stops     → 1 listener<br>Collector B stops     → 0 listeners</pre><p>If you can predict that count and delivery path, you understand callbackFlow.</p><h3>Where we go next</h3><p>BuildPulse can now adapt one CI SDK listener into a safe Flow.</p><p>The next version has three producers:</p><pre>Compiler callback ─┐<br>Test runner callback ├─→ one build timeline<br>Security scanner ──┘</pre><p>Those sources can report concurrently. A basic single callback adapter is no longer the whole problem.</p><p>Next question:</p><blockquote><em>How can several concurrent producers safely send into one Flow?</em></blockquote><p>That is the job of channelFlow.</p><h3>Official references</h3><ul><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/callback-flow.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/callback-flow.html">callbackFlow API</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/await-close.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/await-close.html">awaitClose API</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/try-send.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-send-channel/try-send.html">trySend API</a></li><li><a href="https://kotlinlang.org/docs/coroutines-flow.html">Kotlin Flow guide</a></li></ul><p><em>BuildPulse is one evolving Android/Compose system. Each article introduces only the next concept required by the engineering problem, and each GitHub milestone remains runnable.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a07d4f438dac" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cold Flow — Why Nothing Happens Until collect()]]></title>
            <link>https://medium.com/@sandeep84397/cold-flow-why-nothing-happens-until-collect-927b9b10823d?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/927b9b10823d</guid>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Mon, 31 Aug 2026 07:39:17 GMT</pubDate>
            <atom:updated>2026-08-31T07:39:17.461Z</atom:updated>
            <content:encoded><![CDATA[<p>Cold Flow — Why Nothing Happens Until collect()</p><p><em>A cold Flow is not a running pipeline. It is a reusable description of work — and every collector starts a new execution.</em></p><blockquote><strong><em>BuildPulse series · Article 2 of 9</em></strong></blockquote><blockquote><a href="https://medium.com/@sandeep84397/building-a-live-ci-cd-monitor-why-asynchronous-streams-exist-in-kotlin-264571c42b62"><em>Previous: Why asynchronous streams exist</em></a><em> · </em><strong><em>You are here: Cold Flow</em></strong><em> · Next: </em><em>callbackFlow </em>(unpublished)</blockquote><p>In the first article, BuildPulse fetched one CI/CD status:</p><pre>COMPILING</pre><p>The request was asynchronous and the result was correct. But the build kept moving:</p><pre>QUEUED → COMPILING → RUNNING_TESTS → SECURITY_SCAN → DEPLOYING → SUCCEEDED</pre><p>Our UI did not.</p><p>We proved the original problem: a suspending function can wait efficiently, but it still returns only one value.</p><p>Now we need multiple values. But that requirement immediately creates a second problem.</p><h3>The engineering problem: who owns the repeated work?</h3><p>We could repeatedly fetch snapshots:</p><pre>while (screenIsVisible) {<br>    val snapshot = fetchBuildStatus()<br>    render(snapshot)<br>    delay(1_000)<br>}</pre><p>The code looks small, but the screen now owns several rules:</p><ul><li>when the work starts;</li><li>how values stay ordered;</li><li>when the loop stops;</li><li>what happens when another screen requests the same history;</li><li>how exceptions and cancellation end the operation.</li></ul><p>The real problem is not “how do I write a loop?”</p><p>The problem is:</p><blockquote><em>How do we describe a sequence once, then run that sequence safely whenever a consumer asks for it?</em></blockquote><p>This is where a cold Flow helps.</p><h3>Why is it called cold?</h3><p>The name is a behavior hint.</p><p>Think of a saved CI replay script.</p><p>The script contains every instruction required to replay a build:</p><pre>load build → read QUEUED → read COMPILING → read tests → read deployment</pre><p>Saving that script does not execute a build replay. It only stores the recipe.</p><p>When Developer A presses <strong>Run</strong>, one replay starts.</p><p>When Developer B presses <strong>Run</strong>, another replay starts from the beginning.</p><p>If nobody presses Run, nothing executes.</p><p>That is the reason for the word <strong>cold</strong>: the producer is inactive until a collector starts it.</p><p>Map the analogy directly:</p><p>BuildPulse replay Cold Flow Saved replay script flow { ... } definition Press <strong>Run</strong> Call collect() One replay One Flow execution Replay checkpoints Emitted values Stop the replay Cancel the collecting coroutine</p><p>Memory rule:</p><blockquote><strong><em>flow {} defines the recipe. </em></strong><strong><em>collect() runs the recipe.</em></strong></blockquote><h3>Creating a Flow does not start its producer</h3><p>Consider this small example:</p><pre>val buildHistory = flow {<br>    println(&quot;Producer started&quot;)<br>    emit(&quot;QUEUED&quot;)<br>    emit(&quot;COMPILING&quot;)<br>    emit(&quot;SUCCEEDED&quot;)<br>}</pre><pre>println(&quot;Flow created&quot;)</pre><p>Output:</p><pre>Flow created</pre><p>Producer started is absent.</p><p>Why? The lambda passed to flow {} describes what should happen during collection. Creating buildHistory does not yet invoke that producer block.</p><p>Now collect it:</p><pre>buildHistory.collect { stage -&gt;<br>    println(&quot;UI received $stage&quot;)<br>}</pre><p>Output:</p><pre>Producer started<br>UI received QUEUED<br>UI received COMPILING<br>UI received SUCCEEDED</pre><p>The first terminal operation — collect() here—starts the execution.</p><p>This is called <strong>lazy execution</strong>. “Lazy” does not mean slow. It means the work waits until its result is requested.</p><h3>What happens when two collectors collect the same Flow?</h3><p>This is the part many developers remember incorrectly.</p><p>Run the same object twice:</p><pre>val buildHistory = flow {<br>    println(&quot;New execution&quot;)<br>    emit(&quot;QUEUED&quot;)<br>    emit(&quot;COMPILING&quot;)<br>}</pre><pre>buildHistory.collect { println(&quot;A: $it&quot;) }<br>buildHistory.collect { println(&quot;B: $it&quot;) }</pre><p>Output:</p><pre>New execution<br>A: QUEUED<br>A: COMPILING<br>New execution<br>B: QUEUED<br>B: COMPILING</pre><p>Notice New execution appears twice.</p><p>Collector B does not automatically join Collector A’s earlier execution. The upstream flow {} block runs again for B.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5NFrXn5MyZpPA3pZ.gif" /></figure><p>This gives us the second memory rule:</p><blockquote><strong><em>One cold Flow definition can create many executions — normally one per collector.</em></strong></blockquote><p>This behavior is useful when every consumer needs fresh or independent work. It can be wasteful when the upstream operation is expensive and should be shared. We will solve that later with hot sharing; we should not introduce that machinery before we understand the work being shared.</p><h3>Emission and collection are sequential by default</h3><p>Inside a basic flow {} builder, the producer emits one value at a time:</p><pre>val buildHistory = flow {<br>    emit(BuildStage.QUEUED)<br>    emit(BuildStage.COMPILING)<br>    emit(BuildStage.RUNNING_TESTS)<br>}</pre><p>The collector handles those values in the same order:</p><pre>QUEUED → COMPILING → RUNNING_TESTS</pre><p>The next line in the producer does not leap ahead into a separate concurrent producer merely because Flow is asynchronous. A basic Flow is sequential unless we deliberately introduce operators or builders with different concurrency behavior.</p><p>That gives BuildPulse a clear default:</p><ul><li>one producer execution;</li><li>one ordered sequence;</li><li>one collecting coroutine that owns that execution.</li></ul><p>We are intentionally not adding buffering or concurrency in this article. Those tools solve different problems and change how producer and consumer speed interact.</p><h3>Cancellation: stop the collector, stop that execution</h3><p>Suppose Collector A is replaying a build:</p><pre>QUEUED → COMPILING → RUNNING_TESTS → ...</pre><p>The user leaves the screen after COMPILING.</p><p>If the coroutine running collect() is cancelled, the cold Flow execution is cancelled too. Later values do not keep arriving in that collector.</p><pre>val collectionJob = scope.launch {<br>    buildHistory.collect { stage -&gt;<br>        render(stage)<br>    }<br>}</pre><pre>collectionJob.cancel()</pre><p>This ownership is important. The collection is not a detached loop hidden somewhere else. Its lifetime follows the coroutine that collects it.</p><p>On Android, the UI should normally collect through lifecycle-aware APIs so collection starts and stops with the relevant lifecycle. We are postponing the exact StateFlow and Compose collection APIs until their own articles; the rule to remember now is simpler:</p><blockquote><strong><em>The collecting coroutine owns the cold execution.</em></strong></blockquote><h3>The BuildPulse implementation</h3><p>The repository contract says that BuildPulse can observe a history:</p><pre>fun interface BuildHistoryReader {<br>    fun observeHistory(buildId: BuildId): Flow&lt;BuildSnapshot&gt;<br>}</pre><p>Its implementation defines a cold recipe:</p><pre>class ColdBuildHistoryRepository : BuildHistoryReader {<br>    override fun observeHistory(buildId: BuildId): Flow&lt;BuildSnapshot&gt; = flow {<br>        BuildStage.entries.forEachIndexed { index, stage -&gt;<br>            emit(<br>                BuildSnapshot(<br>                    buildId = buildId,<br>                    stage = stage,<br>                    sequence = index,<br>                ),<br>            )<br>            if (stage != BuildStage.SUCCEEDED) {<br>                delay(700)<br>            }<br>        }<br>    }<br>}</pre><p>Calling observeHistory() creates the Flow. It does not run the loop.</p><p>Collector A starts the loop once. Collector B starts it again. Each receives its own sequence from QUEUED.</p><p>The Android lab keeps both timelines visible so the behavior is harder to forget:</p><pre>Flow defined</pre><pre>Collector A:  QUEUED → COMPILING → RUNNING_TESTS → ...<br>Collector B:  QUEUED → COMPILING → RUNNING_TESTS → ...<br>              ↑ separate execution, not a shared continuation</pre><p>The project is supporting evidence, not required reading:</p><ul><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/tree/article-02-cold-flow">Run the Article 02 checkpoint</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-02-cold-flow/app/src/main/java/io/github/buildpulse/simulation/ColdBuildHistoryRepository.kt">Read the cold repository</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/article-02-cold-flow/app/src/test/java/io/github/buildpulse/simulation/ColdBuildHistoryRepositoryTest.kt">Read the behavior tests</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/compare/article-01-introduction...article-02-cold-flow">Compare Article 01 with Article 02</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/releases/tag/article-02-cold-flow">Open the Article 02 GitHub release</a></li></ul><h3>When should you use a cold Flow?</h3><p>Start by considering a cold Flow when:</p><ul><li>work should begin only when requested;</li><li>each collector should receive a fresh execution;</li><li>the operation naturally produces several ordered values;</li><li>cancellation should follow the collecting coroutine;</li><li>keeping the producer active with zero collectors would waste work.</li></ul><p>Common examples include:</p><ul><li>reading rows from a database query for each request;</li><li>generating a report on demand;</li><li>observing a finite sequence of progress updates for one operation;</li><li>transforming another cold data source;</li><li>replaying BuildPulse history independently for two tools.</li></ul><p>Do not choose it automatically when:</p><ul><li>several screens must observe one already-running source;</li><li>new collectors need the current shared state immediately;</li><li>one expensive upstream connection must be shared;</li><li>each item should be transferred to only one worker.</li></ul><p>Those requirements point toward later parts of our map: hot streams, StateFlow, SharedFlow, sharing operators, or Channel.</p><h3>Common misconceptions</h3><h3>“I assigned the Flow to a variable, so it is running.”</h3><p>No. A cold Flow definition is a recipe. A terminal operation starts it.</p><h3>“Two collectors share the same execution because they use the same Flow object.”</h3><p>Normally no. Each collection invokes the cold producer again.</p><h3>“Cold means slow.”</h3><p>No. Cold describes the producer’s relationship with collectors, not speed.</p><h3>“Flow automatically runs on a background thread.”</h3><p>No. Flow does not imply a particular thread. Coroutine context is a separate rule.</p><h3>“Asynchronous means concurrent.”</h3><p>No. A basic Flow can suspend without blocking while still emitting and collecting sequentially.</p><h3>“Cancelling one collector cancels every collector.”</h3><p>No. Independent cold executions have independent collecting jobs. Cancelling A does not automatically cancel B.</p><h3>The complete mental model</h3><p>When you see a cold Flow, ask four questions:</p><ol><li><strong>Definition:</strong> What recipe is stored inside flow {}?</li><li><strong>Start:</strong> Which terminal operation begins it?</li><li><strong>Execution count:</strong> How many collectors will run the upstream work?</li><li><strong>Lifetime:</strong> Which collecting coroutine cancels each execution?</li></ol><p>For our current BuildPulse history:</p><pre>No collect()          → no replay<br>Collector A starts   → Execution A begins at QUEUED<br>Collector B starts   → Execution B begins at QUEUED<br>Collector A stops    → Execution A stops; B continues</pre><p>If that sequence is clear, you understand the foundation of cold Flow.</p><h3>Where we go next</h3><p>Our current producer is easy because it already uses suspending Kotlin code inside flow {}.</p><p>Real CI SDKs often expose callbacks instead:</p><pre>listener.onBuildChanged { status -&gt; ... }</pre><p>The next limitation is therefore different:</p><blockquote><em>How do we convert a callback that can fire many times into a cold Flow — and guarantee that the listener is removed when collection stops?</em></blockquote><p>That is the job of callbackFlow.</p><h3>Official references</h3><ul><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/flow.html">flow builder API</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/">Kotlin </a><a href="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/">Flow API</a></li><li><a href="https://kotlinlang.org/docs/coroutines-flow.html">Kotlin Flow guide</a></li></ul><p><em>BuildPulse is one evolving Android/Compose system. Each article introduces only the next concept required by the engineering problem, and each GitHub milestone remains runnable.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=927b9b10823d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Live CI/CD Monitor: Why Asynchronous Streams Exist in Kotlin]]></title>
            <link>https://medium.com/@sandeep84397/building-a-live-ci-cd-monitor-why-asynchronous-streams-exist-in-kotlin-264571c42b62?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/264571c42b62</guid>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Mon, 24 Aug 2026 11:46:21 GMT</pubDate>
            <atom:updated>2026-08-31T07:42:11.227Z</atom:updated>
            <content:encoded><![CDATA[<p><em>One evolving engineering problem to understand Flow, StateFlow, SharedFlow, and Channel — before memorizing any API.</em></p><blockquote><strong><em>BuildPulse series · Article 1 of 9</em></strong></blockquote><blockquote><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows"><em>Series repository</em></a><em> · </em><strong><em>You are here: Asynchronous streams</em></strong><em> · Next: C</em>ublished)</blockquote><p>Most explanations of Kotlin Flow begin with flow {} and collect().</p><p>That teaches syntax before it teaches the problem. You may remember how to write a Flow and still be unsure why it exists.</p><p>Let us begin somewhere else: a build that refuses to stand still.</p><h3>A successful request can still produce a broken screen</h3><p>Imagine that we are building <strong>BuildPulse</strong>, an Android dashboard for a CI/CD pipeline.</p><p>A build moves through several stages:</p><pre>QUEUED → COMPILING → RUNNING_TESTS → SECURITY_SCAN → DEPLOYING → SUCCEEDED</pre><p>Our screen calls the build server and receives COMPILING. The request succeeds. No exception occurs. The thread is not blocked. The UI correctly displays COMPILING.</p><p>Five seconds later, the server moves to RUNNING_TESTS.</p><p>The UI still displays COMPILING.</p><p>Nothing is technically wrong with the value we received. It was correct when it arrived. The problem is that we treated a <strong>changing fact</strong> as if it were a <strong>permanent answer</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*KusmfBGMB7-iPIzU.png" /></figure><p>This distinction is the foundation of the complete series.</p><h3>First question: how many answers do we need?</h3><p>Compare these three shapes:</p><pre>fun appName(): String</pre><pre>suspend fun fetchBuildStatus(): BuildStatus</pre><pre>fun observeBuildStatus(): Flow&lt;BuildStatus&gt;</pre><p>They answer different questions.</p><h3>A regular function: one answer now</h3><p>appName() returns one value immediately.</p><h3>A suspending function: one answer later</h3><p>fetchBuildStatus() may pause while waiting for the server. During that pause, the coroutine does not need to block its thread.</p><p>But suspend does not mean “keep sending results.” It changes <strong>how the function waits</strong>, not <strong>how many values it returns</strong>.</p><p>This is the first memory rule:</p><blockquote><strong><em>Suspend means one asynchronous result. Stream means multiple results over time.</em></strong></blockquote><h3>A stream: many answers over time</h3><p>observeBuildStatus() can represent the entire changing sequence:</p><pre>t0        t1           t2              t3          t4<br>QUEUED → COMPILING → RUNNING_TESTS → DEPLOYING → SUCCEEDED</pre><p>The receiver does not repeatedly ask, “What is the answer now?” The producer emits new values as the answer changes.</p><h3>Why not call the suspending function repeatedly?</h3><p>We could poll:</p><pre>while (screenIsVisible) {<br>    render(fetchBuildStatus())<br>    delay(2_000)<br>}</pre><p>Polling is sometimes valid. It is not the same as observing a stream.</p><p>It immediately creates new questions:</p><ul><li>What if the status changes twice during the two-second delay?</li><li>What if thousands of clients poll the server together?</li><li>Who stops the loop when the screen disappears?</li><li>How are errors retried?</li><li>What if a new request starts before the previous request finishes?</li><li>What if two screens need the same build updates?</li></ul><p>Repeatedly requesting snapshots does not automatically create a well-defined stream. We still need rules for production, cancellation, sharing, delivery, and speed differences.</p><h3>What exactly is an asynchronous stream?</h3><p>An asynchronous stream is a sequence whose values can become available at different moments.</p><p>Break the name into parts:</p><ul><li><strong>Asynchronous:</strong> the consumer does not expect every value to be available immediately.</li><li><strong>Stream:</strong> values pass through over time rather than appearing as one permanent result.</li></ul><p>A stream is not necessarily fast. It is not necessarily infinite. It does not necessarily use a network. A database query, sensor, timer, callback, WebSocket, and simulated build can all become stream producers.</p><p>In Kotlin coroutines, Flow&lt;T&gt; is the primary abstraction for representing such values declaratively.</p><p>But saying “use Flow” is still incomplete. We need to understand how the producer and consumers relate.</p><h3>The four questions behind every stream choice</h3><p>Before choosing Flow, StateFlow, SharedFlow, or Channel, ask:</p><ol><li><strong>Who starts the producer?</strong></li><li><strong>Does the producer continue without observers?</strong></li><li><strong>Should every observer receive the value, or only one receiver?</strong></li><li><strong>Should a late observer receive an old or current value?</strong></li></ol><p>Cold streams, hot streams, and channels are different answers to these questions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1U8yXyXuEAsjwMJd.png" /></figure><h3>Cold stream: work that waits for a collector</h3><p>Why the name <strong>cold</strong>?</p><p>Think about an engine that has not been started. The machine exists, but no work happens until someone turns it on.</p><p>A cold stream behaves similarly:</p><ul><li>Creating it normally does not start the producer.</li><li>Collection starts the work.</li><li>A second collector usually starts another independent execution.</li><li>When nobody collects, that execution is not running.</li></ul><figure><img alt="Animated Cold Flow timeline: no work runs before collect; Collector A and Collector B each start independent executions and receive 1, 2, 3." src="https://cdn-images-1.medium.com/max/1024/1*b0KVmxw_tS9y198-bNDsXQ.gif" /></figure><p>Inside BuildPulse, “generate a build-history report for this screen” could be cold. Each collector asks for its own execution when needed.</p><p>Later articles will separate three cold-flow tools:</p><ul><li>flow {} for sequential suspending production.</li><li>callbackFlow for adapting callback APIs.</li><li>channelFlow for concurrent producers inside one cold Flow.</li></ul><p>Important: callbackFlow and channelFlow contain the word “channel,” but the objects they return are still cold Flows. Their names describe how values enter the builder, not a change from cold to hot.</p><h3>Hot stream: an active source that observers can join</h3><p>Why the name <strong>hot</strong>?</p><p>A running build is already producing activity. Opening or closing the dashboard does not start or stop the compiler on the CI server.</p><p>That source is active independently of one particular observer.</p><p>A hot stream commonly behaves like this:</p><ul><li>The source can exist without a collector.</li><li>Multiple collectors can observe the same ongoing source.</li><li>A late collector may miss earlier values unless replay or current-state behavior is configured.</li><li>Removing one collector does not necessarily stop the source.</li></ul><figure><img alt="Animated StateFlow timeline: the producer updates IDLE to COMPILING to RUNNING_TESTS, while Collectors A and B subscribe and observe the current and future states." src="https://cdn-images-1.medium.com/max/1024/1*411ERYvJVPzzfUIPlZoYtw.gif" /></figure><p>BuildPulse has two distinct hot-stream needs:</p><ul><li><strong>Current build state:</strong> “What stage is the build in now?” This points toward StateFlow.</li><li><strong>Broadcast activity:</strong> “Test 47 failed” or “Deployment started.” This may point toward SharedFlow.</li></ul><p>The words <em>state</em> and <em>shared</em> are clues. StateFlow represents a current state. SharedFlow shares emitted values among subscribers with configurable replay and buffering.</p><p>We will examine their exact rules later. For now, remember that “hot” describes the producer’s relationship with observers — not temperature, speed, or importance.</p><h3>Channel: transfer, not shared observation</h3><p>A Channel belongs on the same learning map, but it is not a subtype of Flow.</p><p>Why the name <strong>channel</strong>?</p><p>A physical channel connects two sides and gives something a route through which to travel. A coroutine Channel similarly connects senders and receivers.</p><p>In BuildPulse, imagine a queue of build jobs:</p><pre>Build 101 ─┐<br>Build 102 ─┼──▶ job channel ──▶ available workers<br><br>Build 103 ─┘</pre><figure><img alt="Animated Channel timeline: build jobs 101, 102, and 103 wait in a queue and each goes to one ready worker based on READY or BUSY status." src="https://cdn-images-1.medium.com/max/1024/1*3QoY7FdowLfMwiitbwzWtA.gif" /></figure><p>The goal is usually work transfer. One worker receives a job and processes it. We do not normally want every worker to execute the same build.</p><p>That differs from a hot broadcast stream, where multiple observers may need the same update.</p><p>Memory rule:</p><blockquote><strong><em>Flow describes values to observe. Channel transfers values between coroutines.</em></strong></blockquote><p>This is a useful default, not a law for every advanced design. Kotlin provides bridges between the two abstractions, which we will cover only after their individual semantics are clear.</p><h3>The complete BuildPulse map</h3><ul><li><strong>Fetch build status once → </strong><strong>suspend function:</strong> one result is required later.</li><li><strong>Request an independent history report → Cold </strong><strong>Flow:</strong> work begins for each collector.</li><li><strong>Adapt CI SDK listeners → </strong><strong>callbackFlow:</strong> callbacks need structured cancellation and cleanup.</li><li><strong>Merge compiler, test, and scanner producers → </strong><strong>channelFlow:</strong> several coroutines produce concurrently.</li><li><strong>Hold the current pipeline snapshot → </strong><strong>StateFlow:</strong> new observers need the latest state.</li><li><strong>Broadcast logs and transient activity → </strong><strong>SharedFlow:</strong> several observers may receive the same emission.</li><li><strong>Share one expensive upstream connection → </strong><strong>stateIn / </strong><strong>shareIn:</strong> cold work becomes shared hot observation.</li><li><strong>Distribute build jobs to workers → </strong><strong>Channel:</strong> each job should be transferred to a receiver.</li></ul><p>This table is our series contract. We will not swap analogies in every article. We will keep solving this one system, one limitation at a time.</p><h3>Try the Phase 1 experiment</h3><p>The companion Android project intentionally contains no production Flow implementation yet.</p><p>It presents two values:</p><ul><li><strong>Server now:</strong> the simulator’s current build stage.</li><li><strong>UI snapshot:</strong> the last value returned by the suspending read.</li></ul><p>Try this sequence:</p><ol><li>Select <strong>Fetch snapshot</strong>. Both values show QUEUED.</li><li>Select <strong>Advance server</strong>. The server changes to COMPILING.</li><li>Notice that the UI snapshot remains QUEUED.</li><li>Fetch again. Both values match.</li><li>Advance twice without fetching. The gap becomes obvious again.</li></ol><p>The repository is an optional lab, not a prerequisite for understanding this article:</p><ul><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows">Run BuildPulse</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/main/app/src/main/java/io/github/buildpulse/simulation/BuildContracts.kt">Read the one-shot contract</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/blob/main/app/src/test/java/io/github/buildpulse/simulation/InMemoryBuildSimulatorTest.kt">See the stale-snapshot test</a></li><li><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/releases/tag/article-01-introduction">Milestone: </a><a href="https://github.com/sandeep84397/buildpulse-kotlin-flows/releases/tag/article-01-introduction">article-01-introduction</a></li></ul><h3>Common misconceptions</h3><h3>“If a function is suspend, it keeps observing changes.”</h3><p>No. A suspending function can pause and later return one result. Observation requires another contract.</p><h3>“Flow means background thread.”</h3><p>No. Flow describes asynchronous value delivery. Execution context is a separate concern.</p><h3>“All Flow objects are cold.”</h3><p>No. Many standard Flow builders are cold, while StateFlow and SharedFlow are hot. The Flow interface itself does not encode coldness in its type.</p><h3>“Channel is just another Flow.”</h3><p>No. They have different primary semantics. Flow focuses on observation; Channel focuses on communication and transfer.</p><h3>“Hot is better because it is already running.”</h3><p>No. Hot and cold are behavior choices. Starting unnecessary work early can waste resources; repeating expensive cold work for many collectors can also waste resources.</p><h3>Check your mental model</h3><p>Before continuing, answer these without looking back:</p><ol><li>Does suspend mean one value or many values?</li><li>Who normally starts a cold stream?</li><li>Can a hot source exist without your screen?</li><li>If one job should go to one worker, would you first investigate broadcast Flow or Channel semantics?</li><li>Which question matters more: “Is Flow modern?” or “What delivery behavior does this problem require?”</li></ol><p>If the reasoning feels clear, the later APIs become names for behaviors you already understand.</p><h3>Where the analogy stops</h3><p>BuildPulse is a learning system, not a complete definition of coroutines.</p><p>Real stream behavior depends on the builder and operators used. Buffering, cancellation, exception transparency, context preservation, replay, lifecycle, and backpressure require exact API rules. We will introduce each rule when the project first needs it rather than pretending one diagram explains everything.</p><h3>Learning roadmap</h3><pre>[01] Why asynchronous streams exist          ← You are here<br>  ↓<br>[02] Cold Flow and collection<br>  ↓<br>[03] callbackFlow and listener cleanup<br>  ↓<br>[04] channelFlow and concurrent producers<br>  ↓<br>[05] Hot streams and shared producers<br>  ↓<br>[06] StateFlow vs SharedFlow<br>  ↓<br>[07] stateIn vs shareIn<br>  ↓<br>[08] Channel and worker communication<br>  ↓<br>[09] Final decision guide and complete BuildPulse</pre><p>Next, we will replace repeated BuildPulse snapshots with a cold Flow and answer two questions precisely:</p><blockquote><em>When does a Flow actually start, and what happens when two collectors observe it?</em></blockquote><h3>Official references</h3><ul><li><a href="https://kotlinlang.org/docs/coroutines-overview.html">Kotlin coroutines overview</a></li><li><a href="https://kotlinlang.org/docs/flow.html">Kotlin Flow guide</a></li><li><a href="https://kotlinlang.org/api/kotlinx.coroutines/">kotlinx.coroutines API</a></li><li><a href="https://developer.android.com/kotlin/flow/stateflow-and-sharedflow">Android guidance for StateFlow and SharedFlow</a></li></ul><p><strong>Series navigation</strong></p><p>Previous: Start here · <a href="https://github.com/sandeep84397/buildpulse-kotlin-flows">Series repository</a> · Next: Cold Flow</p><p><strong>Continue learning:</strong> <a href="https://medium.com/@sandeep84397/cold-flow-why-nothing-happens-until-collect-927b9b10823d">Cold Flow — Why Nothing Happens Until collect()</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=264571c42b62" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Offline-First Feed · Part 2 — Low-Level Design]]></title>
            <link>https://medium.com/@sandeep84397/offline-first-feed-part-2-low-level-design-bc47ef2b0289?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/bc47ef2b0289</guid>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[android-development]]></category>
            <category><![CDATA[kotlin-multiplatform]]></category>
            <category><![CDATA[programming]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Sat, 16 May 2026 19:19:53 GMT</pubDate>
            <atom:updated>2026-05-16T19:19:53.156Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kMJASwC8eYfYzeP_XDOfRg.png" /></figure><p><strong><em>Part 1 promised this article. Here it is. The exact piece of code that turns a network and a database into an offline-first feed.</em></strong></p><blockquote><strong>Series:</strong></blockquote><blockquote>— <a href="https://medium.com/@sandeep84397/building-an-offline-first-feed-in-kotlin-multiplatform-part-1-the-high-level-design-42f928e4f186">Part 1 — The High-Level Design</a></blockquote><blockquote>— Part 2 — This one. RemoteMediator orchestration.</blockquote><blockquote>— Part 3 (coming) — The sync state machine for write path.</blockquote><p>Part 1 covered the architecture: KMP + Compose + SQLDelight + Paging 3 + Ktor + Koin. The DB is the source of truth. The network seeds it. The UI never waits on the network.</p><p>The hand-wave was: <em>“and a </em><em>RemoteMediator makes this work.&quot;</em></p><p>This post earns that hand-wave. We walk through one class — FeedRemoteMediator — line by line, plus the two helpers around it (FeedPagingSource and Pager). By the end you&#39;ll know exactly how a user pulls down on a feed and 20 fresh posts appear in their local DB without anyone writing imperative code to make that happen.</p><h3>A note on scope</h3><p>Part 1’s functional requirements split into two delivery groups for Phase 2:</p><ul><li><strong>Read path (this post):</strong> F1–F5. The mediator-paging-source machinery that powers the feed. Already in code.</li><li><strong>Write path (Part 3):</strong> F6 and F7 — “create post → optimistic insert” and “like/unlike → optimistic toggle.” Lands when the implementation does.</li></ul><p>So <strong>Phase 2 ships as two articles, not one.</strong> This is the read-path LLD Part 1 explicitly promised. The write-path LLD comes after the code is in.</p><h3>The three actors</h3><p>Three Paging 3 classes do all the work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pNbPuhzyi7gMm3W_2yecRw.png" /></figure><p>Each has one job:</p><ul><li><strong>FeedPagingSource</strong> — reads paged rows from the local DB. Returns LoadResult.Page. Knows nothing about the network.</li><li><strong>FeedRemoteMediator</strong> — bridges remote API and local DB. Decides <strong>when</strong> to fetch and <strong>what to write</strong>.</li><li><strong>Pager</strong> — glue. Wires the two together. Exposes a feed flow to the UI.</li></ul><p>The clean separation matters. <strong>FeedPagingSource is the read path. </strong><strong>FeedRemoteMediator is the write path from the server&#39;s perspective.</strong> They never call each other directly.</p><h3>Wiring it together: the Pager</h3><p>The actual FeedRepositoryImpl is one chained expression. For the walkthrough, here it is split into named variables so each piece is independent.</p><p><strong>Step 1 — page config:</strong></p><pre>val config = PagingConfig(pageSize = 20, enablePlaceholders = false, )</pre><p><strong>Step 2 — the network bridge:</strong></p><pre>val mediator = FeedRemoteMediator(db = db, api = api, pageSize = 20, )</pre><p><strong>Step 3 — a factory for the DB-backed reader:</strong></p><pre>val sourceFactory = {FeedPagingSource( db = db, pageSize = 20, ) }</pre><p>Why a factory (a lambda) and not just a FeedPagingSource instance: PagingSource instances aren&#39;t reusable across refreshes. Paging 3 may need to build a fresh one on demand.</p><p><strong>Step 4 — the pager wires it all together:</strong></p><pre>val pager = Pager(config = config, remoteMediator = mediator, pagingSourceFactory = sourceFactory, )</pre><p><strong>Step 5 — return a flow of domain models:</strong></p><pre>return pager.flow.map { pagingData -&gt;pagingData.map { row -&gt; row.toDomain() } }</pre><p>The .map chain converts each DB row into a domain Post. That mapping happens lazily per item — only items the UI actually renders get mapped.</p><p>This returns a paged flow of Post items. The Composable subscribes to it. <strong>The UI now has reactive, paginated, network-backed feed data with five named steps you can read top-to-bottom.</strong></p><h3>The simple half: FeedPagingSource</h3><p>FeedPagingSource reads from the local DB. That&#39;s all.</p><p><strong>The class signature:</strong></p><pre>class FeedPagingSource(private val db: FeedDatabase, private val pageSize: Int, ) : BasePagingSource&lt;Int, SelectPaged&gt;()</pre><p>The loadPage function has four steps.</p><p><strong>Step 1 — read where to start.</strong> First call has params.key = null so we start at 0:</p><pre>val offset = params.key ?: 0<br>val limit = params.loadSize</pre><p><strong>Step 2 — run the SQL.</strong> selectPaged is generated by SQLDelight from a .sq file:</p><pre>val rows = db.postQueries.selectPaged( limit = limit.toLong(), offset = offset.toLong(), ) .executeAsList()</pre><p><strong>Step 3 — compute the page keys.</strong> nextKey = null when we got fewer rows than asked (we hit the end). prevKey = null when we&#39;re at offset 0:</p><pre>val hasMore = rows.size == limit<br>val nextKey = if (hasMore) { offset + limit } else { null }<br>val prevKey = if (offset == 0) { null } else { maxOf(0, offset - limit) }</pre><p><strong>Step 4 — return.</strong> Paging 3 stores the keys for the next call:</p><pre>return LoadResult.Page(data = rows, prevKey = prevKey, nextKey = nextKey, )</pre><p>Each returned page carries three things: 20 rows of data, the previous-page key, and the next-page key. Paging 3 uses the keys to call back into loadPage for the next page when the user scrolls near the bottom.</p><p><strong>Note what </strong><strong>FeedPagingSource doesn&#39;t do:</strong> it doesn&#39;t call the network. It doesn&#39;t insert anything. If the DB has 0 posts, this returns 0 posts. The network&#39;s job — seeding the DB — belongs to the next actor.</p><h3>The interesting half: FeedRemoteMediator</h3><p><strong>The class signature:</strong></p><pre>class FeedRemoteMediator(<br>private val db: FeedDatabase,<br>private val api: FakeFeedApi,<br>private val pageSize: Int = 20,<br>) : BaseRemoteMediator&lt;Int, SelectPaged&gt;()</pre><p><strong>The </strong><strong>loadPage function, four steps:</strong></p><pre>override suspend fun loadPage(<br>loadType: LoadType, <br>state: PagingState&lt;Int, SelectPaged&gt;, <br>): MediatorResult {<br>val offset = resolveOffset(loadType) ?: return endOfPagination()<br>val page = api.fetchFeed( offset = offset, limit = pageSize, )<br>writeToDatabase(loadType, offset, page)<br>return MediatorResult.Success( endOfPaginationReached = page.nextOffset == null, ) }</pre><p>What the four steps do, in order:</p><ul><li><strong>resolveOffset</strong> — figure out where to fetch from. Returns null if there&#39;s nothing left to fetch.</li><li><strong>api.fetchFeed</strong> — call the network.</li><li><strong>writeToDatabase</strong> — write the response to the DB in one transaction.</li><li><strong>MediatorResult.Success</strong> — tell Paging 3 whether more pages exist.</li></ul><p>Each helper is small. We cover them below.</p><h3>Thing 1: The LoadType decision</h3><p>Step 1’s helper. Returns the offset to fetch, or null to mean &quot;stop&quot;:</p><pre>private fun resolveOffset(<br>loadType: LoadType, <br>): Int? = when (loadType) { <br>LoadType.REFRESH -&gt; 0 <br>LoadType.PREPEND -&gt; null<br>LoadType.APPEND -&gt; readCursor()<br>}</pre><p>PREPEND returns null because feeds don&#39;t scroll up — explained two paragraphs down.</p><p>The cursor read is its own helper:</p><pre>private fun readCursor(): Int? {<br>val cursor = db.remoteKeyQueries.selectById(FEED_REMOTE_KEY_ID).executeAsOneOrNull()<br>return cursor?.nextOffset?.toInt()<br>}</pre><p>When resolveOffset returns null, the caller turns that into a success result with endOfPaginationReached = true.</p><p>Three LoadTypes, three behaviours:</p><ul><li><strong>REFRESH</strong> — user pulled to refresh, or first time loading. Start from offset 0.</li><li><strong>APPEND</strong> — user scrolled near the bottom. Continue from where we left off (stored in RemoteKey).</li><li><strong>PREPEND</strong> — user scrolled up past the top. Feeds don’t have content above the newest, so we short-circuit.</li></ul><p>The PREPEND short-circuit is one of those “obvious in retrospect” things. A feed of <em>the latest posts</em> has no “before the top.” Returning endOfPaginationReached = true for PREPEND tells Paging 3 not to bother asking again.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ixPk6N55l5qdW14Z8ervCQ.png" /></figure><h3>Thing 2: The cursor lives in the DB</h3><p>The readCursor helper reads from a tiny one-row table that stores &quot;where did we leave off?&quot;</p><pre>CREATE TABLE RemoteKey (<br>id TEXT NOT NULL PRIMARY KEY, <br>nextOffset INTEGER, <br>prevOffset INTEGER, <br>fetchedAt INTEGER NOT NULL <br>);</pre><p>Three things worth noting about the schema:</p><ul><li><strong>id</strong> is always the literal &quot;feed&quot; for this app — there&#39;s only ever one cursor row.</li><li><strong>nextOffset</strong> is nullable. null means we&#39;ve reached the end of the feed; no more pages to fetch.</li><li><strong>fetchedAt</strong> is the millisecond timestamp of the last successful refresh. We don&#39;t read it yet, but we will (see the freshness-window aside below).</li></ul><p>The cursor doesn’t live in memory. It lives in SQLite. <strong>The app can be killed at any point and the next launch will pick up exactly where it left off.</strong> No client state to recover.</p><p>This is also why offline-first apps tend to feel “magical” — they never lose their place.</p><h3>Thing 3: The network call</h3><pre>val page = api.fetchFeed(offset = offset, limit = pageSize, )</pre><p>One call. The API client returns 20 posts plus a nextOffset. If anything throws — timeout, parse error, HTTP 500 — it propagates up to the outer try/catch in the :core module, which turns it into a MediatorResult.Error. Paging 3 surfaces that as an error state in the UI.</p><p><strong>No retries here.</strong> Retry is a separate concern — Phase 1 has none, Phase 2 will introduce it for the write path (Part 3 of this series).</p><h4>Wait — does this hit the network every time?</h4><p>A natural question. The answer has two parts.</p><p><strong>Yes</strong>, every time loadPage runs, it calls the network. There&#39;s no in-mediator cache check.</p><p><strong>No</strong>, loadPage doesn&#39;t run on every screen render. Paging 3 only calls the mediator when:</p><ul><li>The user pulls to refresh (LoadType.REFRESH)</li><li>The user scrolls near the bottom of loaded data (LoadType.APPEND)</li><li>The cached data is empty (so it has to fetch a first page)</li></ul><blockquote>Scrolling back up to already-loaded posts: no mediator call.</blockquote><blockquote>Closing and reopening the app: no mediator call (cached data renders from SQLite via FeedPagingSource).</blockquote><blockquote>Returning endOfPaginationReached = true permanently stops APPEND until the next REFRESH.</blockquote><p>So <strong>the feed feels instant on cold start because the DB is the cache.</strong> The mediator only runs on intentional user actions.</p><p>A future improvement (out of scope for Phase 2) is to add a freshness window to the REFRESH path:</p><pre>val skip = loadType == LoadType.REFRESH &amp;&amp; cursorIsFreshEnough()<br>if (skip) { <br>return MediatorResult.Success( endOfPaginationReached = false, ) <br>}</pre><p>User pulls to refresh twice in 10 seconds → second pull skips the network. Costs one query, saves a round-trip. The RemoteKey table already stores fetchedAt for exactly this reason; we just don&#39;t read it yet.</p><p>For Phase 1, simplicity wins: every REFRESH hits the network. Real backends will need the freshness check.</p><h3>Thing 4: The transaction</h3><p>Step 3’s helper. <strong>This is the most important block in the whole class.</strong></p><p>The orchestrator runs three steps inside one transaction:</p><pre>private fun writeToDatabase(<br>  loadType: LoadType,<br>  offset: Int,<br>  page: FeedPageDto, <br>) { <br>db.transaction { <br>    clearCursorIfRefresh(loadType) <br>    upsertPosts(page.posts)<br>    updateCursor(page.nextOffset) <br>  } <br>}</pre><p>Each step is its own small helper.</p><p><strong>Helper 1 — clear the cursor on REFRESH only.</strong> We start fresh so APPEND can’t read a stale offset:</p><pre>private fun clearCursorIfRefresh(loadType: LoadType) {<br> if (loadType == LoadType.REFRESH) {<br>   db.remoteKeyQueries .deleteById(FEED_REMOTE_KEY_ID)<br> }<br>}</pre><p><strong>Helper 2 — write each post and its author.</strong> insertOrReplace makes both calls idempotent:</p><pre>private fun upsertPosts(posts: List&lt;PostDto&gt;, ) {<br> posts.forEach { dto -&gt; <br>  db.userQueries.insertOrReplace( // user fields )<br>  db.postQueries.insertOrReplace( // post fields )<br> }<br>}</pre><p><strong>Helper 3 — update the cursor.</strong> nextOffset = null means we&#39;ve reached the end:</p><pre>private fun updateCursor(nextOffset: Int?, ) {<br> val now = Clock.System.now() .toEpochMilliseconds()<br>db.remoteKeyQueries.insertOrReplace( id = FEED_REMOTE_KEY_ID, nextOffset = nextOffset?.toLong(), fetchedAt = now, ) }</pre><p>The actual file inlines all of this. Naming the steps makes the read order obvious: <strong>clear, write, update cursor — all atomic.</strong></p><p>If any step fails — DB exception, disk full, anything — the entire transaction rolls back. <strong>There is no “I inserted 15 of 20 posts and then crashed” state.</strong></p><p>This is the offline-first guarantee at the database level: <strong>either a full page lands or nothing does.</strong> No partial state, no orphaned rows, no torn writes.</p><p>If the app dies mid-transaction, SQLite’s atomicity ensures the next launch sees the pre-transaction state. The user pulls down again, the mediator retries, and we try again from offset 0. Idempotent because insertOrReplace writes the same data the same way every time.</p><h3>Thing 5: Tell Paging 3 we’re done</h3><pre>return MediatorResult.Success(endOfPaginationReached = page.nextOffset == null, )</pre><p>Three states the mediator can return:</p><ul><li><strong>Success with </strong><strong>endOfPaginationReached = false</strong> — got data, more pages available.</li><li><strong>Success with </strong><strong>endOfPaginationReached = true</strong> — got data (or didn&#39;t), no more pages.</li><li><strong>Error</strong> — something failed.</li></ul><p>Paging 3 caches the “true” signal and won’t ask APPEND again. The user can still REFRESH from the top — that resets everything.</p><h3>A full pull-to-refresh, end to end</h3><p>Here’s what happens when a user pulls down on the feed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x0kU9Q_1vWQ-KZ8y__ttLg.png" /></figure><p>Six hops. Look at the ordering carefully:</p><ol><li><strong>The user’s pull triggers REFRESH.</strong></li><li><strong>The mediator runs first</strong> — it talks to the network, writes the DB.</li><li><strong>The paging source runs second</strong> — it reads from the DB Paging 3 just had the mediator populate.</li><li><strong>The UI gets pages of DB rows</strong> — which get mapped to domain Post objects.</li></ol><p>The crucial property: <strong>the paging source doesn’t know the network was just hit.</strong> It just reads whatever’s in the DB. If the mediator failed, the paging source still happily returns whatever was there before — that’s why offline-first apps still show cached content on network failure.</p><h3>The pattern from Part 1, made concrete</h3><p>Part 1 said:</p><blockquote>The DB is the source of truth. Network seeds it. UI never waits on the network.</blockquote><p>Now you can see where each rule lives in code:</p><ul><li><strong>DB is the source of truth</strong> — FeedPagingSource reads only from DB.</li><li><strong>Network seeds the DB</strong> — FeedRemoteMediator.loadPage is the only place network-to-DB writes happen.</li><li><strong>UI never waits on the network</strong> — UI subscribes to a feed flow that emits from DB; the mediator runs in parallel, not in series.</li></ul><p>That third rule is the most important and the most often violated. In a naive design, the UI would call loadFeed() which calls the network which writes the DB which then triggers a redraw. Paging 3 inverts this: the UI subscribes to DB-backed pages, and the mediator runs whenever Paging 3 decides it should — invisible to the UI thread.</p><p><strong>The user never sees a loading state because they’re always looking at the DB, never the network.</strong></p><h3>What I’d skip if I were starting over</h3><p>Three things I overthought:</p><ol><li><strong>Don’t build a generic mediator abstraction first.</strong> The BaseRemoteMediator in :core was extracted <em>after</em> I had FeedRemoteMediator working. Doing it the other way around forces premature decisions about retry semantics, PREPEND handling, error wrapping. Build the concrete one, then extract.</li><li><strong>Don’t try to handle PREPEND.</strong> A reverse-chronological feed has no “older than the top.” Return endOfPaginationReached = true for PREPEND and move on. I wasted two hours trying to implement a meaningful PREPEND before realising it was meaningless.</li><li><strong>Don’t put network calls inside the transaction.</strong> I almost did. The temptation: “what if I write to DB only if network and DB both succeed?” The reality: SQLite holds the DB lock for the entire transaction. Hold it during a slow network call and you block every other DB operation. Fetch first, transact second.</li></ol><h3>The one-line takeaway</h3><p>Part 1 told you “the DB is the source of truth, the network seeds it.” The mechanism for that promise is one class with a clear contract:</p><p><strong>RemoteMediator.load(loadType) fetches network data and writes the DB. </strong><strong>PagingSource.load(params) reads the DB. The two never talk to each other directly. Paging 3 orchestrates them.</strong></p><p>That’s the whole pattern. Once you see it, everything else is detail.</p><h3>What’s next</h3><p><strong>Part 3</strong> will be about the write path — what happens when the user <em>creates</em> a post offline. The state machine, the PendingOperation table, and the one-line trick that makes sync provably never duplicate posts.</p><p>The repo is here: <a href="https://github.com/sandeepdhami/OfflineFirstFeed">github.com/sandeepdhami/OfflineFirstFeed</a>.</p><p>If you spot a hole in the reasoning or know a case the mediator doesn’t handle, drop a comment.</p><p><em>Series:</em></p><p><em>— </em><a href="https://medium.com/@sandeep84397/building-an-offline-first-feed-in-kotlin-multiplatform-part-1-the-high-level-design-42f928e4f186"><em>Part 1 — The High-Level Design</em></a></p><p><em>— Part 2 — This article</em></p><p><em>— Part 3 — The sync state machine (coming)</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bc47ef2b0289" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What suspend Actually Does (Spoiler: It Doesn't Pause Your Function)]]></title>
            <link>https://medium.com/@sandeep84397/what-suspend-actually-does-spoiler-it-doesnt-pause-your-function-863bcab63798?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/863bcab63798</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[coroutine]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Mon, 11 May 2026 15:19:58 GMT</pubDate>
            <atom:updated>2026-05-11T15:25:59.829Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5uY0joCYKlnBzZLZ_WbDOw.png" /></figure><h3>“The Secret of Lady Continuance” — what suspend actually does, byte for byte</h3><p>In Episode 1, I told you that suspend is a permission slip, not a teleporter. That was the <em>what</em>. Today is the <em>how</em>.</p><p>By the end of this episode, you’ll know exactly what the Kotlin compiler does to your nice linear suspend fun to make it pause and resume across thread boundaries. You&#39;ll see the hidden parameter it adds. You&#39;ll see the state machine it generates. You&#39;ll watch — line by line — how the main thread becomes free while your network call is still in flight.</p><p>And you’ll never look at viewModelScope.launch { ... } the same way again.</p><p>If you missed Episode 1, <a href="https://medium.com/@sandeep84397/coroutines-a-game-of-threads-episode-1-d54e05335c3a">start here</a> — we set up the cast and the world. This episode assumes you know who Coro Targaryen and Lord Threadon Stark are.</p><blockquote><strong><em>TL;DR — What you’ll take away from Episode 2</em></strong></blockquote><blockquote>A suspend function is silently rewritten by the compiler into a state machine.</blockquote><blockquote>Every suspend function gets a hidden last parameter: Continuation — Lady Continuance herself.</blockquote><blockquote>“Suspending” is not pausing. The function <em>literally returns</em>, frees the thread, and gets <em>called again later</em>.</blockquote><blockquote>This is Continuation Passing Style (CPS). It’s how coroutines work without any runtime magic.</blockquote><h3>Recap: meet the cast</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*iGan7jRaEXLuGxm0JcCcEQ.png" /></figure><p>The two characters who matter today:</p><p><strong>Maester Suspendos</strong> — the suspend keyword. He is the wise old maester who knows how to pause the kingdom&#39;s quests. But he doesn&#39;t do the pausing himself. He hands a parchment to someone who does.</p><p><strong>Lady Continuance</strong> — a Continuation. She carries the parchment. On it: where Coro left off, every local variable Coro had in flight, and what to do when the answer comes back. She is the most important — and most invisible — character in this entire series.</p><h3>The illusion you’ve been writing for years</h3><p>Here’s a tiny Kotlin program. The main function launches a coroutine that loads user data, and then keeps doing other work on the main thread:</p><pre>fun main() = runBlocking {<br>    launch {<br>        loadUserData()<br>    }<br>    println(&quot;main thread keeps working&quot;)<br>    renderUI()<br>}</pre><pre>suspend fun loadUserData() {<br>    val user  = api.getUser()              // suspends<br>    val posts = api.getPosts(user.id)      // suspends<br>    println(&quot;loaded &quot; + posts.size)<br>}</pre><p>Reads like a recipe. Top to bottom. Each line waits for the previous one.</p><p>The fact that each api.* call might suspend for hundreds of milliseconds — <em>while the main thread does other work</em> — is completely hidden from you. That hiding is the magic.</p><p>The magic is also a lie.</p><p>Because at runtime, <strong>this function does not exist as you wrote it</strong>. The Kotlin compiler shreds it, rebuilds it as a state machine, and hands the rebuild to the JVM. Let me show you.</p><h3>The compiler’s trick</h3><p>Look at loadUserData above. It has two suspension points — two places where it might have to pause and wait. The compiler treats each suspension point as a <em>boundary</em>, like the lines on a board game. Between any two boundaries, the code runs synchronously.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*32Yjy1B3qPCArdY_9LTdHA.png" /></figure><p>That diagram is the conceptual transformation: linear code on the left, three labeled states on the right. Each suspension point becomes a label. The function can re-enter at any label, depending on which one was last saved.</p><p>Here’s the part most people don’t realize: the function is invoked <strong>once per state transition</strong>. Not once total. When getUser() suspends, your function literally returns. Done. The thread is freed. Sometime later, when getUser() finishes, the function is invoked <em>again</em> — but this time, it jumps directly to label 1 instead of starting over.</p><p>And the thing that knows which label to jump to, and what local variables to restore? Lady Continuance.</p><h3>The single sentence that kills the confusion</h3><p>Before we go any deeper, I need to give you the one sentence that ends the confusion most developers have about coroutines.</p><blockquote><strong><em>A coroutine doesn’t pause execution. A coroutine returns, gets called again, and uses a Continuation to remember where it was.</em></strong></blockquote><p>Read it twice. That’s the whole thing.</p><p>When we say a suspend function &quot;suspends,&quot; we mean it returns the special value COROUTINE_SUSPENDED to its caller and unwinds the stack. The thread is freed. The function is <em>gone</em> from the call stack. The only thing that survives is the Continuation object on the heap, holding the label and any local variables that need to be remembered.</p><p>When we say it “resumes,” we mean somebody — the network library, a coroutine dispatcher, anyone holding the Continuation — calls continuation.resumeWith(result). Internally, this invokes the suspend function <strong>again</strong>, passing the same Continuation. The function looks at the label, jumps to the matching when case, restores its locals, and runs forward.</p><p>That’s it. That’s all that’s happening.</p><h3>A second analogy in case GoT doesn’t click</h3><p>Think of a suspend function as a <strong>video game save file</strong>.</p><p>You play through level 1. You hit a save point. You save. You quit the game. The console powers off.</p><p>Days later, you come back. You load the save file. The game starts up again, reads the save, and puts you back at the save point with all your inventory restored.</p><p>The game <em>did not stay running</em> during those days. The save file did not stay in RAM. Everything was reconstructed from the save file when you loaded it.</p><p>That’s exactly what a Continuation is — <strong>a save file</strong>. When the function “suspends,” it writes the save and exits. When it “resumes,” the function is launched from scratch and the save file tells it which level to load. The function has no memory of running before — it only has the Continuation to read from.</p><p>This is why a coroutine can resume on a different thread than it suspended on. The thread doesn’t matter. The save file is all that matters.</p><h3>What the bytecode actually looks like</h3><p>Here’s the part that’s going to feel like a magic trick. The clean code on the left is what you wrote. The code on the right is a simplified version of what the Kotlin compiler actually generates, in JVM bytecode form:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1hs7Qs4uoXlmtgje6JfJuA.png" /></figure><p>A few things worth pointing out in that generated code:</p><p>The function signature is different. Your suspend fun loadUserData(): Unit becomes fun loadUserData(cont: Continuation): Any. Two changes — the suspend keyword vanishes (it&#39;s a compile-time signal, not a runtime thing), and the function gains a hidden parameter at the end: the Continuation. <strong>Every suspend function in your codebase has this hidden parameter.</strong> It&#39;s the most invisible API in Kotlin.</p><p>The function body is wrapped in a when (Kotlin&#39;s switch) over cont.label. Each case corresponds to a suspension point. Inside each case, the function:</p><ol><li>Saves the next state (sm.label = N + 1)</li><li>Calls the next suspending function, <strong>passing the same </strong><strong>Continuation</strong></li><li>Checks if the result is the special sentinel COROUTINE_SUSPENDED</li><li>If yes, returns immediately (the thread is freed)</li><li>If no, the call completed synchronously — it falls through to the next state</li></ol><p>That COROUTINE_SUSPENDED sentinel is the compiler&#39;s way of asking &quot;did this actually suspend, or did it return immediately?&quot; Most calls don&#39;t actually suspend — they return synchronously, and the function keeps running on the same thread without ever giving it back.</p><p>The return type becomes Any because the function might return either the real result <em>or</em> the suspension sentinel.</p><h3>Watch it run — all four parties at once</h3><p>Words can only get you so far. The mechanism is best understood by watching it happen.</p><p>Below is an interactive walkthrough showing your Kotlin source code (left), the decompiled bytecode the compiler actually generates (right), and a four-lane timeline tracking everything that matters: the <strong>main thread</strong>, the <strong>launched coroutine</strong>, the <strong>network library</strong>, and the <strong>Continuation object</strong>. Click play, or step through manually.</p><p>Pay special attention to step 6. That’s the moment everything clicks. The banner at the bottom turns green and says <strong>“main thread: FREE!”</strong> — and the highlighted line of bytecode is the exact line of generated code that freed it. Once you see <em>that</em> correspondence, you understand coroutines.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fcodepen.io%2Fsandeep-dhami%2Fembed%2Fpreview%2FQwGENZW%3Fdefault-tabs%3Djs%252Cresult%26height%3D600%26host%3Dhttps%253A%252F%252Fcodepen.io%26slug-hash%3DQwGENZW&amp;display_name=CodePen&amp;url=https%3A%2F%2Fcodepen.io%2Fsandeep-dhami%2Fpen%2FQwGENZW&amp;image=https%3A%2F%2Fshots.codepen.io%2Fusername%2Fpen%2FQwGENZW-512.jpg%3Fversion%3D1778511000&amp;type=text%2Fhtml&amp;schema=codepen" width="800" height="600" frameborder="0" scrolling="no"><a href="https://medium.com/media/7201964c22d250a8d909dc48c26b4912/href">https://medium.com/media/7201964c22d250a8d909dc48c26b4912/href</a></iframe><p>A screenshot of the most important moment, in case the embed doesn’t load:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2xAuJvTU4z4UCeUXWgvjyA.png" /></figure><h3>The full lifecycle, in plain English</h3><p>If you watched the walkthrough through, here’s what you just saw — annotated, with the four parties in mind.</p><p><strong>Steps 1–3.</strong> The main thread runs runBlocking, hits launch, schedules a new coroutine — and then <em>keeps moving</em>. launch does not block. The main thread executes println and starts renderUI. Meanwhile, the launched coroutine sits in a queue, waiting for its turn.</p><p><strong>Step 4.</strong> The runtime dispatches the queued coroutine. The state machine version of loadUserData is invoked with label = 0. The when block enters case 0.</p><p><strong>Step 5.</strong> Case 0 bumps sm.label to 1 (so the function knows where to resume), then calls api.getUser(sm) — passing the Continuation as a hidden parameter. The network library now holds the Continuation. It sends the HTTP request.</p><p><strong>Step 6.</strong> The HTTP response will take 200ms. getUser cannot return a real User yet, so it returns COROUTINE_SUSPENDED. The very next line of bytecode — if (r === SUSPENDED) return SUSPENDED — fires. <strong>The state machine function returns. The stack unwinds. The thread is FREE.</strong></p><p>This is the moment your app stays responsive. The launched coroutine is no longer occupying any thread. Its Continuation sits on the heap, holding label = 1, waiting for someone to call resumeWith().</p><p><strong>Step 7.</strong> The main thread is free. It picks up where it left off — continues renderUI, handles UI events, renders frames. <strong>All of this happens while the network call is still in flight</strong>, because the launched coroutine is not on any stack.</p><p><strong>Steps 8–9.</strong> 200ms later, the HTTP response arrives. The network library calls continuation.resumeWith(user). This is what &quot;resuming&quot; actually means: it invokes the state machine function <strong>again</strong>, passing the same Continuation. The function looks at sm.label, sees it&#39;s 1, jumps to case 1, restores sm.user, bumps the label to 2, and calls getPosts(user.id, sm). Same dance: returns SUSPENDED. Thread is freed again.</p><p><strong>Steps 10–11.</strong> getPosts completes. resumeWith(posts) is called. Third invocation of the state machine. sm.label = 2 → case 2. This time, the function runs println and reaches a real return Unit. Not SUSPENDED. The coroutine framework sees completion and cleans up the Continuation.</p><p><strong>Step 12.</strong> runBlocking sees all children done, returns, and main exits.</p><p>Notice the big picture: <strong>the main thread was free for the entire 200ms+ network wait.</strong> That’s the win. That’s what coroutines bought you.</p><h3>The mechanical truth in three lines</h3><p>If you only remember three lines from this entire episode, remember these:</p><blockquote><em>A suspend function does not pause — it returns </em><em>COROUTINE_SUSPENDED. A </em><em>Continuation is the object that knows how to call the function again. &quot;Resuming&quot; = calling the function again, with the same Continuation.</em></blockquote><p>If a dev asks you tomorrow what suspend does, give them those three lines. They will be ahead of 90% of Android developers.</p><h3>⚠️ The interview question that breaks people</h3><p>Here’s one that comes up in staff Android interviews:</p><blockquote>“What’s the runtime cost of a suspend function that doesn&#39;t actually suspend?&quot;</blockquote><p>The naive answer is “zero, it’s just a function call.” That’s wrong.</p><p>A suspend function that never reaches a suspension point still pays for:</p><ul><li><strong>The hidden </strong><strong>Continuation parameter.</strong> A new object, allocated on the heap, even if it&#39;s only used to determine the entry label is 0 and the function runs through to completion.</li><li><strong>The state machine wrapping.</strong> Your three lines of straight-line code are wrapped in a when block. Always.</li><li><strong>The </strong><strong>COROUTINE_SUSPENDED checks.</strong> Even when nothing suspends, the compiler emits the check after every potentially-suspending call.</li></ul><p>The cost is small — usually a few extra nanoseconds and one heap allocation — but it isn’t zero. This is why hot paths inside a coroutine are sometimes worth extracting as plain non-suspend functions when you’ve measured them and they matter.</p><blockquote><strong>Every </strong><strong>suspend fun is a state machine. Even the ones that never suspend.</strong></blockquote><h3>So why did Kotlin choose this design?</h3><p>This is the design taste question. Why did the Kotlin team choose this Continuation-Passing transformation, instead of, say, real OS-level coroutines (like Go’s goroutines) or fibers (like Java’s Project Loom)?</p><p>Three reasons, all engineering trade-offs:</p><p><strong>1. Zero runtime support needed.</strong> Because the compiler does all the work, coroutines run on plain old JVM, plain old JS, plain old native code. No new threading primitive. No virtual machine changes. This is why Kotlin coroutines work everywhere Kotlin works — Android, server, Compose Multiplatform, the lot.</p><p><strong>2. Cheap suspension.</strong> Suspending a coroutine is just a function return. Resuming it is just a function call. There is no thread context switch, no kernel involvement. This is why you can have a million coroutines and your phone doesn’t catch fire (Episode 1 reference).</p><p><strong>3. Explicit boundaries.</strong> Because you have to mark functions as suspend, you always know when you&#39;re crossing a suspension point. This is the opposite of Loom&#39;s design philosophy (where any blocking call could secretly suspend). Kotlin gives you visibility; Loom gives you transparent retrofit. Different taste, both valid.</p><p>The downside? Function colors. Once you have suspend functions, you have a function-color problem: regular functions can&#39;t easily call them. You see this every day with runBlocking and coroutineScope boilerplate. It&#39;s a known cost.</p><h3>The three things you should walk away with</h3><ol><li><strong>suspend is a compile-time keyword, not a runtime feature.</strong> It tells the compiler to rewrite the function as a state machine.</li><li><strong>Every </strong><strong>suspend function has a hidden </strong><strong>Continuation parameter.</strong> This is Lady Continuance. She carries the current state label and saved local variables.</li><li><strong>“Suspending” means returning.</strong> The function literally exits and unwinds the stack. “Resuming” means being called again, with the same Continuation. The thread is free in between.</li></ol><p>If you understand these three things, you understand 90% of how coroutines work mechanically. The other 10% — Job hierarchy, structured concurrency, dispatchers, cancellation — is what we build <em>on top</em> of this state machine in the rest of the series.</p><h3>What’s coming in Episode 3</h3><p><strong>“Hand of the King: Jobaryon and the Family Tree of Quests”</strong> — we leave the compiler behind and meet the runtime. Why does a coroutine have a <em>parent</em> and <em>children</em>? What happens when the parent dies? Why does launch return one type and async return another? And why is &quot;structured concurrency&quot; the most important phrase you&#39;ll hear this year?</p><p>Episode 3 is the one where you stop being surprised by coroutine cancellation. We’ll trace a real bug — a viewModelScope leak — from symptom to root cause, and you&#39;ll see exactly how the Job hierarchy decides who lives and who dies.</p><p><em>Follow me on Medium so you don’t miss Episode 3. If Lady Continuance finally clicked for you in this episode, the clap button goes up to 50 — use them. The Medium algorithm rewards engaged readers more than you’d think.</em></p><p><em>Hit reply with: have you ever debugged a coroutine and seen </em><em>Continuation in a stack trace? Did you know what it was at the time? I&#39;d love to hear what your pre-Episode-2 mental model was.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=863bcab63798" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building an Offline-First Feed in Kotlin Multiplatform — Part 1: The High-Level Design]]></title>
            <link>https://medium.com/@sandeep84397/building-an-offline-first-feed-in-kotlin-multiplatform-part-1-the-high-level-design-42f928e4f186?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/42f928e4f186</guid>
            <category><![CDATA[compose-multiplatform]]></category>
            <category><![CDATA[kotlin-multiplatform]]></category>
            <category><![CDATA[mobile-architecture]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[offline-first]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Sat, 09 May 2026 18:42:54 GMT</pubDate>
            <atom:updated>2026-05-09T19:10:12.709Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bsWczunrIghbK1P97lk4yg.png" /></figure><h3>The problem I refused to ignore</h3><p>Every social-feed app I’ve built lies to its users on the first launch. You open it on a flaky train, it shows a spinner forever, and your finger hovers over the back button. The fix isn’t a faster network. It’s pretending the network doesn’t exist — until you have to use it.</p><p>That’s offline-first. Not a feature. A posture.</p><p>This article is the <strong>High-Level Design</strong> of how I built one for Android <em>and</em> iOS from a single Kotlin codebase. The next part dives into the LLD — concrete classes, sequences, code paths.</p><h3>What you’re looking at</h3><p>A Kotlin Multiplatform (KMP) feed app. One codebase, two platforms, zero compromises on UX.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/832/1*CvRJxny27yibtjLmLyRMvw.png" /></figure><blockquote>Why a context diagram before code? Because every reader who skims tech blogs is asking “is this for me?” One picture, three boxes, decision made.</blockquote><h3>The three rules I designed against</h3><p>I picked these <em>before</em> writing any code. Every architectural choice traces back to one of them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/767/1*IFU8-K6XE_1w0N95Ux9Zng.png" /></figure><h3>The container view</h3><p>Three deployable units. One language.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qqgP0i5JMYvlTFlnle5htw.png" /></figure><p><strong>The win:</strong> ~95% of the code lives in shared. Platform modules are thin (~30 lines each — Activity setup on Android, ViewController bootstrap on iOS).</p><h3>The tech stack — every choice has a reason</h3><p>I won’t list libraries. I’ll list <strong>decisions</strong>.</p><h3>1. Kotlin Multiplatform (not Flutter, not React Native)</h3><p><strong>Why:</strong> I want native UI per platform, but one source of truth for <em>behaviour</em>. KMP gives me that. Flutter draws its own widgets (uncanny-valley feel). React Native bridges JS to native (perf cliff). KMP compiles to native bytecode on both sides — no bridge, no draw layer.</p><p><strong>Cost:</strong> iOS dev experience is rougher. Build times are longer. Stack traces sometimes lie. I accepted this.</p><h3>2. Compose Multiplatform (not SwiftUI for iOS)</h3><p><strong>Why:</strong> Sharing UI is the last 5% — and the most expensive 5% if you don’t. JetBrains’ Compose Multiplatform now ships production-grade for iOS (1.9.x). I get one Composable tree, two binaries.</p><p><strong>Cost:</strong> Some iOS-native idioms feel grafted on. Worth it for a feed-style app where UX is mostly the same shape on both platforms.</p><h3>3. SQLDelight (not Room, not Realm)</h3><p><strong>Why:</strong> I write SQL. The library generates type-safe Kotlin. Schema migrations are checked at <em>compile time</em>. Multi-platform out of the box. Room is Android-only; Realm is opaque.</p><p><strong>Receipt:</strong> the migration to SQLDelight 2.3.2 (which switched paging extension to androidx) was a one-day swap. Try that with Room.</p><h3>4. Paging 3 — androidx.paging (not Cash App&#39;s wrapper)</h3><p><strong>Why:</strong> Google’s KMP-native paging library now exists. The wrapper (app.cash.paging) was the only option for years; it&#39;s deprecated. I migrated.</p><p><strong>Receipt:</strong> the migration was blocked for 9 months because SQLDelight transitively pulled the deprecated wrapper. The moment SQLDelight 2.3.2 unblocked it, I moved. Real engineering is about waiting for the right window.</p><h3>5. Ktor (not Retrofit)</h3><p><strong>Why:</strong> Multiplatform. Suspending. Pluggable engines (OkHttp on Android, Darwin on iOS). Same client, two HTTP stacks, one API call shape.</p><h3>6. Koin (not Dagger/Hilt, not Kotlin-Inject)</h3><p><strong>Why:</strong> Multiplatform. Runtime DI. Zero codegen, zero KSP plugins to fight. For a project this size, the perf overhead is invisible.</p><p><strong>Honest tradeoff:</strong> Dagger catches more errors at compile time. I accepted runtime errors in exchange for setup that takes 5 minutes instead of 5 hours.</p><h3>7. JetBrains ViewModel (yes, in commonMain)</h3><p><strong>Why:</strong> As of androidx.lifecycle:2.10.0, ViewModel is full KMP — Android, iOS, desktop, JS. I no longer need to roll my own scope-management.</p><p><strong>Receipt:</strong> I started with hand-rolled AutoCloseable and CoroutineScope + SupervisorJob. Migrated when JetBrains shipped the KMP artifact. Less code, more correctness.</p><h3>Functional requirements</h3><p>Concrete, testable, scoped.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/764/1*ei_qBnvJraKyVPtAs7lfYg.png" /></figure><h3>Non-functional requirements</h3><p>Where most architectures lie. Here’s mine, with measured numbers where I have them.</p><h3>Performance</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/763/1*emeO07n-vN1nAH8WEYnFEg.png" /></figure><h3>Reliability</h3><ul><li><strong>Network drop mid-fetch:</strong> mediator returns Error, paging surfaces it as a load-state. UI degrades to last-cached page. <strong>Tested.</strong></li><li><strong>DB write conflict:</strong> INSERT OR REPLACE handles it. Idempotent.</li><li><strong>App killed mid-sync:</strong> syncStatus = PENDING_* rows persist; sync worker re-attempts on next launch. <strong>Designed, not yet built.</strong></li></ul><h3>Scalability</h3><ul><li>Feed table indexed on createdAt DESC — pagination is a range scan, not a full table scan.</li><li>Paging keeps in-memory window small (configurable via PagingConfig.pageSize).</li><li>Image loading via Coil 3 (KMP) — disk-cached, network-shielded.</li></ul><h3>Security</h3><ul><li>All API calls over HTTPS. Ktor enforces.</li><li>Local DB unencrypted (Phase 1). SQLCipher integration scoped for Phase 3 if user data gets sensitive.</li><li>No PII in logs.</li></ul><h3>Maintainability</h3><ul><li>Clean Architecture layers — domain knows nothing of data or presentation.</li><li>~95% code in commonMain — one bug fix, two platforms patched.</li><li>77 unit tests across both platforms.</li><li>ADRs (Architecture Decision Records) for every reversible decision.</li></ul><h3>The layered architecture</h3><p>This is where KMP earns its rent.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bSqasciUiLxYmBL40VJeyA.png" /></figure><p><strong>Dependency rule:</strong> arrows point inward. Domain has no dependencies on Data or Presentation. Presentation depends on Domain only. Data implements interfaces declared by Domain. Standard Clean Architecture.</p><p><strong>The </strong><strong>:core module</strong> is a separate Gradle module containing the app-agnostic plumbing: navigation primitives, base classes, SQLDelight adapters. Designed for Maven extraction once stabilised.</p><h3>What this article doesn’t cover</h3><ul><li><em>How</em> RemoteMediator orchestrates the local DB and remote API → Part 2 (LLD)</li><li><em>Why</em> I rebuilt the Navigator three times → Part 3 (Decisions)</li><li><em>What</em> goes into :core and what doesn&#39;t → Part 4 (Reusable Core)</li><li><em>How</em> the failure modes behave → Part 5 (Non-Functional Reality Check)</li></ul><h3>What I’d do differently (if I started today)</h3><ol><li><strong>Adopt androidx.paging from day one.</strong> I knew the migration was coming. I should have waited.</li><li><strong>Skip Channel-based effects for navigation.</strong> I added Channel then ripped it out for AppNavigator. The <em>first</em> version should have been AppNavigator.</li><li><strong>Write the ADRs as I went, not at the end.</strong> I lost rationale on three decisions because I waited too long.</li></ol><h3>Code, slides, complaints</h3><p>Repo: <a href="https://github.com/sandeep84397/OfflineFirstFeed"><strong>github.com/sandeepdhami/OfflineFirstFeed</strong></a> Next part: <strong>The Read Path — How a Post Travels from Server to Pixel</strong></p><p>If this was useful, the highlight button in the margin is right there. If not, the comment box too.</p><p><em>Part 1 of 5. Subscribe to follow the rest.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=42f928e4f186" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Coroutines: A Game of Threads — Episode 1]]></title>
            <link>https://medium.com/@sandeep84397/coroutines-a-game-of-threads-episode-1-d54e05335c3a?source=rss-9b4604feeb7a------2</link>
            <guid isPermaLink="false">https://medium.com/p/d54e05335c3a</guid>
            <category><![CDATA[coroutine]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[kotlin]]></category>
            <dc:creator><![CDATA[sandeep dhami]]></dc:creator>
            <pubDate>Wed, 06 May 2026 13:47:58 GMT</pubDate>
            <atom:updated>2026-05-11T15:31:36.572Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xvRUahEShx7wJsc9bHlicA.png" /></figure><h3>“The Fall of House Threadon” — or why Kotlin needed a new kind of soldier</h3><p>This is Episode 1 of a 10-part web series where we’ll dissect Kotlin Coroutines from the ground up — using a Game-of-Thrones-style cast of characters that will make every concept stick. By Episode 10, you’ll be able to walk into a senior Android interview and answer “what does the suspend keyword do&quot; without sweating.</p><blockquote><strong><em>TL;DR — What you’ll take away from Episode 1</em></strong></blockquote><blockquote>A coroutine is <strong>not</strong> a thread. It’s a tiny passenger; a thread is the horse.</blockquote><blockquote><strong>Suspending is not blocking.</strong> A blocked thread sits idle; a suspended coroutine vanishes and frees the thread for someone else.</blockquote><blockquote>suspend is a <strong>permission slip, not a teleporter</strong> — it doesn&#39;t make code asynchronous on its own.</blockquote><blockquote>One thread can serve thousands of coroutines. That’s the entire game.</blockquote><h3>Meet the cast</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2cueTgwF7rjrsiQnSAqlOg.png" /></figure><p>Before we open Episode 1, here are the characters you’ll see across all 10 episodes. Save this list — when something confuses you in Episode 6, you’ll come back to it.</p><p>Character Plays <strong>Lord Threadon Stark</strong> An OS thread <strong>Coro Targaryen</strong> A coroutine <strong>Maester Suspendos</strong> The suspend keyword <strong>Lady Continuance</strong> A Continuation <strong>Hand of the King Jobaryon</strong> A Job <strong>Lord Dispatch Tyrell</strong> A Dispatcher <strong>Captain Scope Mormont</strong> A CoroutineScope</p><p>Roll the title card.</p><h3>The realm has a problem</h3><p>For centuries, House Threadon ran the kingdom. When a quest came in — <em>“fetch a scroll from the Citadel,” “deliver a raven to Winterfell”</em> — the king summoned Lord Threadon, who dispatched a knight. The knight rode out, completed the quest, rode back.</p><p>Beautiful. Honorable. <strong>Bankrupting the treasury.</strong></p><p>Each Threadon knight wears a 1 MB suit of armor (his stack memory). When he rides to the Citadel and waits for the maester to find a scroll, he stands there in full armor doing nothing — but the crown still pays for that armor. A kingdom can field maybe a few thousand knights before the gold runs out.</p><p>Now Coro Targaryen rides into King’s Landing on a dragon. She wears a light cloak — a few hundred bytes. When she has to wait, she takes the cloak off, hands the sword to the next soldier in line, and <em>vanishes</em>. The crown can field a hundred thousand of her.</p><p>This is the central truth of Episode 1:</p><blockquote><strong><em>A coroutine is not a thread. A coroutine is a passenger; a thread is the horse. One horse can carry many passengers, one at a time.</em></strong></blockquote><h3>The Watcher on the Wall (and why you must never block him)</h3><p>Here’s the most important character in your Android app: the <strong>Night’s Watch</strong>.</p><p>There is exactly <em>one</em> brother of the Night’s Watch. His name is the <strong>Main Thread</strong>. He stands the Wall — your app’s UI. Every tap, every scroll, every animation, the Watcher handles it. He must never fall.</p><p>If you give the Watcher a long quest — a network call, a database read, anything that takes more than ~16 ms — the Wall freezes. The wildlings (your old friend, the ANR dialog) come over the wall. Your user closes your app.</p><p>The whole point of coroutines is this: <strong>the Watcher can hand off the quest and instantly return to the Wall.</strong> The quest runs somewhere else. When it’s done, the result quietly comes back to the Watcher during a quiet frame. He never breaks rhythm.</p><p>Everything else in this series — Job, Dispatcher, Scope, Continuation — exists to make that single trick safe and reliable.</p><h3>How can one horse serve three soldiers at once?</h3><p>Here’s the question that breaks most people’s mental model:</p><blockquote>If we only have one horse (one thread), and three soldiers all need to ride somewhere, how can they possibly travel “at the same time”?</blockquote><p>The answer is: <strong>they don’t.</strong> They take turns — but they take turns <em>intelligently</em>, never wasting the horse on idle waiting.</p><p>Watch this.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*5Iy0S7b57Pfwcz9hrfJxRA.gif" /></figure><p>In 14 seconds, you’ve seen the entire concept of coroutines. Notice what happened:</p><ol><li>Horse picks up Coro, rides to the Citadel.</li><li>The maester says <em>“give me a few minutes.”</em> Coro <strong>suspends</strong> — she takes off her cloak and waits at the Citadel.</li><li>The horse, now free, gallops back home. It picks up Daenys, runs her quick errand. Then Visarra. Then her errand.</li><li>The Citadel sends word: <em>“Coro’s scroll is ready.”</em></li><li>The horse rides back, picks Coro up where she left off, brings her home.</li></ol><p><strong>The horse never sat idle.</strong> Coro never blocked Daenys. Daenys never blocked Visarra. Three quests ran “concurrently” on a single horse — because suspending is not blocking.</p><p>If the horse had been a Threadon knight (a blocking thread), it would have stood at the Citadel for the entire wait. Daenys and Visarra would still be at the castle, pacing. Your app would have frozen for 5 seconds and earned an ANR.</p><p>This is why your Android app can launch hundreds of coroutines on a small thread pool and your phone doesn’t catch fire.</p><h3>The same code, three eras of warfare</h3><p>Here’s the same task — fetch a user, then their banners, then the houses they’re sworn to — written in each era of Android async code.</p><p><strong>Era 1: The Pyramid of Doom (callbacks)</strong></p><pre>fun loadHouseData(userId: String) {<br>    api.getUser(userId, object : Callback&lt;User&gt; {<br>        override fun onSuccess(user: User) {<br>            api.getBanners(user.id, object : Callback&lt;List&lt;Banner&gt;&gt; {<br>                override fun onSuccess(banners: List&lt;Banner&gt;) {<br>                    api.getHouses(banners.first().id, object : Callback&lt;List&lt;House&gt;&gt; {<br>                        override fun onSuccess(houses: List&lt;House&gt;) {<br>                            runOnUiThread { showOnWall(user, banners, houses) }<br>                        }<br>                        override fun onFailure(e: Throwable) { /* gods help us */ }<br>                    })<br>                }<br>                override fun onFailure(e: Throwable) { /* and again */ }<br>            })<br>        }<br>        override fun onFailure(e: Throwable) { /* the same prayer */ }<br>    })<br>}</pre><p><strong>Era 2: The Wildfire (RxJava)</strong></p><pre>fun loadHouseData(userId: String): Disposable {<br>    return api.getUser(userId)<br>        .flatMap { user -&gt; api.getBanners(user.id).map { banners -&gt; user to banners } }<br>        .flatMap { (user, banners) -&gt;<br>            api.getHouses(banners.first().id).map { houses -&gt; Triple(user, banners, houses) }<br>        }<br>        .subscribeOn(Schedulers.io())<br>        .observeOn(AndroidSchedulers.mainThread())<br>        .subscribe(<br>            { (user, banners, houses) -&gt; showOnWall(user, banners, houses) },<br>            { error -&gt; showError(error) }<br>        )<br>}</pre><p><strong>Era 3: The Dragons (coroutines)</strong></p><pre>suspend fun loadHouseData(userId: String) {<br>    try {<br>        val user    = api.getUser(userId)<br>        val banners = api.getBanners(user.id)<br>        val houses  = api.getHouses(banners.first().id)<br>        showOnWall(user, banners, houses)<br>    } catch (e: Exception) {<br>        showError(e)<br>    }<br>}</pre><p>Read the Era 3 version and tell me it doesn’t read like instructions written on parchment. That readability <em>is</em> the selling point. The compiler does the callback gymnastics for you. We will see exactly how, in Episode 2.</p><h3>⚠️ The interview question that breaks people</h3><p>Here’s a question I’ve been asked twice in senior Android interviews. Most candidates get it wrong.</p><blockquote><strong><em>“Does the </em></strong><strong><em>suspend keyword make a function asynchronous?&quot;</em></strong></blockquote><p>The answer is <strong>no</strong>.</p><p>suspend does not make Coro fast or parallel. It does not move her work to a background thread. All the keyword does is grant her <em>permission</em> to pause — meaning, permission to call other suspending functions like delay() or withContext().</p><p>A suspend function with no actual suspension points runs <strong>synchronously</strong> on whoever called it.</p><pre>suspend fun addTwoNumbers(a: Int, b: Int): Int = a + b</pre><p>This suspend function does not run on a background thread. It does not pause. It runs on the caller&#39;s thread, blocking it like any other function.</p><pre>suspend fun fetchUser(): User = withContext(Dispatchers.IO) {<br>    api.getUser()<br>}</pre><p><em>This</em> one actually suspends and runs in the background — because withContext(Dispatchers.IO) is the spell that summons Lord Dispatch Tyrell to send the work to a different thread.</p><blockquote><strong><em>suspend is a permission slip, not a teleporter.</em></strong></blockquote><p>Internalize that one sentence and you’ll be ahead of 80% of Android developers.</p><h3>The three things you should walk away with</h3><p>If you can recite these to a colleague over chai, you’ve understood Episode 1:</p><ol><li><strong>Coro Targaryen is not Sir Threadon.</strong> A coroutine is a tiny passenger; a thread is the horse.</li><li><strong>Suspending is not blocking.</strong> A blocked knight stands idle in armor. A suspended coroutine vanishes and frees the horse for another soldier.</li><li><strong>suspend is permission, not behavior.</strong> Where the work actually runs is decided by the <em>dispatcher</em> — that&#39;s Episode 4&#39;s whole story.</li></ol><h3>What’s coming in Episode 2</h3><p>In <strong>“The Secret of Lady Continuance,”</strong> we crack open the parchment Coro hands to Maester Suspendos when she suspends. We’ll see exactly what the Kotlin compiler does to your suspend fun — how it transforms your beautiful linear code into a state machine, what hidden parameter it adds to every function, and how Lady Continuance actually remembers where to resume.(<a href="https://medium.com/@sandeep84397/what-suspend-actually-does-spoiler-it-doesnt-pause-your-function-863bcab63798">Link</a>)</p><p>This is the episode where the magic disappears and becomes engineering. You will never look at suspend the same way again.</p><p><em>Follow me here on Medium so you don’t miss Episode 2 (dropping next Tuesday). Or — better — drop a comment with your worst coroutine bug. The most painful one will become a case study in Episode 9.</em></p><p><em>If this helped you understand suspending vs blocking for the first time, the clap button goes up to 50. Use them all. They cost you nothing and the Medium algorithm cares more about them than you’d think.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d54e05335c3a" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>