Capy and Boost.Cobalt: A Comparison

An I/O library should make the implementation completely invisible to its consumers. Public headers declare the interface — types, functions, contracts. All platform-specific machinery lives in the translation unit. No implementation detail leaks into the consumer’s code.

Capy achieves the Dimovian Ideal. The proof is in example/asio/.

Capy defines seven coroutine-only stream concepts. Cobalt inherits Asio’s AsyncReadStream and AsyncWriteStream, which are hybrid concepts supporting callbacks, futures, and coroutines. Cobalt’s cobalt::io wrappers simplify the API and Cobalt defines stream abstractions (write_stream, read_stream, stream) as abstract base classes, a distinct approach from Capy’s concept-based hierarchy. Cobalt’s wrappers still include full Asio headers. See Write Stream Design for a detailed comparison of the two approaches.

Capy’s concepts form a refinement hierarchy that emerged naturally from use-case-first design:

BufferSource and BufferSink implement callee-owns-buffers I/O. The source provides buffers; the caller processes them in place. No copies. Memory-mapped files, hardware DMA buffers, and kernel-provided memory all work naturally through this pattern.

Traditional approaches to type erasure in Asio focus on the lowest-level elements: the completion handler, the executor, the allocator. This is not the right layer. Type-erasing these individually adds overhead at every customization point while still leaving the stream type concrete and visible.

Capy type-erases the stream itself. This is possible because coroutines provide structural type erasure — the continuation is always a handle, not a template parameter. When the library is coroutines-only, one virtual call per I/O operation is the total cost. The completion handler, executor, and allocator do not need individual erasure because they are not part of the stream’s operation signature.

Cobalt defines stream abstractions (write_stream, read_stream, stream) as abstract base classes in cobalt/io/stream.hpp, taking a different approach from Capy’s concept + type-erased wrapper model. See Write Stream Design for a side-by-side analysis.

The wrappers compose. any_buffer_source also satisfies ReadSource — natively if the wrapped type supports both, synthesized otherwise. any_buffer_sink also satisfies WriteSink. You pick the abstraction level you need.

This is how the Dimovian Ideal is mechanically achieved.

When algorithms operate on type-erased interfaces, testing becomes deterministic. Capy provides mock implementations for every stream concept. Cobalt defines stream abstractions as abstract base classes but does not provide mock implementations for testing. See Write Stream Design for a comparison of the two stream designs.

Capy’s mock types:

test::fuse injects errors systematically at every I/O operation point. test::run_blocking executes coroutines synchronously for deterministic unit tests. max_read_size and max_write_size simulate chunked delivery. expect() validates written data.

Tests run without sockets or network access, eliminating non-determinism.

Cobalt is single-threaded by design. One executor per thread. Channels are restricted to a single thread — Cobalt’s own documentation states: "Channels can be used to exchange data between different coroutines on a single thread." Primitives cannot be shared between threads.

Capy supports multi-threaded execution. thread_pool distributes work across threads. strand serializes execution without blocking OS threads. The Executor concept is open — implement your own.

Cobalt stores executor context in thread-local variables. Coroutines access it via this_coro::executor. This works on a single thread with a single executor. This design is scoped to single-threaded, single-executor configurations.

Capy introduces the IoAwaitable protocol and uses it for context propagation. When you co_await, the caller passes its execution environment to the child structurally:

No thread-local state. No ambient context. The executor and stop token flow forward through the call chain via the io_env parameter.

Both libraries propagate cancellation automatically through coroutine chains. Both support OS-level cancellation of pending I/O operations (CancelIoEx on Windows, IORING_OP_ASYNC_CANCEL on Linux).

Capy uses std::stop_token, propagated via the IoAwaitable protocol’s io_env parameter. The token flows forward structurally alongside the executor.

Cobalt uses Asio’s cancellation_signal and cancellation_slot. Propagation is wired automatically in await_suspend via forward_cancellation. this_coro::cancellation_state provides filtering control over which cancellation types pass through.

Capy adopts Asio’s buffer sequence model — ConstBufferSequence, MutableBufferSequence — because it works. Capy’s buffer types are fully compatible with Asio’s. You can pass Capy buffers to Asio operations and vice versa, seamlessly. Then Capy extends the model with additional types and algorithms, while still achieving the Dimovian Ideal — none of this requires exposing Asio headers to consumers.

Cobalt does not provide buffer sequence types or dynamic buffer support. Users who need these features use Asio’s types directly, inheriting the DynamicBuffer_v1/DynamicBuffer_v2 split.

Capy has one DynamicBuffer concept. The v1/v2 split in Asio exists because of a fundamental ownership problem: when an async operation takes a buffer by value and completes via callback, who owns the buffer? The original design had flaws, and the fix created two incompatible versions. By going coroutines-only, Capy avoids this entirely. The coroutine frame owns the buffer. Parameters have their lifetimes extended by the suspended frame, and the awaitable lives in the frame alongside them. There is no decay-copy, no ownership transfer, no ambiguity. One concept is sufficient.

Cobalt sets up a thread-local PMR resource via main or thread. All coroutines on that thread share it. Every awaitable embeds a fixed SBO buffer:

If the buffer is exhausted, allocations fall back to the upstream PMR resource or operator new. The buffer size is a compile-time constant. Changing it requires recompiling the library.

Capy leaves these decisions to the user. run_async(executor, allocator)(my_task()) sets the allocator before the task is created. The task’s operator new reads it from thread-local storage. This is a small, flexible customization point that permits usage patterns the authors did not anticipate: per-connection arenas, bounded pools, tracking allocators, per-tenant memory budgets. The allocation strategy is a deployment decision, not a library decision.

recycling_memory_resource provides zero-overhead recycling after warmup. Memory isolated per connection. Reclaimed instantly on disconnect.

Cobalt is coupled to Asio’s io_context. The execution model and the platform abstractions are one thing.

Capy separates them. The execution model — executors, cancellation, allocation — lives in Capy. Platform abstractions live in Corosio, a companion library that provides native TCP sockets, acceptors, TLS streams, timers, DNS resolution, and signal handling — all built on Capy’s IoAwaitable protocol with native IOCP and epoll backends. You can test Capy’s execution model without a network stack. You can swap the I/O backend without changing your application code.

To measure the overhead that coroutines add to a real workload, an experimental JSON serializer drives output through a chain of co_await calls instead of direct function calls. Each JSON value type — null, bool, integer, double, string, array, object — is handled by a coroutine that writes fragments through a write_sink. The baseline is boost::json::serialize, a highly optimized non-coroutine implementation.

The input is numbers.json from the Boost.JSON benchmark suite. Results are best-of-four runs, Clang 20, -O3, Windows x64:

Capy’s coroutine-driven serializer runs at 1.69x the baseline. Cobalt’s promise is 4.29x. Cobalt’s task is 82x.

The Capy implementation:

Every co_await ws.write(…​) call creates a coroutine frame, suspends, resumes, and destroys. This is the worst case for coroutine overhead — many tiny operations that complete synchronously. In a real application where I/O operations take microseconds or milliseconds, the coroutine machinery becomes negligible.