Jank Concurrency Model Proposal: Stackless Coroutine Concurrency with C++20 and ASIO

[divs1210]

Jank Concurrency Model Proposal: Stackless Coroutines with C++20 and ASIO

RFC / Design Proposal — MVP
C++20 coroutines + ASIO reactor + ForkJoin work-stealing pool.

---

API Reference

Function	Description
(future & body)	Spawn coroutine on global pool
(deref f) / @f	Suspend until f resolves; rethrows on exception or cancellation
(cancelled? f)	True if f is in CANCELLED state
(cancel f)	Cancel a pending future; notifies all waiters

Suspension occurs only at future/deref boundaries — ordinary functions need no async annotation. The top level runs in an implicit root coroutine.

MVP scope: global pool, futures, deref, cancellation, shutdown, native async I/O.
Post-MVP: custom pools, blocking FFI offload (on-io-pool), foreign-thread re-entrancy (jank_post).

---

Architecture

Component	Responsibility
Reactor (asio::io_context)	Async I/O and OS events; dedicated thread. Never executes user code.
Scheduler (ForkJoin pool)	Coroutine execution, work-stealing

All ready-queue pushes and semaphore posts go through enqueue — push and post are always paired:

void enqueue(std::coroutine_handle<> h) {
    global_ready_queue.push(h); // always use enqueue(); never call these directly
    semaphore.post();
}

Each ForkJoin worker:

while (true) {
    handle = pop_local() ?: steal_from_other() ?: pop_global_ready_queue();
    if (handle) handle.resume();
    else        worker_wait_on_semaphore();
}

Startup:

int main() {
    runtime::init();
    scheduler.schedule(program_entry());   // implicit root coroutine
    reactor_thread = std::thread([]{ io_ctx.run(); });
    scheduler.run();                       // blocks until drained
    reactor_thread.join();
    runtime::shutdown();
}

---

Futures

States: PENDING → {RESOLVED | EXCEPTION | CANCELLED}. Transitions are atomic and final. Always managed via shared_ptr.

struct future : std::enable_shared_from_this<future> {
    std::atomic<State> state{PENDING};
    std::variant<std::monostate, value_type,
                 std::exception_ptr, cancellation_error> result;
    std::mutex                             waiters_mu;
    bool                                   closed = false; // prevents lost wakeups
    std::vector<std::coroutine_handle<>>   coroutine_waiters;
    std::vector<std::condition_variable*>  thread_waiters;
};
using future_ptr = std::shared_ptr<future>;

result is written inside waiters_mu before state.store. The waiter list is moved out before flushing — each handle enqueued exactly once:

void future::resolve(value_type v) {
    std::vector<std::coroutine_handle<>> local_coro;
    std::vector<std::condition_variable*> local_threads;
    {
        std::lock_guard lk(waiters_mu);
        result = std::move(v);          // (1) write result under lock
        closed = true;
        local_coro    = std::move(coroutine_waiters); // (2) drain — no duplicates
        local_threads = std::move(thread_waiters);
    }
    state.store(RESOLVED, std::memory_order_release); // (3) publish after lock
    for (auto h  : local_coro)    enqueue(h);
    for (auto cv : local_threads) cv->notify_one();
}
// cancel() and set_exception() follow the same move-and-flush path.

deref Awaitable

await_ready and await_suspend are not atomic — re-check closed after acquiring the lock. The awaitable holds a shared_ptr to its future for the entire suspension interval:

struct deref_awaitable {
    future_ptr fut; // keeps future alive while suspended

    bool await_ready() {
        return fut->state.load(std::memory_order_acquire) != PENDING;
    }

    void await_suspend(std::coroutine_handle<> h) {
        std::lock_guard lk(fut->waiters_mu);
        if (fut->closed) { enqueue(h); return; } // already resolved — self-enqueue
        fut->coroutine_waiters.push_back(h);
    }

    value_type await_resume() {
        if (std::holds_alternative<std::exception_ptr>(fut->result))
            std::rethrow_exception(std::get<std::exception_ptr>(fut->result));
        if (std::holds_alternative<cancellation_error>(fut->result))
            throw std::get<cancellation_error>(fut->result);
        return std::get<value_type>(fut->result);
    }
};

---

Async I/O

The awaitable is heap-allocated via shared_ptr — captured by value in the completion lambda, eliminating the dangling-this hazard. The reactor calls enqueue; a ForkJoin worker resumes the coroutine:

struct async_read_awaitable {
    tcp::socket& socket;
    asio::mutable_buffer buf;
    std::error_code ec;  std::size_t n = 0;
    std::shared_ptr<async_read_awaitable> self; // self-ref broken on destroy

    bool await_ready() { return false; }

    void await_suspend(std::coroutine_handle<> h) {
        auto keep_alive = self; // extend lifetime until handler fires
        socket.async_read_some(buf, [keep_alive, h](auto ec_, auto n_) mutable {
            keep_alive->ec = ec_;  keep_alive->n = n_;
            enqueue(h); // reactor thread posts to scheduler; never touches frame
        });
    }

    std::pair<std::error_code, std::size_t> await_resume() { return {ec, n}; }
};

auto make_async_read(tcp::socket& s, asio::mutable_buffer buf) {
    auto p = std::make_shared<async_read_awaitable>(s, buf);
    p->self = p;
    return p;
}

// Usage: auto [ec, n] = co_await *make_async_read(socket, buffer);

---

Exceptions and Cancellation

Exceptions inside a future body are caught at the coroutine boundary and rethrown by deref — matching Clojure semantics. The entire body including co_return is wrapped:

task future_body() {
    try {
        auto val = user_code(); // return-value construction inside try
        co_return val;
    } catch (...) {
        promise.set_exception(std::current_exception());
    }
}

cancel sets alive = false before flushing waiters. In-flight ASIO handlers check the flag and skip enqueue, preventing a cancelled coroutine from being re-queued. Running bodies must poll (cancelled? f) — cancel does not preempt:

void future::cancel() {
    std::vector<std::coroutine_handle<>> local_coro;
    std::vector<std::condition_variable*> local_threads;
    {
        std::lock_guard lk(waiters_mu);
        if (closed) return;
        result = cancellation_error{};
        closed = true;
        if (alive) alive->store(false, std::memory_order_release); // signal handlers before flush
        local_coro    = std::move(coroutine_waiters);
        local_threads = std::move(thread_waiters);
    }
    state.store(CANCELLED, std::memory_order_release);
    for (auto h  : local_coro)    enqueue(h);
    for (auto cv : local_threads) cv->notify_one();
}

---

Shutdown

1. Root coroutine returns or throws → initiate_shutdown called (idempotent; also called from unhandled_exception)
2. All live futures cancelled; parked waiters receive CancellationException
3. Scheduler waits for live-coroutine counter to reach zero
4. work.reset() releases the ASIO work guard; io_ctx.run() returns
5. Reactor thread joined; runtime::cleanup runs

---

Coroutine Frame GC Integration

Jank uses Boehm GC. Suspended frames live on the heap outside Boehm's stack scan and must be explicitly rooted. Frames are allocated via GC_malloc_uncollectable; size is stored at allocation for use in register/unregister without ABI tricks. Roots are registered before enqueue — before any worker or GC cycle can see the handle:

struct task_promise {
    void* frame_addr = nullptr;  std::size_t frame_size = 0;
    bool  roots_registered = false;

    void* operator new(std::size_t sz) {
        void* p = GC_malloc_uncollectable(sizeof(std::size_t) + sz);
        *static_cast<std::size_t*>(p) = sz; // store size alongside frame
        return static_cast<char*>(p) + sizeof(std::size_t);
    }
    void operator delete(void* ptr) {
        GC_free(static_cast<char*>(ptr) - sizeof(std::size_t));
    }
    ~task_promise() {
        if (roots_registered)
            GC_remove_roots(frame_addr, static_cast<char*>(frame_addr) + frame_size);
    }
};

// await_suspend: root BEFORE enqueue
void await_suspend(std::coroutine_handle<> h) noexcept {
    auto& p = h.promise();
    GC_add_roots(p.frame_addr, static_cast<char*>(p.frame_addr) + p.frame_size);
    p.roots_registered = true;
    enqueue(h); // only now visible to scheduler
}

// await_resume: unroot after frame is back on the call stack
result_type await_resume() {
    auto& p = handle_.promise();
    if (p.roots_registered) {
        GC_remove_roots(p.frame_addr, static_cast<char*>(p.frame_addr) + p.frame_size);
        p.roots_registered = false;
    }
    return extract_result();
}

Known limitation: GC correctness under high optimization depends on the compiler not eliminating interior pointers inside the frame. MVP mitigations: build at -O1 initially; GC tests must include suspended coroutines holding the only live reference to a jank object; TSan + fuzzer pass required before shipping.

---

Runtime Guarantees

Guarantee	Notes
Cooperative suspension	deref suspends via co_await; pool thread picks up other work
Scheduler-controlled resumption	Coroutines resumed only by ForkJoin workers via the ready queue
Reactor isolation	No user code runs on the reactor thread
Deterministic shutdown	Drains live-coroutine counter before releasing work guard
No abandoned coroutines	Shutdown cancels all live futures before drain
GC-safe frames	GC_malloc_uncollectable + size stored at allocation; roots registered before enqueue
Semaphore correctness	All pushes via enqueue; push and post always paired
No duplicate wakeups	Waiter list moved out under lock before flush
Cooperative cancellation	alive=false set before flush; in-flight handlers skip enqueue
Future lifetime safety	shared_ptr-managed; waiters hold a copy for the suspension interval
Awaitable lifetime safety	Async awaitables heap-allocated via shared_ptr; captured by value in lambdas
Exception safety	Entire coroutine body including return-value construction wrapped in try/catch

---

Post-MVP

Feature	Reason deferred
on-io-pool / asio::thread_pool	Blocking FFI offload; complex lifetime interaction with cancellation
jank_post / foreign-thread re-entrancy	No MVP FFI consumer requiring it
Custom pools (make-pool, future my-pool)	Pool isolation unenforceable without affinity tracking

[divs1210]

Hey @jeaye, our conversation on Reddit got me thinking.

Your reference to C++ coroutines was especially interesting.

I ended up spending my evening working on this proposal.

I've tried to be thorough, and taken AI help to refine and compile it into the final document.

That said, this is obviously a rough sketch cooked up in a short time.

Would love to know your thoughts.

[jeaye]

Thanks for the proposal! Also, thank you for following the contribution guidelines and calling out the use of AI.

Overall, I'm interested in jank having an excellent concurrency story. I know that Rust has struggled with getting something which checks all of the boxes and I would want to understand their design and its issues before committing to anything for jank. On my plate, this is a post-alpha topic, for no sooner than next year. On someone else's plate, though, this could start whenever, as an exploration.

With that said, one approach is to see how complex the implementation is, with this design, and how it holds up to battle testing. If we can hook it into a jank port of core.async, we should be able to both stress test the system and get some useful benchmarking done. That's a pretty involved task, altogether.

[divs1210]

I understand this is not your priority at the moment, and for very good reasons.

I'm mostly a Clojure/Java/JS guy with superficial knowledge of C++.

But I like the challenge, and would really like to have a native concurrent Clojure.

In this proposal I've tried to mimic the Rust / Go runtimes by separating the reactor and scheduler.

The single biggest implementation challenge that I can see is the integration with Boehm GC.

I will keep editing this document as per my research, and might attempt a poc implementation in the future.

I agree hooking up a core.async implementation would be great.

Thanks!

[divs1210]

Hi @jeaye, I actually ended up spending a considerable amount of time on this, and ended up doing something I had been procrastinating for a long time.

Presenting libgoc: a Go-style CSP concurrency runtime for C: threadpools, stackful coroutines, channels, select, async I/O, and garbage collection in one coherent API.

Next I'm going to make an idiomatic C++ wrapper for this.

I made this because I'm acutely aware of what a terrible compilation target Go-lang is, and how much scheme/lisp implementors love C. 😄

I've made it especially for native lisp implementations like Jank, which can quickly bootstrap a strong multithreaded concurrency system - just like Boehm did for GCs.

Your work on Jank is a huge motivation, and the prime mover that got me off my butt and I finally got around to making this. 🙏

Will look forward to your thoughts on it!

[jeaye]

That's cool to see! The native GC support is a great convenience. :)

The main things, with something as complex as a concurrency library, are:

1. Battle testing
2. Benchmarking

So, in terms of next steps, it'd be great to benchmark libgoc against:

• Actual Go
• Clojure JVM + core.async
• Async Rust

A great benchmark would focus on channel coordination and throughput and less on non-async code like number crunching. There may be some existing benchmarks which Go, core.async, and/or Rust/tokio folks are using.

Following that, if you're interested, since this is a C library which hooks into BDWGC, we should be able to use this directly from jank code without compiler support needed. So it should be feasible to actually test this out using jank.

[divs1210]

Agree with you on both counts!

I have just wrapped up with the scoped work of the initial release.

The library is well-tested, as in it has a pretty decent test suite. Battle testing will require time.

Benchmarking is my next priority. The plan is to pick up existing (Go / JVT / core.async) benchmarks repo(s), and add libgoc benchmarks.

My expectation is that it will be competetive, at the very least, if not the best, since minicoro (that libgoc uses) is blazing fast.

Once I'm done with that, I'll try integrating it with Jank. 🙌

But no, it can not be called directly from jank. It is basically the runtime - it has init and shutdown functions that should be called at the start and end of each program.

libgoc's GC is thread/fiber-aware and requires deep integration. It is trivial to swap out GC_ malloc in the compiler for goc_malloc.

Used the right way, libgoc provides a runtime environment exactly the same as Go's - the blocking versions of take/put/alts will never be seen or required by jank users.

A compiled jank program's main function (in C/C++) would look like this:

static void main_fiber(void* _) {
    // User code comes here.
    // Since this is a fiber context,
    // async channel ops work here
    // and in all code reachable from here
}

int main(void) {
    goc_init();
    // reify main thread as main fiber
    goc_go(main_fiber, NULL);
    goc_shutdown();
    return 0;
}

[divs1210]

As a corollary, if jank's current future implementation isn't registering the underlying thread with the GC, it is probably leaking memory.

[jeaye]

We do that! https://github.com/jank-lang/jank/blob/main/compiler%2Bruntime/src/cpp/jank/runtime/core.cpp#L745

[divs1210]

Glad to know! 🙌

minicoro coroutines need similar special treatment so the GC can reach them.

This is why libgoc links to and wraps over bwdgc.

[divs1210]

Hi, @jeaye!

Hope you're well!

I now have a stable build, and benchmarks to share.

There are also helper libraries for:

• Async I/O
• Dynamic Array
• Telemetry

Now that benchmarks are stable and I have telemetry in place, I'll be working on further optimizations.

LMK what you think!

[jeaye]

Nice work. :) In C++, I think Boost::Asio is the contending async library. It would be good to compare it to libgoc.

I'm not clear on what "libgoc vmem" means.