A faithful C++ port of kotlinx.coroutines, designed to create a semantically aligned bridge between Kotlin's coroutine runtime and C++ applications. This enables seamless interoperability with Kotlin/Native's garbage collector while providing standalone C++ coroutine functionality.

#include <kotlinx/coroutines/Builders.hpp>

int main() {
    using namespace kotlinx::coroutines;

    run_blocking([](auto& scope) {
        scope.launch([](auto& ctx) {
            delay(1000);
            std::cout << "Kotlin Coroutines World!" << std::endl;
        });
        std::cout << "Hello" << std::endl;
    });
    return 0;
}

The flagship feature of this implementation is seamless coordination with Kotlin/Native's garbage collector:

#include <kotlinx/coroutines/KotlinGCBridge.hpp>

extern "C" void native_inference() {
    // Without guard: GC waits 100ms, blocking all Kotlin threads
    // With guard: GC proceeds immediately, ~50-100x improvement
    kotlinx::coroutines::KotlinNativeStateGuard guard;
    run_expensive_computation();  // Takes 100ms
}

Key Benefits:

• Zero overhead when running standalone (functions inline away completely)
• Weak-linked Kotlin Native runtime functions for automatic detection
• RAII-based state management with exception safety guarantees
• Thread-safe with no synchronization overhead

The suspension system uses a sophisticated atomic state machine that eliminates exception-based control flow:

// Three-state decision model: UNDECIDED -> SUSPENDED or RESUMED
class CancellableContinuationImpl {
    std::atomic<int> decision_{DECISION_UNDECIDED};

    // Lock-free coordination between suspend and resume
    int try_suspend();   // Returns COROUTINE_SUSPENDED or result
    void try_resume();   // Coordinates with suspension atomically
};

This approach provides:

• Deterministic behavior without exception overhead
• Lock-free suspension/resumption coordination
• Proper cancellation semantics matching Kotlin's model

Every API maintains semantic equivalence with the original Kotlin implementation:

kotlin.coroutines-cpp/
├── include/kotlinx/coroutines/    # Public C++ headers
│   ├── Builders.hpp               # launch, async, runBlocking
│   ├── Job.hpp                    # Job hierarchy and lifecycle
│   ├── Deferred.hpp               # Async result handling
│   ├── Flow.hpp                   # Cold async streams
│   ├── channels/                  # Channel implementations
│   │   ├── Channel.hpp
│   │   └── BufferedChannel.hpp
│   ├── KotlinGCBridge.hpp         # GC coordination (flagship)
│   └── ...
├── kotlinx-coroutines-core/       # Core implementation
├── kotlinx-coroutines-test/       # Test utilities
└── docs/                          # Documentation

• launch and async coroutine builders
• Job and Deferred with proper cancellation
• Channel with all buffer strategies
• Flow with operators: map, filter, collect, take, drop, etc.
• delay and timing operations
• Mutex and Semaphore synchronization
• Kotlin Native GC bridge (zero-overhead)
• Atomic state machine suspension

• Darwin-specific dispatchers (Grand Central Dispatch integration)
• Complete select expression implementation
• withContext function
• Debug probes and coroutine inspection
• Performance benchmarking infrastructure

• C++17 compatible compiler (GCC 9+, Clang 10+, MSVC 2019+)
• CMake 3.16+

mkdir build && cd build
cmake ..
make

When linking with Kotlin Native (for GC bridge coordination):

mkdir build && cd build
cmake -DKOTLIN_NATIVE_RUNTIME_AVAILABLE=ON ..
make

# After building, test binaries are in build/bin/
./build/bin/test_job
./build/bin/test_dispatchers
./build/bin/test_suspend

# Or use CTest
cd build && ctest

#include <kotlinx/coroutines/Builders.hpp>

run_blocking([](auto& scope) {
    auto job = scope.launch([](auto& ctx) {
        std::cout << "Starting work..." << std::endl;
        delay(1000);
        std::cout << "Work complete!" << std::endl;
    });

    job->join();  // Wait for completion
});

auto deferred = scope.async<int>([](auto& ctx) {
    delay(500);
    return 42;
});

int result = deferred->await();  // Suspends until result ready

auto channel = Channel<int>::create(Channel<int>::BUFFERED, 10);

scope.launch([&](auto& ctx) {
    for (int i = 0; i < 10; i++) {
        channel->send(i);
    }
    channel->close();
});

scope.launch([&](auto& ctx) {
    for (auto value : *channel) {
        std::cout << "Received: " << value << std::endl;
    }
});

flow_of({1, 2, 3, 4, 5})
    .filter([](int x) { return x % 2 == 0; })
    .map([](int x) { return x * x; })
    .collect([](int x) {
        std::cout << x << std::endl;  // Prints: 4, 16
    });

#include <kotlinx/coroutines/KotlinGCBridge.hpp>

// Called from Kotlin/Native code
extern "C" void process_data(const char* data) {
    // Signal to GC that this thread is doing native work
    kotlinx::coroutines::KotlinNativeStateGuard guard;

    // GC can proceed without waiting for this thread
    expensive_native_operation(data);

    // Guard destructor restores runnable state
}

• Comprehensive Audit Report - Detailed implementation analysis
• Kotlin GC Bridge Implementation - GC bridge summary
• Kotlin GC Bridge Specification - Technical specification
• Coroutines Guide - Usage patterns and best practices
• API Reference - Component documentation

Contributions are welcome! Key areas needing attention:

1. Darwin Dispatchers - Grand Central Dispatch integration
2. Select Expression Internals - Complete the select implementation
3. Performance Optimization - Lock-free data structures
4. Documentation - Usage examples and guides

See CONTRIBUTING.md for guidelines.

This project is a derivative work based on kotlinx.coroutines by JetBrains. The original Kotlin implementation provided the semantic foundation and API design that this C++ port faithfully follows.

Special thanks to:

• The Kotlin team at JetBrains for the excellent original implementation
• Roman Elizarov for the coroutine design and structured concurrency concepts

Copyright 2000-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
Copyright 2025 Sydney Renee and The Solace Project contributors.

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 of the License at

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

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Maintainer: Sydney Renee (sydney@solace.ofharmony.ai) Project: The Solace Project