Coroutines

A coroutine is a lightweight task that can pause and resume. Unlike a thread, it does not block an OS thread while waiting, so you can run very many of them at once cheaply.

Structured concurrency means every coroutine runs inside a scope, and a parent waits for all its children to finish. If the parent is cancelled, its children are cancelled too — so nothing is left running or leaked.

The compiler rewrites a suspend function into a state machine. Each pause point becomes a state, and the function is given a hidden parameter that lets it remember where to continue from when it resumes.

Each coroutine is just a small object, not an OS thread, so creating one barely costs memory. That lets you have huge numbers of waiting tasks at once without exhausting threads.

Kotlin builds coroutines from a small compiler feature plus a library, instead of changing the runtime. This keeps them portable and cheap, but means they only pause at marked points and you must use suspend-aware libraries.

It is a helper that turns an old-style callback API into a suspend function. You pause the coroutine, then call resume in the callback to continue with a result, or resumeWithException to fail.

The compiler rewrites a suspend function to take a hidden extra parameter representing 'what to do next'. When the function pauses, it hands work back to that callback and resumes later instead of blocking a thread.

suspend marks a function that can pause and resume later without blocking its thread. You can only call it from a coroutine or from another suspend function.

invokeOnCancellation runs a cleanup block when the coroutine is cancelled while suspended, so you can stop the underlying work. After cancellation any value you try to resume with is ignored, so close it safely.

The compiler splits the function at each pause point into numbered states. A label counter remembers which state to run next, so when the function resumes it jumps straight to the right spot instead of starting over.

async starts a background task and hands you a Deferred. You call await() on it to wait for and receive the result value.

launch starts a new coroutine that runs in the background without giving you a result. It returns a Job, a handle you can use to wait for it to finish or to cancel it.

runBlocking is a bridge that lets regular blocking code call suspend functions. It blocks the current thread until the coroutines inside finish. Use it in main() and tests, not inside other coroutines.

coroutineScope starts a block where you can run several coroutines and it waits for all of them to finish before returning. It does not block the thread; it only suspends.

withContext runs a block of suspending code on a different thread pool and waits for its result. You wrap blocking I/O in withContext(Dispatchers.IO) so it does not freeze the main thread, then it returns the value.

It is a small set of settings carried by every coroutine. It bundles things like which thread pool runs the coroutine, its Job (lifecycle), and an optional name, so each coroutine knows how it should run.

A dispatcher decides which thread a coroutine runs on. Use Default for heavy CPU work like sorting or parsing, and IO for waiting on network or disk calls.

It creates a view of a dispatcher that lets at most n coroutines run at the same time. You use it to cap how much work hits a limited resource, like a database or an external API.

Each setting in the context is an Element tagged with a unique Key. You look one up by indexing with its key. Every single element is itself a tiny one-item context, which is why you can add them together with +.

The + operator merges two contexts into a new one. If both sides contain the same kind of element (say two dispatchers), the one on the right wins and replaces the one on the left.

A Job is a handle to a running coroutine. It can be active, can complete, or can be cancelled. You can wait for it, cancel it, or check if it is still running.

coroutineScope runs a block, starts child coroutines inside it, and waits until all of them finish before returning. GlobalScope launches coroutines that are not tied to anything and can outlive your code, so they can leak.

The object creates a scope to launch background work tied to its life. When the object is done, it cancels the scope, which stops every coroutine started in it so nothing keeps running and leaking.

Every coroutine runs inside a scope, and that scope won't finish until all the coroutines it started have finished. This stops background work from being forgotten or leaking.

A SupervisorJob is a special parent for coroutines. If one child crashes, the others keep running and the parent stays alive. With a regular Job, one crash cancels everything.

Cancellation is cooperative: the coroutine only stops if it checks for cancellation. A pure CPU loop never checks, so it ignores cancel(). Add a check inside the loop, such as while (isActive).

No. cancel() just marks the job as cancelled. The coroutine actually stops the next time it pauses at a suspending call. If it never pauses, it keeps running.

When a coroutine is cancelled, trying to suspend again (like awaiting a call) in finally immediately throws cancellation, so cleanup is skipped. Wrapping that cleanup in withContext(NonCancellable) lets it suspend and complete.

Both run a block of code with a time limit. If the work takes too long, withTimeout throws an error, while withTimeoutOrNull just returns null. Use them so slow operations don't hang forever.

isActive is a Boolean you test to exit the loop without throwing. ensureActive() throws CancellationException if cancelled. yield() throws too and also lets other coroutines run. Pick by whether you want to throw and/or reschedule.

The exception is stored inside the Deferred result and is re-thrown when you call await() on it. Calling async itself does not throw.

It is a piece of coroutine context that acts as a last-resort catcher. When a coroutine started with launch fails and nobody else handles the exception, this handler runs instead of crashing silently.

The coroutine fails. The error travels up to its parent, which cancels itself and its other child coroutines, and then the error is reported.

With a normal Job, if one child crashes, the parent and all the other children are cancelled too. With a SupervisorJob, a crashing child only affects itself; its siblings keep running.

await() decides where YOU see the error. But the async is also a child coroutine, so when it fails it tells its parent Job, which cancels the parent and all siblings — regardless of whether you await.

A Channel is a pipe between coroutines. One coroutine puts values in with send, another takes them out with receive. Both suspend (wait politely) until the other side is ready.

synchronized blocks the whole thread while it waits. Coroutines share threads, so blocking one stalls others. Kotlin's Mutex instead suspends the coroutine, freeing the thread for other work.

Capacity controls how many values a channel holds before send has to wait. Rendezvous holds none, buffered holds a few, unlimited holds everything, and conflated keeps only the latest and never waits.

withLock acquires the lock, runs your block, and always releases it afterward — even if the block throws or the coroutine is cancelled. Manual lock()/unlock() makes you remember to release it yourself.

With produce the coroutine makes values for you, so you get the read end (ReceiveChannel). With actor you feed it messages, so you get the write end (SendChannel). Each is the opposite end of the channel from what the coroutine uses.