Consider comparison shopping for a pair of headphones. If you want prices from four stores, you would not ask the first store, wait for its response, and only then ask the second store. You would send all four requests and process the quotes in the order they arrive.

In Kotlin, channelFlow gives us a convenient way to express that pattern while keeping the result as an ordinary Flow.

The example uses the kotlinx-coroutines-core dependency:

implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0")

Here is the complete example:

import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.channelFlow
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.flow.flow
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import java.util.Locale
import kotlin.random.Random

data class PriceQuote(val store: String, val price: Double)

// Simulates a store API with its own latency
fun fetchPrice(store: String, product: String): Flow<PriceQuote> = flow {
    println("Requesting $product price from $store")
    delay(Random.nextLong(300, 2_000))
    emit(PriceQuote(store, Random.nextDouble(80.0, 120.0)))
}

fun comparePrices(product: String): Flow<PriceQuote> = channelFlow {
    val stores = listOf("Amazon", "Takealot", "eBay", "AliExpress")

    for (store in stores) {
        launch {
            fetchPrice(store, product).collect { quote ->
                send(quote)
            }
        }
    }
}

fun main() = runBlocking {
    comparePrices("headphones").collect { quote ->
        println("${quote.store}: \$${"%.2f".format(Locale.US, quote.price)}")
    }

    println("All stores answered.")
}

One run may produce the following output:

Requesting headphones price from Amazon
Requesting headphones price from Takealot
Requesting headphones price from eBay
Requesting headphones price from AliExpress
eBay: $94.13
Amazon: $101.87
AliExpress: $83.42
Takealot: $109.55
All stores answered.

The request is logged before each coroutine reaches delay, so those messages appear before their corresponding quotes. Neither the request messages nor the quotes have a guaranteed order, although the requests will normally start in store-list order in this small example.

Why use channelFlow instead of flow?

A normal flow { } is designed for sequential emission from its own coroutine. It preserves the coroutine context in which it is collected, so starting child coroutines inside it and calling emit from those children violates the flow invariant.

channelFlow is designed for the case where several coroutines need to produce values for the same flow. Its block provides a ProducerScope, and each child coroutine can safely call send on that scope. The channel merges those values into a single flow for the collector.

The resulting flow is still cold. Nothing happens when comparePrices("headphones") is called; the store requests start when the flow is collected. Collecting it a second time starts four new requests and produces a new set of quotes.

Why launch inside the loop?

Without launch, the collections would run one after another:

for (store in stores) {
    fetchPrice(store, product).collect { quote ->
        send(quote)
    }
}

collect is a suspending call and does not return until that store's flow completes. Amazon would therefore finish before Takealot starts, followed by eBay and AliExpress. The total waiting time would be close to the sum of all four delays.

With launch, each store flow is collected by a child coroutine. All four delays can overlap, so the total waiting time is close to the slowest request rather than the sum of every request. This is concurrency; it does not require four dedicated threads. While one coroutine is suspended in delay or waiting for non-blocking I/O, another coroutine can make progress.

Why does the flow wait for every store?

The child coroutines launched inside channelFlow belong to its scope. Because this follows structured concurrency, the flow does not complete until the builder block and all of its children have completed.

The loop itself finishes quickly, but its children are still fetching and sending quotes. Only after the last child finishes does collection complete and All stores answered. print. There is no need to maintain a counter, close a channel manually, or call joinAll.

Structured concurrency also defines the failure behaviour. If one store flow throws an exception, its failure cancels the channelFlow and the other child coroutines, and the exception reaches the collector. If a failed store should not stop the comparison, handle that failure inside the individual store flow and decide what result to send instead.

Why use send instead of emit?

send is the channel operation provided by the ProducerScope inside channelFlow. Each store coroutine sends its quote into the same channel, and the downstream collector receives quotes as they become available. That interleaving of several producers into one consumer is the fan-in.

From main's point of view, comparePrices is simply a Flow<PriceQuote>. The concurrency is kept inside the producer, so callers can use normal flow operators and terminal operations without knowing how the values were produced.

Cancellation and backpressure

Cancellation follows the same parent-child relationship. If the collector is cancelled or stops early, the work inside channelFlow and its child coroutines is cancelled as well. For example, comparePrices("headphones").first() returns the first quote to arrive and cancels the remaining requests. It finds the fastest response, not necessarily the cheapest price.

channelFlow uses a buffered channel by default. Producers can get ahead of a slow collector until that buffer is full; after that, send suspends until capacity becomes available. That gives the flow backpressure without allowing producers to grow an unbounded queue. If every send must wait for the collector, apply buffer(0) to the returned flow to use rendezvous behaviour.

The shorter version with merge

For this example, the merge flow operator is the idiomatic shortcut:

import kotlinx.coroutines.flow.merge

fun comparePrices(product: String): Flow<PriceQuote> {
    val stores = listOf("Amazon", "Takealot", "eBay", "AliExpress")

    return stores
        .map { store -> fetchPrice(store, product) }
        .merge()
}

merge collects all of the flows concurrently and emits their values without preserving the order of the source flows. For a straightforward fan-in, I would normally use merge. When the producer needs more control over how child coroutines send values, handle callbacks, or combine different kinds of concurrent work, channelFlow makes the underlying pattern explicit.

The useful part of fan-in is that the consumer does not have to coordinate the producers.

Each producer works at its own pace, while the collector sees one flow of results and retains the normal completion, failure, cancellation, and backpressure behaviour of Kotlin coroutines.

macOS Tahoe ships with Apple's on-device foundation model, roughly a 3B parameter LLM, and apfel gives it a very convenient front door. It wraps Apple's FoundationModels framework and exposes the model in three ways:

1. A UNIX-style command-line tool.
2. An OpenAI-compatible HTTP server.
3. An interactive chat mode.

In this post I will show how to use apfel from the command line, then call the same local model from a Kotlin script using the OpenAI-compatible API.

Installing apfel

The installation is a single Homebrew command:

brew install apfel

apfel requires Apple Silicon, macOS Tahoe, and Apple Intelligence to be enabled. Once those pieces are in place, there is no extra configuration needed.

The important part is that the model runs on your Mac. For short prompts, small text transformations, command explanations, shell one-liners, translations, and local scripting tasks, that is very appealing. You get a useful local assistant without sending the prompt to a cloud model.

Prompting from the terminal

After installing apfel, you can prompt the model directly:

apfel --stream "Can you write some Kotlin code to print Hello World to the screen?"

You can also use it in the normal UNIX way by redirecting output:

apfel "Write a Kotlin script to print Hello World to the console without any explanation or anything else besides the script." > hello.kts

The model is still a small local model, so you should inspect what it writes, but the output is easier to pipe into a file.

Starting the OpenAI-compatible server

The most interesting part for Kotlin is the server mode. apfel can expose the local model as an OpenAI-compatible API:

apfel --serve

By default, this starts a server on:

http://127.0.0.1:11434

If that port is already busy, or you just prefer a different port, you can specify one:

apfel --serve --port 11435

The server exposes the familiar chat completions endpoint:

POST /v1/chat/completions

It also supports useful OpenAI-style features such as streaming, GET /v1/models, tool calling, response_format: json_object, temperature, max_tokens, seed, and CORS for browser clients.

For this post, we only need the basic chat completions endpoint.

Calling apfel from Kotlin

Because the server speaks the OpenAI API shape, calling it from Kotlin is straightforward. The model name is apple-foundationmodel, and the API key can be any placeholder value because the local server does not require authentication by default.

Here is a complete Kotlin script:

@file:DependsOn("tools.jackson.core:jackson-databind:3.0.3")

import tools.jackson.databind.json.JsonMapper
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

val baseUrl = "http://localhost:11434/v1"
val apiKey = "unused"

val body = """
    {
      "model": "apple-foundationmodel",
      "messages": [
        {
          "role": "user",
          "content": "Translate to Korean: Thank you"
        }
      ],
      "temperature": 0.2,
      "max_tokens": 100
    }
""".trimIndent()

val request = HttpRequest.newBuilder(URI.create("$baseUrl/chat/completions"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer $apiKey")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build()

runCatching {
    val response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString())

    check(response.statusCode() in 200..299) {
        "HTTP ${response.statusCode()}: ${response.body()}"
    }

    val root = JsonMapper.shared().readTree(response.body())
    val content = root.path("choices").get(0)
        ?.path("message")?.path("content")?.asString()
        ?: error("Unexpected response shape: ${response.body()}")

    println(content)
}.onFailure { System.err.println("Error: ${it.message}") }

Save this as apfel.main.kts. With Kotlin on your path, you can run it directly:

kotlin apfel.main.kts

Here is the output I get:

감사합니다.

If you started apfel on the alternate port shown earlier, change the script to:

val baseUrl = "http://localhost:11435/v1"

That is the main benefit of the OpenAI-compatible API. The code is ordinary HTTP client code. If you already have a client abstraction that talks to OpenAI, you can often point it at http://localhost:11434/v1, use the apple-foundationmodel model name, and keep most of the rest of the code the same.

Checking the available model

The server also exposes a models endpoint, which is useful when you want to verify that the server is running:

curl http://localhost:11434/v1/models

For apfel, the important model id is:

apple-foundationmodel

There is no model picker here in the same sense as a cloud API or a local model manager such as Ollama. apfel is intentionally wrapping the Apple model that is already available through macOS.

What this is good for

The local model is not meant to replace larger cloud-based models. It has a smaller context window, around 4,096 tokens for input and output combined, and it is not the tool I would choose for long documents, complex code generation, or tasks that need strong factual recall.

Where it becomes interesting is in small, local, everyday tasks:

1. Explaining a shell command.
2. Generating a small regex.
3. Rephrasing a short paragraph.
4. Translating a phrase.
5. Summarising a short file.
6. Turning command output into something easier to read.
7. Building a small local Kotlin utility that needs just enough language understanding.

The local context is the part I like most. Cloud models cannot see the output of df -h, lsof, git log, or ls unless you explicitly send that data to them. With apfel, you can pipe local command output into a local model and keep the whole loop on your machine.

For example:

df -h | apfel "Which volume is closest to full? Reply in one sentence."

or:

git log --oneline -10 | apfel "Summarise these commits in three bullets."

That makes apfel feel less like a replacement for a big hosted model and more like a small language-aware UNIX tool.

Final thoughts

For me, the nice thing about apfel is not only that it provides CLI access to Apple's on-device model. It is that it exposes the model through interfaces developers already know: standard input and output for shell scripts, and an OpenAI-compatible API for application code.

That makes it easy to experiment from Kotlin. Start apfel --serve, point a small Kotlin script at http://localhost:11434/v1, send a normal chat completions request, and you have a private local model call running on your Mac.

It will not replace cloud models for every use case, and it should not be treated as if it has the same capabilities as a larger hosted model. But for quick local automation, small text transforms, and developer workflows where privacy and zero setup matter, it is a very useful tool to have installed.

So I wrote a deliberately simple experiment. It does not simulate a full production workload. It does not call a database, marshal JSON, apply business rules, or exercise a web server. It simply asks one question:

How many parked threads can this JVM create before something gives way?

That is still a useful question, because it shows the most important difference between platform threads and virtual threads. Platform threads are expensive because they are backed by operating system threads. Virtual threads are cheap because they are managed by the JVM and only use a platform thread while they are actually running.

Spawning platform threads

The first test creates platform threads using the normal Thread constructor. Each thread immediately parks itself so that it stays alive without doing any useful work.

import org.junit.jupiter.api.Test
import java.util.concurrent.locks.LockSupport

class PlatformThreadLimitTest {
    @Test
    fun `how many platform threads can be created`() {
        var threadCount = 0
        try {
            while (true) {
                Thread {
                    while (true) LockSupport.park()
                }.start()
                threadCount++
            }
        } catch (_: OutOfMemoryError) {
            System.err.println("Platform thread limit reached: $threadCount")
        }
    }
}

This is not a test I would leave in a normal build. It is intentionally trying to exhaust a resource, and the exact failure point depends on the machine, operating system limits, JVM settings, and other processes running at the same time.

The important point is that every platform thread needs an operating system thread underneath it. That means the limit is not only about Java heap. Native memory, per-thread stack size, process limits, and the operating system scheduler all matter.

Spawning virtual threads

The second test creates one million virtual threads. Again, each thread parks itself immediately.

import org.junit.jupiter.api.Test
import java.util.concurrent.locks.LockSupport

class VirtualThreadLimitTest {
    @Test
    fun `how many virtual threads can be created`() {
        val n = 1_000_000
        repeat(n) {
            Thread.startVirtualThread {
                while (true) LockSupport.park()
            }
        }
        val rt = Runtime.getRuntime()
        val usedMb = (rt.totalMemory() - rt.freeMemory()) / (1024 * 1024)
        println("Mounted $n virtual threads, heap used: ${usedMb}MB")
    }
}

This is where virtual threads feel quite different. There is no attempt here to create a million operating system threads. Instead, the JVM creates a million lightweight Thread instances whose continuations can be mounted on a much smaller number of carrier platform threads when they need to run.

Because the threads are parked, most of them are not mounted on carrier threads most of the time. That is exactly the kind of situation virtual threads are designed for: lots of concurrent tasks, many of which spend most of their lives waiting.

Results

On my MacBook Pro M4 with 48 GB RAM, I got the following results.

Platform threads

Platform thread limit reached: 12253

Virtual threads

Mounted 1000000 virtual threads, heap used: 581MB

Result analysis

The platform-thread test dies in the low thousands, around 12k on my machine. The virtual-thread test manages to create one million parked virtual threads on a normal heap size.

That is a remarkable difference, but it is worth being precise about what this proves. It proves that virtual threads have a much lower per-thread footprint when they are parked or blocked in a way the JVM can unmount. It does not prove that a Spring Boot application can handle one million useful concurrent requests.

Real applications have other bottlenecks:

1. Database connection pools.
2. HTTP client connection pools.
3. Downstream service limits.
4. CPU-bound work.
5. Memory used by request objects, responses, buffers, caches, and application state.
6. Rate limits, queues, and back-pressure policies.

Virtual threads remove one very old bottleneck: the need to keep a large pool of expensive platform threads around just because requests might block. They do not remove the need to size and protect the rest of the system.

The number of virtual threads you can create is mainly a memory question rather than an operating-system-thread question. If you increase the heap with -Xmx, you can usually create more parked virtual threads. If each virtual thread has a deeper stack or holds more request state, you will create fewer.

Why this matters for Spring MVC

Spring MVC traditionally uses a request-per-thread model. That model is wonderfully simple: a request comes in, a thread handles it, and the code can be written in a direct blocking style.

The downside has always been scalability. If a request spends time waiting for a database, a REST call, a message broker, or a filesystem operation, the platform thread is still occupied while it waits. That is one of the reasons reactive programming with Spring WebFlux became attractive for high-concurrency I/O-heavy applications.

Virtual threads change that trade-off. For many I/O-bound workloads, you can keep the straightforward blocking style of Spring MVC while allowing the JVM to park blocked work cheaply. That does not make WebFlux obsolete. Reactive programming is still a very good fit for streaming, back-pressure, and end-to-end reactive systems. But virtual threads make the simple blocking model scale much further than it used to.

Enabling virtual threads in Spring Boot

Enabling virtual threads in Spring Boot is as simple as setting a property in your application.properties or application.yaml file:

spring.threads.virtual.enabled=true

At least Java 21 is required for this to work. Spring Boot's reference documentation also notes that the feature affects auto-configured task execution and scheduling. When virtual threads are enabled, Boot uses virtual-thread-friendly executor and scheduler choices in places where its auto-configuration is responsible for creating them.

That means this property is not only about embedded Tomcat handling requests. It can also affect pieces such as @Async, Spring MVC asynchronous request handling, blocking execution support in WebFlux, and scheduled task infrastructure depending on how the application is configured.

There is one small Spring Boot detail that is easy to miss. Virtual threads are daemon threads. If your application relies on scheduled work or other virtual-thread-based infrastructure to keep the JVM alive, you may need:

spring.main.keep-alive=true

This is called out in the Spring Boot reference documentation and is worth knowing before enabling virtual threads in a service that mostly does background or scheduled work.

Things to watch out for

Virtual threads are very useful, but they are not magic performance dust. I would pay attention to at least the following when enabling them in a Spring Boot application.

Pinning

A virtual thread can usually unmount from its carrier thread when it blocks. There are cases where it cannot, which is known as pinning. Historically, blocking while inside a synchronized block or native method could pin the virtual thread to its carrier. If enough virtual threads are pinned for long periods, throughput can suffer because the carrier threads are no longer free to run other virtual threads.

The JDK has been improving this area, but it is still worth testing your own application. The official Java documentation and Spring Boot reference both point to tools such as JDK Flight Recorder and jcmd for detecting pinned virtual threads. Spring Boot's current reference documentation also strongly recommends Java 24 or later for the best virtual-thread experience, even though Java 21 is the minimum version required.

Pool sizing still matters

With platform threads, the web server thread pool often acted as an accidental concurrency limit. Turning on virtual threads can remove or greatly raise that limit. That is usually what you want, but it means other limits become more visible.

If your database pool has 20 connections, then allowing 20,000 requests to reach code that all needs a database connection will not make the database faster. It may just move the waiting from the servlet thread pool to the connection pool.

For that reason, virtual threads often pair well with explicit bulkheads, timeouts, rate limits, and connection-pool sizing.

CPU-bound work does not become cheaper

Virtual threads are excellent when work blocks or waits. They do not give the CPU more cores. If the workload is mostly CPU-bound, creating more virtual threads can increase scheduling overhead without improving throughput.

For CPU-heavy work, the usual rules still apply: measure, use bounded parallelism, and size around the available processors.

Be careful with ThreadLocal usage

Virtual threads are still instances of java.lang.Thread, and they support ThreadLocal. That is useful for compatibility with existing libraries. However, virtual threads are intended to be numerous and short-lived, so using ThreadLocal as a cache for expensive resources is a bad fit.

Use normal Spring-managed beans, connection pools, and scoped context mechanisms where appropriate. Do not treat a virtual thread as a long-lived worker thread with reusable state attached to it.

Useful references

These are the pages I would keep close by when experimenting with this in a Spring Boot application:

1. Spring Boot reference documentation: Virtual threads
2. Spring Boot reference documentation: Task execution and scheduling
3. Spring Guide: Building a RESTful Web Service
4. Spring Guide: Building a Reactive RESTful Web Service
5. Spring blog: Embracing Virtual Threads
6. OpenJDK JEP 444: Virtual Threads
7. Oracle Java documentation: Virtual Threads

Final thoughts

For me, the experiment makes the appeal of virtual threads very concrete. With platform threads, the JVM runs into a practical wall after a few thousand parked threads. With virtual threads, a million parked tasks is not especially dramatic.

That difference matters for Spring Boot applications because so many business systems are mostly waiting: waiting for databases, waiting for downstream APIs, waiting for queues, waiting for storage.

Virtual threads let you keep the readable request-per-thread programming model while dramatically reducing the cost of waiting. They are not a replacement for good system design, sensible limits, or performance testing. But for many Spring MVC applications running on Java 21 or later, spring.threads.virtual.enabled=true is now one of the most interesting properties worth testing.

In Kotlin, coroutines make it straightforward to start asynchronous work. However, I prefer not to scatter calls to CoroutineScope(...) or Dispatchers.IO, (and definitely NOT GlobalScope) throughout an application. Instead, I like to define an explicit background coroutine configuration and inject it where it is needed.

This gives the application a named place for background execution, error handling, and shutdown behaviour.

@Configuration
@OptIn(ExperimentalCoroutinesApi::class)
class CoroutineConfig : DisposableBean {

    private val backgroundExecutor: ExecutorService = Executors.newVirtualThreadPerTaskExecutor()
    private val backgroundDispatcher = backgroundExecutor.asCoroutineDispatcher()

    private val handler = CoroutineExceptionHandler { ctx, e ->
        val correlationId = ctx[CorrelationIdContextElement]?.correlationId ?: NO_CORRELATION_ID
        log.error(">>> Unhandled background coroutine error, correlationId=[$correlationId]", ctx, e)
    }

    @Bean
    @Qualifier(BACKGROUND_DISPATCHER_NAME)
    fun backgroundDispatcher(): CoroutineDispatcher = backgroundDispatcher

    @Bean
    @Qualifier(BACKGROUND_SCOPE_NAME)
    fun backgroundScope(): CoroutineScope {
        return CoroutineScope(SupervisorJob() + handler + backgroundDispatcher + CoroutineName(BACKGROUND_SCOPE_NAME))
    }

    override fun destroy() {
        backgroundDispatcher.close()
        backgroundExecutor.shutdown()
    }

    companion object {
        private val log = CoroutineLogger(LoggerFactory.getLogger(CoroutineConfig::class.java))
    }
}

const val BACKGROUND_DISPATCHER_NAME = "backgroundDispatcher"
const val BACKGROUND_SCOPE_NAME = "backgroundScope"
private const val NO_CORRELATION_ID = "<no correlation id>"

Why define a background coroutine configuration?

The main reason is ownership.

When a coroutine is launched, something should own its lifecycle. In a web application, the request normally owns request-scoped work. If the request is cancelled, times out, or completes, that work should usually stop with it.

Background work is different. It often needs to continue independently of the request that caused it. For example, an endpoint may accept a command, persist the initial state, and then trigger some follow-up processing in the background. That follow-up processing should not be tied to the HTTP connection staying open.

By exposing a dedicated CoroutineScope as a Spring bean, you make that decision explicit:

@Bean
@Qualifier(BACKGROUND_SCOPE_NAME)
fun backgroundScope(): CoroutineScope {
    return CoroutineScope(SupervisorJob() + handler + backgroundDispatcher + CoroutineName(BACKGROUND_SCOPE_NAME))
}

Any class that needs to launch background work can inject this scope using the qualifier. That keeps the application honest about which work is request-bound and which work is intentionally detached.

Why use a dedicated dispatcher?

The configuration creates an ExecutorService and adapts it into a coroutine dispatcher:

private val backgroundExecutor: ExecutorService = Executors.newVirtualThreadPerTaskExecutor()
private val backgroundDispatcher = backgroundExecutor.asCoroutineDispatcher()

In this case, the executor uses Java virtual threads. That makes the dispatcher a good fit for many typical application-level background jobs. Especially where the job may spend time waiting on blocking I/O such as database calls, HTTP calls, file operations, or SDK clients that are not coroutine-native.

The important point is not only that this uses virtual threads. The important point is that background work is not silently being pushed onto an unrelated dispatcher. It has a specific execution policy that can be named, tested, monitored, and changed later without hunting through the codebase.

For example, if you later decide that a particular application needs a bounded thread pool, a different executor, or more detailed instrumentation, the change can happen in this configuration class rather than at every call site.

Why use a SupervisorJob?

The scope uses a SupervisorJob:

CoroutineScope(SupervisorJob() + handler + backgroundDispatcher + CoroutineName(BACKGROUND_SCOPE_NAME))

This is useful for background processing because one failing child coroutine should not necessarily cancel every other background task running in the same scope.

For example, if three independent notification jobs are launched and one fails because a downstream provider is unavailable, the other two should usually be allowed to continue. SupervisorJob gives you that isolation.

This does not mean failures are ignored. It means failures are contained. The exception handler is still important.

Centralised exception handling

Background work can fail after the original caller has already received a response. That means you cannot rely on normal request handling to surface errors.

This configuration adds a CoroutineExceptionHandler:

private val handler = CoroutineExceptionHandler { ctx, e ->
    val correlationId = ctx[CorrelationIdContextElement]?.correlationId ?: NO_CORRELATION_ID
    log.error(">>> Unhandled background coroutine error, correlationId=[$correlationId]", ctx, e)
}

The useful part here is that the error handling is not an afterthought at each launch site. Unhandled background coroutine failures are logged in one place, and the log entry attempts to include a correlation id from the coroutine context.

That is especially valuable when the background job was triggered by a request, message, or scheduled process, and you want to connect the failure back to the original flow.

Clean shutdown

The configuration implements DisposableBean:

override fun destroy() {
    backgroundDispatcher.close()
    backgroundExecutor.shutdown()
}

The dispatcher is backed by an executor, and the executor should be shut down when the Spring application context is closed. Without this, you risk leaving executor resources alive longer than intended during shutdown, tests, redeployments, or local development restarts.

Typical use cases

I would typically use a background dispatcher like this for work that is application-owned, asynchronous, and not part of the direct response path.

Some examples are:

1. Sending email, SMS, push notifications, or webhooks after a command has been accepted.

2. Calling third-party APIs where the user does not need to wait for the result immediately.

3. Post-processing uploaded files, generated reports, images, or exported data.

4. Updating derived state, caches, search indexes, or read models after a write.

5. Running fan-out tasks where one action needs to trigger several independent downstream operations.

6. Starting work from a Spring event listener or scheduled job while keeping the coroutine execution policy consistent.

7. Running blocking I/O integrations from coroutine-based services without mixing that concern into every service method.

The common theme is that the work should be visible as background work in the code. Injecting a specifically named scope or dispatcher makes that intent clear.

How it might be used

A service can inject the scope and launch work on it:

@Service
class NotificationService(
    @Qualifier(BACKGROUND_SCOPE_NAME)
    private val backgroundScope: CoroutineScope,
) {

    fun sendWelcomeNotification(command: WelcomeNotificationCommand) {
        backgroundScope.launch {
            sendEmail(command)
            sendSms(command)
        }
    }
}

If the launched coroutine fails unexpectedly, the exception handler configured on the scope will log the failure. If multiple jobs are running in the same background scope, SupervisorJob prevents one failing job from cancelling the entire scope.

When not to use it

This configuration is not a replacement for every asynchronous processing pattern.

If the work must be durable, retryable, or guaranteed to run after the application restarts, then a queue, database-backed job table, workflow engine, or message broker is usually a better fit. A coroutine launched in memory is still in-memory work. If the process dies, that work is gone.

I would also avoid using this for request-bound concurrency. If the work is part of producing the HTTP response, prefer structured concurrency inside the suspend function handling the request. That way cancellation and error propagation remain tied to the request lifecycle.

For me, this configuration is the middle ground: useful for application-owned background work that should be explicit, observable, and cleaned up correctly, but does not need the durability guarantees of a full job processing system.