Re: [Capy/Corosio review]

On Monday, June 29th, 2026 at 3:47 PM, James Earnshaw via Boost <[email protected]> wrote:

> This is my formal review of the Capy and Corosio Libraries.
> 
> As context I have been working with the Capy and Corosio libraries for
> a period of four months as part of a coroutine migration effort. I
> have been involved in implementing various components of, and
> applications within a tier-1 financial market system (deployed on
> Linux) that has been in production for many years.
> 
> The platform currently uses Asio as an IO backbone, so using a library
> that mirrors the behaviour and performance of the Asio counterparts
> was important.
> 
> While this review is about the merits of Capy/Corosio, it is natural
> that much of it may reference Asio as a comparator given that it is
> our reference point for capability and performance given our existing
> codebase is entirely based on the Asio library (largely using
> callbacks).
> 
> Also note I come at this review from the position of a user picking up
> a new library as part of a refactoring and navigating that library
> based on the documentation and examples provided. I’m not trying to do
> anything too clever and have been able to fall-back on existing tests
> to assure behaviour (albeit updated to work with Capy/Corosio).
> 
> 
> *1. What is your evaluation of the usefulness of the libraries?*
> 
> My goal, by using these libraries, was to build simple coroutine
> scaffolding around pre-existing concepts within the codebase. This was
> made possible by a familiar API and strong documentation. The
> introductions provided a good high-level overview that allowed me,
> given my limited knowledge and experience with coroutines, to get up
> to speed quickly. These libraries will prove very useful for building
> effective coroutine-based applications.
> 
> I have used capy and corosio to write TCP/UDP servers and clients
> using each of the socket types, so the facilities provided by Corosio
> are exactly what I would expect from a networking library.
> 
> As an aside I should note that all my previous experience has been
> with Asio and callback code so while some may feel that style of code
> is hard to reason about I find it more intuitive, mainly because of my
> experiences to date.
> 
> This means, for example, that some coroutine specific patterns felt a
> little clunky or counter-intuitive at first. Not long after my first
> introduction to the libraries I attempted to rewrite some functions
> that execute a callback periodically when an asynchronous timer
> expires. This was when a new pattern was adopted: the periodic
> callback needs to be run in a loop, since the alternative, re-entering
> the same timer function indefinitely could result in a stack overflow.
> For me, initially, the callback style code felt easier to reason
> about.
> 
> I had a similar experience when refactoring server code that performs
> read and write tasks. While the new pattern of performing the
> asynchronous waits in a loop made the flow of the server easier to
> understand from a high-level perspective, doing this as part of a
> callback-chain felt more natural to me.
> 
> Why am I mentioning this as a general observation? Well because, as
> someone who might be more representative of a typical user coming from
> a callback-based Asio background they may face similar mental hurdles.
> However, and this is the point, despite this: the mental jump from
> callbacks to coroutines and then using a new library as well, I can
> say that the experience has been a good one. So none of this is a
> criticism, more just an observation that may lead to documentation
> improvements to better aid users like me.
> 
> No doubt there will be alternative patterns and approaches I should
> have taken but I haven’t looked into that in detail yet because I was
> able to get code working that delivered the same or better performance
> than the older implementation by using the documentation as a very
> accessible guide.
> 
> 
> *2. What is your evaluation of the design?*
> 
> The design of the library has been easy to use with limited background
> knowledge of C++20 coroutines. In terms of the facilities from Capy,
> having the capy-provided task type meant that coroutines could be
> composed and executed in parallel to make up small working projects
> with only few includes required.
> 
> Using run_async in more complicated code took some getting used to, in
> comparison to my experience of Asio’s callback approach using, for
> example, boost::asio::read_some( Socket, Callback ) where the
> execution of the async operation is also the code that runs after the
> operation is complete and no more than that.
> 
> Passing stop tokens through the coroutine stack automatically in the
> background makes cancellation a seamless task. Running child tasks
> within this stack is easy to orchestrate with the helpers e.g.
> capy::this_coro, for getting access to the environment where the stop
> token can be found.
> 
> So all-in-all, as advertised, this is more or less a familiar design
> to Asio but with a focus on being coroutine-first.
> 
> 
> *3. What is your evaluation of the implementation?*
> 
> My experience of the libraries is less of the implementation and more
> of the usage of the API, so I haven’t read a lot of the source code.
> 
> Anecdotally from a testing and behavioural point of view clearly the
> implementation is fit for purpose as all of our tests (refactored to
> allow both Asio and Capy/Corosio variants) passed and performed
> comparably or better, so no concerns here.
> 
> 
> *4. What is your evaluation of the documentation?*
> 
> The documentation is incredibly strong. The way they begin from first
> principles - networking, coroutine machinery and threading
> synchronisation etc., means that C++ developers can reference the
> documents for guidance on many related topics. A lot of canonical
> patterns are given. I found it was a simple task to adapt these to
> working code.
> 
> 
> *5. Have you used either or both libraries? What was your experience?*
> 
> Yes, as noted, I have used both libraries for a period of about 4
> months to-date. Prior to that I had no experience of working with
> coroutines in C++. As a result I very much appreciated that the
> documentation started from first principles of coroutines, allowing me
> to write my own awaiters and promises to get a handle on the
> machinery, before trying some of the same mock code with capy task and
> run_async.
> 
> Creating my own awaiter involved creating a sleeping thread that then
> posted the continuation on wake-up. To get this working I had to look
> at the capy::delay_awaitable to see what was done with the handle and
> io_env, so maybe the documentation could be improved for others
> wanting to create their own.
> 
> In trying to write more complex code I was tripped up by the lambda
> capture lifetime caused by temporary lambda tasks on multiple
> occasions. However the documentation has since been updated and
> explicitly warns users about this with sufficient detail to explain
> exactly what happens in this scenario, and proven alternatives.
> 
> In the time I have been using Capy/Corosio the documentation has
> continued to evolve as misunderstandings arise and can be addressed
> and this has supported (for me) a positive experience of using the
> libraries but more importantly the result of using the libraries has
> been working, production quality code.
> 
> 
> *6. Are the libraries ready for inclusion in Boost?*
> 
> Yes, the libraries are such that they provide all of the tools
> necessary to write coroutine code with networking facilities. For my
> use cases there is just one point to be made about the socket/endpoint
> interfaces which is mentioned below.
> 
> In short, for Asio, we write resolver.resolve(host_name, port) and
> then try each of the endpoints, each of which is potentially IPv4 or
> IPv6, until one of them works, keeping the application code
> independent of the particular IP version.
> 
> In some cases, it would be convenient if corosio supported a similar
> mechanism that would replace this style of application code:
> 
>     if( Endpoint.is_v4() )
>     {
>         Socket_.set_option
>           ( boost::corosio::socket_option
>               ::join_group_v4( Endpoint.v4_address() ) );
>     }
>     else
>     {
>         Socket_.set_option
>           ( boost::corosio::socket_option
>               ::join_group_v6( Endpoint.v6_address() ) );
>     }
> 
> with
> 
>     Socket_.set_option( boost::corosio::socket_option::join_group( Endpoint ) );
> 
> Having said that, this is not a blocker.
> 
> I haven’t looked into the test coverage on these libraries so cannot
> make any comments about this.
> 
> 
> *7. If not, what changes would you recommend before acceptance?*
> 
> Nothing that would be considered a blocker.
> 
> 
> *8. Do the libraries fit well within the existing Boost ecosystem?*
> 
> Yes, as a C++20 coroutine-first alternative to Asio. Capy in
> particular could serve as a basis for other IO library developers
> wishing to start from a foundation of coroutines if it was accepted
> alone (recognising that the review is to treat both libraries as a
> set).
> 
> 
> *9. Are there API, naming, usability, extensibility, or implementation
> concerns that should be addressed?*
> 
> I have no major concerns about the libraries. The authors have been
> quick to address and fix any issues encountered with use.
> 
> Our code would directly depend on native support for websockets. I
> have been told that this will be supported at a later date, but I
> cannot find any github issues or timelines backing this up.
> 
> 
> *Summary*
> 
> For the avoidance of doubt I vote to accept these libraries into Boost
> on the basis that for my use cases they have proved fit for purpose. I
> have no strong views on the APIs and proposed changes voiced in other
> reviews as I’ve been tracking an evolving API for a while now and have
> not encountered any blockers.
> _______________________________________________
> Boost mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
> Archived at: https://lists.boost.org/archives/list/[email protected]/message/YLT26KCU5JS3FIAUUORW3JVKACZNZRNY/
> 

Thank you kindly for the detailed review James.
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/7XV2AGMYW6I5Q2LEFAJKB72Q5ZF7VUR3/