- Boost - lists.boost.org

[Capy] Review Note
by Vinnie Falco 29 Jun '26

29 Jun '26

This review has surfaced a documentation problem that I want to address directly. Several reviewers have arrived at different (incompatible) conclusions about what Capy is, because we never stated it plainly. Let me try now. *What Capy is* Capy is a proposed standard protocol for coroutine environment propagation, plus a reference implementation of that protocol. The protocol (IoAwaitable) ensures that three things flow correctly through co_await chains: executor, stop token, and allocator. The concrete library - thread pool, task types, byte streams, synchronization primitives - exists to prove the protocol works in practice. *The invariant* Capy enforces one rule: A coroutine always resumes on the executor it was launched with. This isn't a restriction for its own sake. Consider: capy::task<void> handle_client(connection& conn) { auto req = co_await conn.read(); auto resp = process(req); co_await conn.write(resp); conn.stats.requests++; } Launch this on a strand. Every resumption after co_await happens on that strand. conn.stats.requests++ is data-race-free without a mutex. Correct by construction. Without the invariant, after co_await conn.read() you might resume on an io_uring completion thread, a random pool thread, anywhere the I/O subsystem completed. Now you need either a mutex around every access to shared state, or a manual co_await resume_on(my_strand) after every co_await. The first defeats strands. The second is verbose, repetitive, and if you forget one, you have a silent data race. The invariant makes the correct thing automatic and the incorrect thing a compile error. *Why IoAwaitable, not plain awaitables* A plain awaitable can resume a coroutine on any thread by calling coroutine_handle::resume() directly. That breaks the invariant. The compile error when you co_await a plain awaitable from a Capy coroutine is the type system preventing this. This isn't about locking you in. It's about making environment propagation explicit. An IoAwaitable receives the io_env (executor + stop token + allocator) and promises to dispatch the resumption through the executor. That promise is what enables the safety guarantee. *The interop problem* Without a shared protocol, N coroutine libraries need N*(N-1) adapters. With a standard protocol for environment propagation, one bridge covers everyone. IoAwaitable is our proposal for that protocol. Capy is the testbed. The papers (P4172, P4092, P4093) are the standardization path. *What Capy is not* Capy is not a general-purpose "do everything" coroutine framework competing with TooManyCooks feature-for-feature. It is not an implementation detail of Corosio. It is the execution model and byte-stream layer - usable standalone for business logic that operates on streams without platform I/O (HTTP parsing, protocol state machines, serialization), and usable as the foundation for Corosio's networking layer. CERN's traccc project uses Capy without Corosio for GPU reconstruction pipelines. The Boost.HTTP parser is implemented entirely on Capy's byte streams. These are the intended use cases for Capy alone. *What went wrong in this review* The documentation never stated any of the above. It explained the API without explaining the design's purpose. Rainer encountered a type-safety check, found no documentation for the escape hatch, and concluded the escape hatch didn't exist. The frustration was understandable. The documentation failed him. We are fixing this. Bikeshed ideas: Cowaitable, Exwaitable Thanks

5 15

What an error message must do
by Udo Steinbach 29 Jun '26

29 Jun '26

I’d like to raise a practical issue with the current direction of error-handling support. In my experience, existing models still leave too much uncertainty for both human and programmatic consumers of error information. I’m interested in whether a more general boost::exception-style mechanism could preserve richer diagnostic context without forcing users into narrow error codes or lossy secondary return values. A general-purpose error-handling facility should preserve as much diagnostic information as possible, keep that information available for both human and programmatic consumers, and remain highly reliable itself. An error message must enable the user of the program to identify the cause and investigate or fix it without further assistance, without experiments, without guesswork, and without help from third parties. It must also be usable programmatically. To do that, it must identify four points: * The action triggered by the user or by an automated process in whose context the error occurred, including the consequences of incomplete execution, for example: “Not all mails could be retrieved; the missing ones are still on the server.” This is not the task of error handling itself, but of the top level, the user of the error-handling facility. * The cause, that is, the detected state, for example a full disk. * The object, such as a file path, device name, or similar, on which * the named operation failed: reading, writing, opening a window. Unless there are compelling reasons to the contrary, these points must have top priority; neglecting them is inexcusable. It is not enough to simply produce text at the end; rather, the text must be part of the diagnosis that begins with the message. Ideally, it implicitly suggests a necessary or at least obvious course of action. For logging purposes, it must also allow later diagnosis. That is the task of the caller or an external instance, but the error must include the point of state recognition and the triggering operation. Taken together, these requirements mean that many participating levels and instances must collect information, and each must also have the opportunity to make use of it and act accordingly. At the same time, no error-handling mechanism itself may become a source of errors; it must handle any runtime errors occurring within itself definitively. Errors that occur during error handling do not only lead to technical difficulties, but “errors during errors” can also conceal or distort the original error, or lead to unmanageable or otherwise unrecoverable follow-up errors. In my view, there is no alternative to making error handling itself free of errors. Existing solutions often do not take this requirement into account. The widely unsatisfactory state of error messages shows that more is needed than yet another proposal. A good solution in boost could show what error messages should look like in the first place. Udo -- Mit Radwegen lernte ich den Menschen kennen. http://radwege.udoline.de/ GPG: A245 F153 0636 6E34 E2F3 E1EB 817A B14D 3E7E 482E

4 6

[Capy/Corosio review] Benchmark results
by Marcelo Zimbres Silva 29 Jun '26

29 Jun '26

Hi, some months ago I started implementing new benchmarks for Boost.Redis to compare it to the current state of other popular clients. While underway with it Boost.Redis gained Corosio support, something that has been announced by Ruben Perez in this mailing list recently. In this email I would like tol share the results I obtained for appreciation by the Capy/Corosio review audience. The code is public and available at https://github.com/mzimbres/redis-cli-comp. The new benchmarks simulate a scenario where Redis is mostly used, namely, internet facing servers (usually HTTP) that serve connections concurrently while receiving server pushes e.g. pubsub events. It consists of 1. starting multiple independent sessions that issue commands in a loop. 2. subscribing to a channel to receive pubsub events. ## Runtime Performance The metric used to assess the runtime performance was the wall-clock multiplied by %CPU consumption used by the client. This metric takes into account that clients might use a different number of threads. The following result were obtained (lower is better) Client Time x %CPU (nomalized) ------------------------------------------------------------------- boost_redis_corosio 1.00 boost_redis_asio_cb 1.35 boost_redis_asio_co 1.73 redis_rs (Rust) 4.62 go_redis (Go) 22.33 The thread and file-descriptor usage by each client was Client threads fd-nr -------------------------------------------------- boost-redis-corosio 3 7 boost-redis-asio-co 2 7 boost-redis-asio-cb 2 7 redis-rs 1 10 go-redis 24 1006 ## Application build time This is the time taken to build the benchmark program excluding the time taken to build the client library Library Time (s) --------------------------------------- boost-redis-corosio 1.68 boost-redis-asio-co 3.60 boost-redis-asio-cb 8.62 redis-rs 3.10 go-redis 0.28 ## Client build time Here we see the time taken to build only the client Library Time (s) ------------------------------------------- boost-redis-lib-corosio 5.3 boost-redis-lib-asio 21.7 redis-rs 9.6 Note: I haven't found a way to measure this for go clients. ## Total build time The times below include the build time of all dependencies (which have been previously downloaded) Client Time (s) --------------------------------------- boost-redis-corosio 33.6 boost-redis-asio-co 35.5 boost-redis-asio-cb 40.5 redis-rs 42.6 go-redis 9.0 ## Executable size That is the size of release builds of each benchmark program. Executable Size -------------------------------------- boost_redis_corosio 1.5M boost_redis_asio_cb 1.9M boost_redis_asio_co 1.3M redis_rs 2.0M go_redis 8.2M ## Summary It is not the point of this report to analyse the results in detail or emit any verdict, Corosio however has come out with really impressive results IMO. Marcelo

2 1

B2 5.5.0 release
by René Ferdinand Rivera Morell 28 Jun '26

28 Jun '26

FYI, the latest (5.5.0) release of B2 is now in the develop branch. It will get to the master branch in the next couple of days if nothing blows up. For what's in the release see: < https://github.com/bfgroup/b2/releases/tag/5.5.0> -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net

1 0

[capy review] Klemens' Laundry list
by Klemens Morgenstern 28 Jun '26

28 Jun '26

Disclaimer: I have been involved in the development in affiliation with the C++Alliance. I wish to first of all express that I really admire the effort of creating a coroutine-first alternative to boost.asio that can optimize run- and compile-time by having only one asynchronous completion mechanism. However, I fear that capy & corosio are not ready. Below is a list of criticisms & issues that might end up as part of my review. However, I think it is better to allow the authors to address these first. I have discussed some of these with Vinnie on Slack already, but I think it is better to get this on the record for the review. So I hope he doesn't mind reiterating some of the discussion we had. # 1. Comparison to asio Asio is incredibly feature-rich and I would not expect capy/corosio to match all the features. However, I would hope it to would more features or different approaches, that take the coroutines into account. However, they are mainly compile and run-time improvements and very little in functionality. Since `capy::task` is functional equivalent to `asio::awaitable` the only thing I can identify are the type erased streams (e.g. any_read_stream) and the ability to use different SSL implementations like wolfSSL. The type-erase stream types however are then not even used, the corosio::read_until function is templated. Their ownership semantic (construction by pointer is non-owning, construction by pointer is owning) is very unintuitive. Construction by lvalue ref is non-owning, by rvalue ref is owning would make more sense to me. As a side-note: Botan actually offers a SSL stream for asio, so technically other SSL implementations for asio exist. Other than that there seems to be a lot of "asio did it" design decisions. ## 2. capy::continuation The continuation type is useful because the executor doesn't need to allocate a list on it's own, it uses an intrusive list of which `continuation` is a node. However, the `next` member is public and default constructed as null. If this was an implementation detail, why isn't it private? Or at least name `next_` or `_next` ? It could be public and allow me to submit multiple continuations at once, but as it is, it is an odd api. At the very least I would expect a non-explicity constructor from a `coroutine_handle`. It is an implementation detail leaking out for no apparent reason. ## 3. capy::async_mutex The mutex is a thing that's not thread-safe. This naming is just bad. And no, it's not enough that it's documented, as this is very counter-intuitive. ## 4. capy::DynamicBuffer / capy::read_until The dynamic_buffer concept comes from asio and I don't think it is needed in a coroutine library. It's one of the "asio did it" features. The reason asio has those is because of `async_read_until`. In asio, writing an asynchronous algorithm is extremely painful, so using `async_read_until` is a massive help. However, once we have coroutine, this becomes a `for` loop. std::string buffer; auto [ec, n] = co_await read_until(s, capy::dynamic_buffer(buffer), "\n", 2048); Can be written as : std::string buffer; while (buffer.find('\n') == std::string::npos) { const auto prefix = buffer.size(); buffer.resize(prefix + 2048); auto buf = capy::make_buffer(buffer); buf += prefix; auto [ec, n] = co_await s.read_some(buf); buffer.resize(prefix + n); if (ec) co_return ec; } From my experience using asio for years, I can also say that I almost never used read_until. It usually ended up being replaced because the matching function wasn't ideal for many protocols. Mainly because the matching condition (as it does in capy' read_until) always rescans the whole buffer. Even in the example above it would be more efficient to pass `prefix` after find to not scan through the whole string again. I would also like to add that beast is providing it's own buffer types to use with it's http functions. Dynamic Buffers may be a good idea for certain protocols, but it is not at all evident to me that they make a good generic concept. Rather I think that a dynamic buffer should be optimized for it's protocol. But, because we have `read_until` we now replace 10 lines of code with multiple types and concepts that I consider unnecessary. It seems yet another design decision based on "asio did it" that doesn't seem to have reevaluated the changed conditions. ## 5. capy's non dynamic buffers First of all, I agree with asio's decision to use a pair of `void*` and `size_t`, because memory is untyped. So those two are correct. However, it seems capy is copying `asios` buffer sequence without reconsidering the following new circumstances: If I have a function accepting a `span<const_buffer>` and I have a generic buffer sequence I could do this: some_buffer_sequence bs; co_await write(s, as_span(bs)); Where span returns a type that can be converted to the span. Because the `co_await` expression is - as one might guess - an expression, the lifetime of the container referenced by the span will be destroyed after the coroutine is returned. Thereby we could avoid templating the write function over the buffer sequence and reduce compile time and complexity. An IO object could also communicate through it's API if actually supports vectorized IO or not. The buffer types could also just wrap around the OS buffer types (e.g. iovec) and thus avoid any copying. If a stream does not get templated on the buffer_sequence, but just takes a span, implementation of other stream types gets much simpler, too. This is important if capy wants to establish it's stream concepts as the de-factor or actual standard. To be clear: I am not saying that a `span` is the right solution, but there are simpler solutions that can have a concrete type. Asio's buffer sequences need to work with asynchronous completion that do not get `co_await`ed and thus has to solve lifetime problems, that capy hasn't. The design of capy does not seem to consider this subtle difference. ## 6. capy::any_executor I don't understand why there's an `executor_ref` and an `any_executor`. If the `any_stream` support non-owning mode, why couldn't the `any_executor` follow the same model and we don't have an `executor_ref` ? I know that `executor_ref` is uses in the tasks and must be cheaply copyable, but why couldn't that use a single any_executor at the structure allocated by `async_run` and then a `any_executor&` in the task. At the very least, there's an inconsistency between `any_executor` and the `any_stream` types. ## 7. capy::execution_context Next, the `capy::execution_context` is odd. It is only used by `corosio`, however it is part of any `executor`. However, it turns out that the `execution_context` can be default constructed but is completely useless unless constructed as the parent class of corosio::io_context? Why is that? In asio, I can default construct an `execution_context` and it'll spawn off a thread for the reactor and it'll work great. Likewise the `asio::thread_pool` will work, where as capy::thread_pool will not allow me to create a corosio::tcp_socket. If the `execution_context` must not be used this way, the constructor should be `protected`. I would very much prefer it behaved like `asio`, because that is required to make the asio bridge I wrote work. ## 8. capy::IoAwaitable The IO awaitable protocol is an interesting idea of how to solve the executor propagation problem. However, it has one issue: not every waitable is asynchronous. That means that not every awaitable will need to dispatch back through the executor. I think restricting `co_await` to just `io_awaitables` is too restrictive and puts `capy::task` as `asio::awaitable`. I don't think that proposing io_awaitable for the standard is an argument either, since at this point regular `awaitable`s are the standard protocol. I don't know how capy should fix it, but this is a missing feature, if `capy` wants to a generic coroutine library. `asio::awaitable` achieves a similar thing, by only allowing `asio::awaitables` to await each other. That is fine, but it turns a `capy::task` into something more specific, a coroutine type aimed towards use with corosio. ## 9. capy::async_run The `async_run` double invocation just looks weird. I get the intention of setting the thread_local memory resource for when the task is created. I do however think that this is a consequence of `asio did it` design. This could be much more intuitive, if the `corosio::io_context` API changed to this: // we use a main task that can use wait_all & wait_any to manage other work capy::task<double> main_task(); { corosio::io_context ctx; double res = ctx.run(main_task()); } We would achieve two things: we got rid of the callback, which is generally a good idea in a coroutine library, and we could bind the memory_resource to the io_context. This would give us a simpler and much more intuitive API and an implicit work guard with the `main_task`. But alas, capy/corosio just copies `asio`'s API for `io_context` and requires a call to `run`; ## 10. capy::io_result `io_result` is not great, because std::get<> is not an extension point. That means I can't use `std::tie`. The code examples use structured binding for the `error_code`, but that means I will need to redeclare `ec` for every operations. const auto [ec, nr] = co_await read_some(...); const auto [ec2, nw] = co_await write_some(...); This needs to be solved.

3 2

[Capy review] On peer dependencies
by Ruben Perez 28 Jun '26

28 Jun '26

I'd like to bring up the issue of peer dependencies in Boost, taking Capy's review as an occasion. Running boostdep --brief capy yields: # Primary dependencies asio # Secondary dependencies align assert # and half of Boost, omitted for brevity This is not a hard dependency - Asio is included in an optional header (capy/buffers/asio.hpp) to facilitate integration. I think this is the right choice, but we lack a way to represent this. Every Boost library depending on Capy and using boostdep will now install Asio and half of Boost (when they likely don't need it). I don't know if this has implications for package managers or not (the b2 people probably know the answer). What's everyone's opinion on this? Should we try to do something to represent the concept of "peer dependency"? (maybe a field in meta.json?) Best, Ruben.

6 13

[release] 1.92.0 Deadline for major changes is next Wednesday!
by Marshall Clow 27 Jun '26

27 Jun '26

We’re starting the 1.92.0 release cycle. Upcoming milestones: 1-Jul - Boost 1.92.0 closed for major changes 8-Jul - Boost 1.92.0 closed for beta As always, you can find the calendar here: https://www.boost.org/calendar/ — The release managers

2 1

Boost Review for Capy and Corosio - June 23 to July 7th
by Jeff Garland 27 Jun '26

27 Jun '26

Dear Boost Community: The Boost Formal Review of the *Corosio* and *Capy* libraries will begin on *June 23, 2026* and will conclude on *July 7, 2026*. I'm Jeff Garland and I'll be the review manager. I'd like to thank Vinnie for inviting me to maintain the continuity from Boost.Asio and I'll apologize now for the late notice. Since this is a two library review the period is somewhat extended from normal. In fact my personal pre-review indicates we will likely need an extension due to the size of the libraries -- I'll work with the review wizards on that. Capy Capy is a coroutine foundation library providing task types, execution contexts, executors, asynchronous synchronization primitives, buffer abstractions, and coroutine composition facilities. It serves as the execution and asynchronous programming substrate upon which Corosio is built. Repository: - Capy GitHub Repository <https://github.com/cppalliance/capy?utm_source=chatgpt.com> - docs <https://develop.capy.cpp.al/capy/index.html> Corosio Corosio is a coroutine-native asynchronous I/O library for C++20. It provides networking and I/O facilities designed specifically for coroutines, with awaitable operations, executor affinity, cancellation support, and cross-platform implementations based on IOCP, epoll, and kqueue. Repository: - Corosio GitHub Repository <https://github.com/cppalliance/corosio?utm_source=chatgpt.com> - docs <https://develop.corosio.cpp.al/corosio/index.html> Review Questions Potential reviewers are encouraged to consider the following questions: 1. What is your evaluation of the usefulness of the libraries? 2. What is your evaluation of the design? 3. What is your evaluation of the implementation? 4. What is your evaluation of the documentation? 5. Have you used either or both libraries? What was your experience? 6. Are the libraries ready for inclusion in Boost? 7. If not, what changes would you recommend before acceptance? 8. Do the libraries fit well within the existing Boost ecosystem? 9. Are there API, naming, usability, extensibility, or implementation concerns that should be addressed? How to Participate Please post your review to the Boost Developers mailing list. Reviews from both experienced Boost contributors and first-time reviewers are encouraged. Reports based on real-world usage, experimentation, code inspection, and documentation review are all valuable contributions. At the conclusion of the review period, the review manager will consider all feedback and determine whether the libraries should be accepted into Boost. We look forward to your participation in this review.

10 50

[Capy Review] Why no default rescheduling?
by Marcelo Zimbres Silva 26 Jun '26

26 Jun '26

Hi, there seems to be a fundamental difference between how Asio and Capy protect its users against async operations that are always ready. Asio uses default rescheduling and will not call the continuation inline even if the completion is synchronous. This is valuable for the safety of internet facing code e.g. a malicious client can't starve other tasks by sending data continuously. Capy on the other hand uses symmetric transfer to deal with synchronous completions, allowing the task to monopolize the event loop as long as data is available. IMO it is not safe enough to delegate yielding into the event loop to users as forgetting to do so creates vulnerability. It is safer to provide a way out of default rescheduling than requiring every user to do it manually. The problem is not a theoretical one and widely used runtimes such as Tokio had to correct course to avoid it [1] > If data is received faster than it can be processed, it is possible that more data will have already been received by the time the processing of a data chunk completes. In this case, .await will never yield control back to the scheduler, other tasks will not be scheduled, resulting in starvation and large latency variance. > Currently, the answer to this problem is that the user of Tokio is responsible for adding yield points in both the application and libraries. In practice, very few actually do this and end up being vulnerable to this sort of problem. I would like to know why Corosio/Capy authors decided to take this direction? Marcelo [1] https://tokio.rs/blog/2020-04-preemption

2 1

Capy & Corosio Review
by Jonny Weir 26 Jun '26

26 Jun '26

This is my formal review of the capy and corosio libraries. This review of capy and corosio is based on 4 months of active development on a large-scale production codebase which consists of a total of 56 repositories in a standard platform release, of which 39 form part of the C++ framework, all of which use asio for their underlying asynchronous implementation. Of those, 7 repositories contain more concentrated use as part of the message passing architecture by providing core pipeline and transport layer utilities. The codebase in question is for a tier-1 financial market system that has been in production for many years. The codebase builds using gcc15, supporting C++23/26. It is worth noting that this review has been written with the view that capy/corosio is used to underpin the backend asynchronous operations and networking. No attempt was made to have asio/corosio interoperability. I have framed my review around the original questions proposed by Jeff Garland. 1. What is your evaluation of the usefulness of the libraries? In a high performance, ultra low latency environment, being able to move data around efficiently is of the utmost importance. The capy library is extremely useful for this. It has a very specific set of functionality: coroutine tasks, buffers, streams, and executors. This makes it easy to reason about where it fits into an existing codebase, or how it is to be used for a new project. Equally, the same can be said about corosio, fast and efficient networking is core to the functioning of financial systems. Having a modern approach to network programming is extremely useful. 2. What is your evaluation of the design? Having actively used this library for the last 4 months, I can say with confidence that capy is a well designed library. By separating out buffers, streams, and executors, capy gives the user orthogonal abstractions. That is to say, memory layout, asynchronous byte transfer, and coroutine scheduling can be mixed and matched, optimized independently, tested in isolation, and reused without pulling in platform specific networking or each other's implementation details. A key design decision is that it is coroutine-only. This has not been retrofitted and therefore commits to one single asynchronous style. The usual benefits of coroutines apply: flow control reads as sequential code. The use of capy primitives (eg: run_async/when_all/etc...) are used instead of ad-hoc callback chains. Corosio provides a layered design (similar to capy) that consists of three layers: (viewed as native vs. type-erased) - abstract - eg: io_stream, type-erased and generic that works with TCP/UDP/Unix domain socket/etc... - concrete - the full protocol API (connect, bind, endpoints, socket options) for each type. - native - implementation specific inlined awaitables with no vtable. The corosio design focuses on IO primitives, sockets, resolvers, timers, etc... and does not try to be an execution framework. This results in a cleaner codebase with clear ownership of problems, all of which can be paired very naturally to specific networking problems, like HTTP, or Websockets. By using the capy::io_result<T>, there is a consistent way to handle errors and results. It is the same for sockets, resolvers, timers, etc… 3. What is your evaluation of the implementation? The capy and corosio implementations use modern C++20 techniques: - concepts - coroutines - structured bindings - std::stop_token - PMR-style allocators I have spent some time inside the capy source (mostly when it came to raising bugs/issues/questions) and I found that there is a clear layered design without platform coupling. The layered design provides clear separation points within the code: executor / run_async -> where and when coroutines resume | v streams / sources/sinks -> the async byte transfer semantics | v buffers / buffer sequences -> memory regions those operations use Users are able to choose the layer as per their need, for example: - Protocol parsing - BufferSink / BufferSource concepts (zero-copy). - Connection logic - concrete stream types (or the type-erased any_stream&). The higher-level behaviour is typically expressed as template free functions that are constrained by concepts. Capy keeps concepts (compile-time contracts) and wrappers (runtime polymorphism) as separate layers, so you choose where the cost lands (native vs. type-erased) . This approach to implementation gives the user full control over how they integrate capy into their projects. It is also worth mentioning that a lot of the capy and corosio specific compile errors that were seen were easy to follow and debug. It was rare to see pages of obscure compile-time errors with little or no information about what actually happened when the capy/corosio related code was incorrect. The corosio implementation has a very familiar look and feel, borrowing much of the styling from well established asio principles. Many of the APIs are very similar to asio. As a result, the biggest challenge was thinking about the coroutine integration, rather than having to re-think the applications network stack and how it behaves. The capy and corosio source code quality is very high. When it came to requesting features, an attempt was made to understand how things currently work before offering up a solution, or, to check whether it was feasible or not. The code was easy to read and understand. A number of bugs were fixed and features added during this large-scale refactoring project. I found error handling to be very consistent across the library. The structured binding approach is used everywhere and io_result never throws, which is extremely important for the code I work on. However, it is possible to throw std::system_error(ec) if that behaviour is desired. From a performance and benchmarking perspective, the implementation (epoll in this case) is performant. It is on a par with asio under production-style loads and it is definitely capable of low latency message handling (more on this later). Having the option to use fully inlined backend calls without introducing a second, parallel type hierarchy or a separate way of thinking about sockets and streams is a very attractive implementation detail. 4. What is your evaluation of the documentation? This was my first real foray into the world of coroutines and how they might be used in a production codebase. I am familiar with C++20 coroutines, but I had no real world experience with them. The capy documentation gives a very good primer and introduction into coroutines, concurrency, and all of the associated concepts. I found the documentation clear, and easy to follow. I have a lot of experience with asio and reading through the capy documentation allowed me to see the similarities between capy and asio (in terms of buffers) and map them directly onto pre-existing concepts that were lifted from asio, no discrepancies in terms of what I would expect the behaviour to be were noticed. For the new concepts introduced by capy, each section is well presented and clearly written. The code examples are concise and go to great lengths to illustrate most (all?) of the functionality. It was rare that I would not find what I was looking for when looking over the specific examples if I was unclear on how to do something. If details were missing, the authors made the required documentation updates. As an experienced user of asio, my view on the corosio documentation is that it is very well written and explains each of the concepts very clearly. Users who have asio familiarity will be very comfortable with this documentation. As for users who may not be familiar with network programming, or asio, they will get a gentle introduction with a number of tutorials that are well written and include code examples that are well commented. New users should be able to get up to speed quickly, given the quality of the documentation. 5. Have you used either or both libraries? What was your experience? As mentioned above, I have been using capy for 4 months now on a large-scale production codebase that is underpinned by asio. The goal of the project was to assess the viability of capy/corosio as an alternative to asio. The asio code in question used lambda-style callbacks and in some places, asio (stackless) coroutines, as well as various uses of timers, buffers, and asio specific helpers for various networking functionality. The first major piece of work was to integrate capy into the core message passing pipeline library that underpins the entire codebase. A traits based approach was taken which facilitated using asio_traits or capy_traits as the backend. This was configured as a compile-time option. The system could be built with asio or capy. A springboard approach was taken that wraps a callable with all of the required coroutine machinery and is then executed inline, or posted across a thread boundary. This integration was relatively unintrusive aside from the compile-time defines that needed to be specified in a small number of places. Even when capy moved from a std::coroutine_handle to a capy::continuation model, the traits based approach was easily modified to handle the continuation based approach. Part of the goal with this springboard approach was to avoid changing core infrastructure. Whilst the implementation may not have been as optimal as it could have been, the performance was still very comparable to the asio equivalent. This traits based approach resulted in a very minimal set of boilerplate code to determine which implementation was used at compile time. This boiled down to a number of defines being set in the main application code, meaning that as you moved lower into the library code, these defines were not required and the codebase “looked normal” with no “per-implementation” hacks to work around certain things. The capy stream concepts and buffers were almost a direct drop-in replacement for the asio buffers. Very little additional code was required and in most cases, it was making sure that the new capy types were compatible with the internal structures used within the production codebase. Using capy::run_async to launch the asynchronous behaviour at various locations in the codebase provided very clear entry points to indicate that asynchronous operations were about to occur. Support for stop_token was already part of our asio codebase which was a custom implementation of P0660 (our implementation pre-dated support in the standard library and the version of gcc that was being used at the time). As such, his custom implementation was replaced with std::stop_token. The majority of this change was replacing the custom namespace with std::. A number of issues were raised during this development period and were resolved very quickly, or alternatives presented (which ultimately made it into the documentation). As a result, the usage of capy within this codebase does not have any drawbacks or missing features. When it came to integrating corosio, the most challenging aspect was re-writing the lambda-style callback-based code with a coroutine based approach. The challenging part was around how to restructure the existing callback code so that lifetime issues were managed correctly. The difference in behaviour between callbacks and coroutines required some thought. One very important lesson when moving from a lambda-style callback chain to coroutines was that simply copying the callback lambda into capy::run_async and having it co_return a capy::task<> was a massive problem, due to IIFE/lifetime/UB traps. This is now very well documented in the capy documentation and I would go as far as to say lambdas (except for very simple usage) should be avoided. Class methods or free functions should be preferred. These denote clearer lifetime semantics and explicit coroutine entry points. When it came to implementing corosio client and server components, the flow control and APIs were all very familiar. The APIs are very similar to asio, so it was possible to make fast progress. The modular design approach taken in the production codebase made it possible to do a side-by-side porting of each asio component to a corosio implementation. At a high level, the following application components were ported over to use corosio: - TCP based clients and servers - UDP based transmitter and receiver. - Application specific timer synchronisation classes. - The core "application" that was used to start the io_context objects had both an asio and corosio implementation. It was of utmost importance that all of the existing tests worked with an asio io_context as well as the corosio io_context (both native and type-erased). Each of the corosio-equivalent classes has identical interfaces so that each of the tests could be called in the same way. A lot of work went into updating the existing tests so that any io_context could be passed and the tests run. Depending on the type of io_context, asio::dispatch or capy::run_async would be used. Care was taken to avoid making behavioural changes to the tests, to ensure that what previously passed would still pass with the corosio version of the test runner. This approach was also taken for all of the core benchmark scenarios, so that a fair comparison could be made between the asio components and corosio components. As a result of extensive test coverage, a number of bugs relating to the corosio io_context were filed and fixed. A number of API changes were required upstream, these were mostly gaps in functionality between corosio and some asio features that were required by the system. For example, supporting the <=> operator for endpoint objects. These changes were added upstream. As a result, all of our use cases and requirements were satisfied. The ports for each component were 100% capy/corosio compatible and did not require any asio interoperability. My overall experience in refactoring this codebase was very positive. I was surprised at how quickly progress was made on porting entire components. I was also very impressed by the speed at which issues were resolved. This is why I do not have any specific gripes about missing features or functionality. This work has been carried out in parallel with the development of capy and corosio. 6. Are the libraries ready for inclusion in Boost? Given the time spent with capy and corosio, I would say that yes, the libraries are ready for inclusion in Boost. The APIs are sufficiently mature and each have an adequate amount of features to be very useful. They provide a familiar approach to what users may already be used to, and expecting, when it comes to asynchronous network programming. Given the well defined design principles, further development and maintenance of these libraries will be possible. 7. If not, what changes would you recommend before acceptance? See point 6. 8. Do the libraries fit well within the existing Boost ecosystem? Yes, having a set of modern coroutine-only C++20 libraries that provides access to executors, buffers, and streams, as well as networking would be a welcome addition. Both capy and corosio would fit well within the existing Boost ecosystem. 9. Are there API, naming, usability, extensibility, or implementation concerns that should be addressed? I do not have any concerns. Mainly because any issues that I had raised as part of this large-scale refactoring were addressed in one form or another. In most cases, when an API change was made (that was not at the request of this reviewer), it generally caused very little disruption and the change in the production codebase was minimal. This suggests that the designs are mature and well thought out. Any user who is already familiar with asio should see familiar concepts, along with the typical extension points to allow further customisation, if required. Summary: I vote for these libraries to be accepted into Boost.

2 1