ABCoroutines

🧩 Structured concurrency built on JDK 21 Virtual Threads — without the magic.

ABCoroutines is a minimal, composable toolkit for running structured, cancellable tasks on JDK 21+ Virtual Threads from Kotlin.
It offers predictable lifecycle management, coroutine-style helpers, and well-tested patterns for timeouts, retries, races, and channels — all while remaining 100% compatible with kotlinx.coroutines.

💡 Looking for cross-platform concurrency patterns? Check out ABConcurrency — the multiplatform successor bringing these coordination patterns to JVM, JS, and Native.

---

✨ Overview

ABCoroutines makes it easy to use Virtual Threads as structured coroutine dispatchers.
It provides:

• A VirtualThreads CoroutineDispatcher backed by Executors.newVirtualThreadPerTaskExecutor()
• A long-lived applicationScope for launching jobs
• Lifecycle management (ensureRunning, shutdown, reset)
• Blocking entry point runBlockingVT — ideal for main
• High-level coordination patterns: parallel, race, retry, zip — intuitive primitives for concurrent thinking
• Rich timeout, retry, and channel/flow utilities
• Java interop via ABCoroutinesInterop (exposing Executor/ExecutorService)
• Over 160+ tests verifying lifecycle, cancellation, resource safety, and concurrency

---

🎯 Why ABCoroutines?

Think in patterns, not primitives. Instead of wrestling with low-level concurrency:

// Express intent clearly
val userData = parallel(
    { fetchProfile() },
    { fetchPreferences() },
    { fetchNotifications() }
)

// Race multiple strategies
val data = raceForSuccess(
    { getFromCache() },
    { getFromDatabase() },
    { getFromAPI() }
)

// Handle failures gracefully
val result = retry(maxAttempts = 3, initialDelay = 100.milliseconds) {
    unstableOperation()
}

ABCoroutines makes concurrent coordination as natural as sequential programming.

---

🧱 Modules

Module	Purpose
ABCoroutines.kt	Core VT dispatcher lifecycle, scopes, and helpers
AbcApi.kt	Idiomatic façade exposing high-value VT utilities
CoroutinePatterns.kt	Common structured patterns (timeouts, retries, races, channels, flows)
ABCoroutinesInterop.kt	Java-facing executors (Executor, ExecutorService)
src/test/kotlin/...	Comprehensive test suite covering utilities, channels, racing, load, and interop

---

⚙️ Getting Started

1. Add dependency

repositories {
    mavenCentral()
}

dependencies {
    implementation("tech.robd:abcoroutines:")
}

Requires JDK 21+.

2. Run your first Virtual Thread task

import tech.robd.abcoroutines.ABCoroutines

fun main() {
    ABCoroutines.runBlockingVT {
        val job = launchVT {
            println("Hello from a Virtual Thread: ${Thread.currentThread().isVirtual()}")
        }
        job.join()
    }
}

---

🚀 Quick Examples

Parallel execution

val results = AbcApi.parallelVT(
    { fetchUser() },
    { fetchSettings() },
    { fetchPermissions() }
)
println(results)

Zip results

val combined = AbcApi.zipVT(
    { loadConfig() },
    { fetchRemoteDefaults() }
) { config, defaults ->
    config.merge(defaults)
}

Race for success

val result = AbcApi.raceForSuccess(
    ABCoroutines.asyncVT { callFastBackup() },
    ABCoroutines.asyncVT { callSlowPrimary() }
)
println("Winner: $result")

Retry with backoff

val data = retry(
    maxAttempts = 3,
    initialDelay = 100.milliseconds
) {
    fetchFromNetwork()
}

Timeout with fallback

val response = cancelIfExceedsOrElse(500.milliseconds, fallback = { "timeout" }) {
    slowApiCall()
}

Bounded concurrency

val results = urls.mapConcurrent(concurrency = 5) { url ->
    fetchPage(url)
}

Channels & Flows

val results = flowOf(1, 2, 3, 4, 5)
    .parallelMap(concurrency = 2) { process(it) }
    .toList()

---

🧩 Java Interop

import tech.robd.abcoroutines.interop.ABCoroutinesInterop;
import java.util.concurrent.CompletableFuture;

public class Example {
    public static void main(String[] args) throws Exception {
        var exec = ABCoroutinesInterop.virtualThreadExecutor();
        var future = CompletableFuture.supplyAsync(() -> {
            System.out.println(Thread.currentThread().isVirtual());
            return "done";
        }, exec);
        System.out.println(future.get());
    }
}

---

🧪 Testing Highlights

ABCoroutines includes a full JUnit 5 suite covering:

• ✅ Lifecycle control — shutdown, reset, ensureRunning
• ✅ Cancellation propagation
• ✅ Timeouts, retries, and race patterns
• ✅ Parallel & bounded concurrency
• ✅ Channel/Flow utilities
• ✅ Interop executors
• ✅ Load and resource cleanup

Example:

./gradlew test

Key test classes:

• ABCoroutinesCancellationTests
• ConcurrencyAndRacingTests
• IntegrationAndLoadTests
• ChannelAndFlowTests
• CoreRawExecutorInteropTests

---

🧠 Design Philosophy

ABCoroutines is intentionally small, explicit, and unmagical:

• No hidden thread pools — just Virtual Threads
• No global mutable context — scopes are explicit
• Predictable shutdown and reset
• Interop with existing kotlinx.coroutines APIs
• Coordination patterns as primitives — think in terms of parallel, race, retry rather than threads and locks
• Focused, readable helpers instead of frameworks

If you know coroutines, you can use ABCoroutines immediately.

---

🔮 Roadmap

• Core Virtual Thread dispatcher and lifecycle
• Comprehensive concurrency patterns
• Java interop layer
• abcoroutines-jcoroutines-interop — Advanced interop for testing and porting Java JCoroutines code to Kotlin, avoiding lock-in
• ABConcurrency — Cross-platform coordination patterns (JVM, JS, Native)
• IDE integration with pattern detection
• Educational materials and tutorials

---

🧩 Related Projects

• JCoroutines — Structured concurrency for pure Java 21
• ABCoroutines-JCoroutinesInterop (Coming Soon) — Demonstrates Java ⇆ Kotlin structured concurrency bridge
• ABConcurrency (Coming Soon) — Cross-platform concurrency patterns for Kotlin Multiplatform

---

📜 License

Copyright 2025 Rob Deas

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy at

http://www.apache.org/licenses/LICENSE-2.0

---

📦 Status

• Version: 0.1.0
• License: Apache 2.0
• Build: Gradle Kotlin DSL
• Tested: JDK 21

🧩 ABCoroutines: Structured concurrency for Virtual Threads — lightweight, explicit, and ready for real workloads.