Async
Kotlin

import kotlinx.coroutines.*

fun main() = runBlocking {  // bridges blocking world → coroutines

    // launch — fire-and-forget, returns Job
    val job: Job = launch {
        delay(1000L)           // suspend (non-blocking sleep)
        println("World!")
    }
    println("Hello,")
    job.join()              // suspend until job completes

    // async — returns Deferred<T> (a result later)
    val deferred: Deferred<String> = async {
        delay(500L)
        "computed result"
    }
    println(deferred.await()) // suspend until ready
}

// Output:
// Hello,
// World!
// computed result

// The "Pyramid of Doom" — callback style
getUser(userId) { userResult ->
    if (userResult.isError) { handleError(userResult.error); return }
    getOrders(userResult.data.id) { ordersResult ->
        if (ordersResult.isError) { handleError(ordersResult.error); return }
        getProducts(ordersResult.data.first().id) { productsResult ->
            if (productsResult.isError) { handleError(productsResult.error); return }
            render(productsResult.data) // finally!
        }
    }
}

// ── The coroutine equivalent — flat and readable ───────
suspend fun loadDashboard(userId: String) {
    val user     = getUser(userId)
    val orders   = getOrders(user.id)
    val products = getProducts(orders.first().id)
    render(products)   // same result, zero nesting
}

// ── Wrapping a callback API with suspendCoroutine ──────
suspend fun locationOnce(): Location =
    suspendCancellableCoroutine { cont ->
        val cb = LocationCallback { loc -> cont.resume(loc) }
        locationClient.requestUpdate(cb)
        cont.invokeOnCancellation { locationClient.remove(cb) }
    }

suspend fun loadDashboard() = coroutineScope {

    // ── Sequential (slow — each suspends before the next) ─
    val user    = fetchUser()     // ~600ms
    val profile = fetchProfile()  // then ~400ms → total ~1000ms

    // ── Concurrent with async (fast) ──────────────────────
    val dUser    = async { fetchUser() }    // starts immediately
    val dProfile = async { fetchProfile() } // starts immediately
    val dOrders  = async { fetchOrders() } // starts immediately
    // all three in parallel — total ≈ max(600, 400, 800) = 800ms

    Dashboard(
        user    = dUser.await(),
        profile = dProfile.await(),
        orders  = dOrders.await()
    )
}

// awaitAll — idiomatic shorthand for a list of Deferred
val results: List<Data> = (1..10)
    .map { id -> async { api.fetch(id) } }
    .awaitAll()

// ── Basic suspend function ─────────────────────────────
suspend fun fetchUser(id: String): User {
    delay(500)               // suspends without blocking thread
    return api.getUser(id)
}

// ── withContext — switch dispatcher mid-coroutine ──────
suspend fun readFile(path: String): String =
    withContext(Dispatchers.IO) {   // moves to IO thread pool
        File(path).readText()
    }                           // returns to original dispatcher

// ── Reads top-to-bottom like synchronous code ─────────
suspend fun loadAll(userId: String) {
    val user     = fetchUser(userId)
    val orders   = fetchOrders(user.id)
    val products = fetchProducts(orders.first().id)
    render(products)
}

// ── Suspension order in a single coroutine ────────────
fun main() = runBlocking {
    println("1 — sync")

    launch { println("4 — child coroutine (launched)") }

    // yield() suspends and lets other coroutines run
    yield()
    println("3 — after yield")
}
// Output: 1 — sync → 3 — after yield → 4 — child coroutine

// ── 1. Retry with exponential backoff ─────────────────
suspend fun <T> withRetry(maxAttempts: Int = 3, block: suspend () -> T): T {
    repeat(maxAttempts - 1) { attempt ->
        try { return block() }
        catch (e: CancellationException) { throw e } // never swallow!
        catch (e: Exception) {
            delay((2.0.pow(attempt) * 1000).toLong()) // 1s, 2s, 4s…
        }
    }
    return block() // last attempt — let it throw
}

// ── 2. Timeout ─────────────────────────────────────────
val result = withTimeout(3000L) { api.fetchData() }

val result = withTimeoutOrNull(3000L) {
    api.fetchData()
} ?: fallbackData()   // null on timeout → use fallback

// ── 3. Flow — cold async streams ───────────────────────
fun paginate(url: String): Flow<List<Item>> = flow {
    var next: String? = url
    while (next != null) {
        val page = api.fetch(next)
        emit(page.items)    // suspend + push each page downstream
        next = page.nextUrl
    }
}.flowOn(Dispatchers.IO)

// collecting a Flow with operators
paginate("/api/items")
    .filter { items -> items.isNotEmpty() }
    .map { items -> items.filter { it.active } }
    .collect { page -> processPage(page) }

// ── 4. Concurrency limiting with Semaphore ────────────
val semaphore = Semaphore(5)   // max 5 concurrent coroutines
items
    .map { item -> async { semaphore.withPermit { process(item) } } }
    .awaitAll()

// ── Pattern 1: try/catch in suspend functions ──────────
suspend fun safeLoad(): Data? {
    return try {
        fetchData()
    } catch (e: NetworkException) {
        logger.warn("Network failed, using cache")
        getCachedData()
    } catch (e: CancellationException) {
        throw e            // always re-throw cancellation!
    } finally {
        cleanup()          // always runs, even if cancelled
    }
}

// ── Pattern 2: CoroutineExceptionHandler ──────────────
val handler = CoroutineExceptionHandler { _, throwable ->
    logger.error("Unhandled coroutine exception", throwable)
}
val scope = CoroutineScope(Dispatchers.IO + handler)
scope.launch { riskyOperation() }

// ── Pattern 3: SupervisorJob — isolate child failures ─
val supervisor = CoroutineScope(SupervisorJob() + Dispatchers.Default)
supervisor.launch { /* failure here does NOT cancel siblings */ }
supervisor.launch { /* this keeps running independently */ }

// ── Pattern 4: runCatching — Result<T> type ───────────
suspend fun safeCall(): Result<Data> = runCatching { fetchData() }

safeCall()
    .onSuccess { data -> render(data) }
    .onFailure { err  -> showError(err) }
    .recover   { _   -> fallback() }    // transform failure to value