El 03/02/2026 a las 4:52, Vinnie Falco via Boost escribió:
On Mon, Feb 2, 2026 at 3:52 PM Ion Gaztañaga <igaztanaga@gmail.com> wrote:
Documentation explains what Capy is about (and what the library does not do) but, unless I'm missing something, it does not emphasize why we should use Capy and not any other abstractions (are there are any competing libraries?).
This is a great point and it also highlights a difficulty in proposing such a library. On its own it is difficult to show the value proposition since it is a foundational library. It only solves a subset of user problems and needs things to be built with it to demonstrate utility.
Maybe in the examples section we could add a more concrete approach if possible, say an example using the framework and reading file asynchronously using POSIX or Windows asynchronous I/O. We can compare that with a more traditional coroutine approach. I guess that a user must write much less boilerplate code using Capy and we should show that.
There has been no effort to preserve any sort of compatibility with Boost.Asio, except for the buffer sequence concepts and that is admittedly such a small aspect that it seems hardly worth mentioning. Asio has its own execution model which is rather constrained.
Since Boost.Asio is very widely used library, I think users will ask how they can combine both, if possible. If combining Capy and Asio is not possible (I don't know, maybe incompatible APIs?), it should be mentioned in the documentation. I understand Capy can be combined with different I/O backends, so Capy users will inevitably ask which Capy-compatible I/O backends are available for them.
I would suggest that documentation should highlight why Capy
is the way to go.
Yes, I have put together this page to help answer that question:
Yeah, I think it show clear motivation. An additional doubt, note that I have little knowledge of coroutines, but here I go anyway: - When reading the IOAwaitableProtocol (https://master.capy.cpp.al/capy/coroutines/io-awaitable.html), it says that "the IoAwaitable protocol extends await_suspend to receive context". - But "await_suspend" is a method the coroutine machinery calls from an Awaiter, not an Awaitable. - How is the three-Argument "await_suspend" called? Who calls it? In which object? AFAIK the Awaiter comes from the co_await Awaitable expression but I'm confused by the terminology used in the page... Best, Ion