Repository navigation
Capy types need renaming #395
Description
Activity
I do not know why, but while I do not mind reusing popular names like
taskin namespacecapy, I feel uncomfortable withcapy::resultand it having a quite opposite meaning toboost::result.ExecAwaitablefeels like the most explicit name to highlight the idea of inherent executor affinity built into the protocol.EnvAwaitableandEnvAwareAwaitableare also a bit confusing in light ofstd::execution::task<T, Environment>as per P3552. If (or rather when)std:executionmodel becomes common it would be confusing to haveEnvAwareAwaitablethat isn't related tostd::executionenvironment.capy::envis fine because it is not something an unprepared user would normally encounter unless they implement an awaiitable of their own, which forces them to get acquainted with Capy's protocol anyway.I agree with Andrzej on
capy::result. It says nothing about the nature of what the user is working with, and to add insult to injury it collides withboost::resultand all the otherresultpeople write. I would prefer something more explicit, for examplecapy::partial. I am not proposing this specifically but it indicates what the user is dealing with better than justcapy::result.Reacted by Steve Gerbinocapy::envis fine because it is not something an unprepared user would normally encounterIoAwaitableor its rename is also something normal people will never encouter. They will only be exposed totask<>or most of the time. Even though the docs and the papers keep using the name, user programes will not see it.Back to
result, let me share another observation. The typetuple<error_code, ...>is actually specific to an operation on a single stream. These stream operations will consume/fill a portion of the buffer, always return "what adventures happened to the stream" and often the size, which can be zero. And as long as you are operating on a single stream, you do not have to distinguish between "result from the stream" from "avoid exceptions". But the moment you do something more complicated, a simpletupleno longer serves the purpose of "avoid exceptions". For more complicated types that one would want to return, like we face now in Bost.HTTP, you now need avariant<error_code, T>. The famouspush_to/pull_fromoperations that operate on two streams suddenly need statuses of two streams to be reported.Long story short, @gubnik's
capy::partialis quite good. Other candidates:stream_result<...>.IoAwaitableor its rename is also something normal people will never encouterYou are right, yes. I was thinking about a potential API outside of Capy which could use an
IoAwaitablebut that's highly unlikely now that I try to actually think of one.capy::envis good.capy::io_result- I don't know why we needio_resultat all, just use atuple. I want totiemyecs.capy::task- yes, in theory we could do the same forio_awaitable.
Ok, let's bikeshed
io_awaitable: maybe some obscure name is better, something that screams at you?awaitableis an alright name for a concept, in the same way thatdrivablewould make sense as a concept for my car.
However, I don't think we need to strictly use nouns for concepts, this read just fine to me:template<can_drive Car>.IoAwaitableis bad because it sounds like something that canawaitio. It's like sayingRoadDrivablebut including dirtbikes.What it actually means is: an awaitable that accepts an environment; we could either just make that implicit and go for
capy::awaitable, because that is what is awaitable in the context/environment of capy. Or we find a way to express theenvawareness - e.g.groundedAwaitable.env_awaitablesounds like it's awaiting the environment.[...] Or we find a way to express the env awareness - e.g.
groundedAwaitable.env_awaitablesounds like it's awaiting the environment.Looks like
EnvAwareAwaitablesatisfies your criteria.I would also like to add another name to the bikeshedding exercise. The docs use in a lot of places the term
IoAwaitable-protocol. We do not need to use the concept name (whatever name we settle on) while describing the protocol. We could use "environment-propagation-protocol".I like
capy::env. I don't likecapy::partialat all - that'd mean Corosio's resolver returnscapy::partial<resolver_results>. I'd consider dropping the alias.capy::resultkind conflicts withsystem::result, but if the alias is to be kept, I'd be ok with it.I'm ok with
taskdefaulting to todaysio_taskif you rename the base template tobasic_task.EnvAwaitablelooks like the most explicit to me.capy::io_result- I don't know why we needio_resultat all, just use atuple. I want totiemyecs.
I will just bring to your attention that it is a tuple, it is just an alias now. Maybe your suggestion is just to remove the alias?
Reacted by Klemens MorgensternUpdating this issue to the latest discussions on slack.
IoAwaitable —> ContextAwaitable
IoAwaitableRange —> ContextAwaitableRange
IoRunnable —> ContextRunnable
io_result — Remove the alias std::tuple< std::error_code, ... >
io_task — Remove the alias task< std::tuple< std::error_code, ... > >
io_env — await_context
io_awaitable_promise_base — context_awaitable_promise_baseWhile at harmonizing names, I suggest that the naming around
this_corobe reconsidered. Looks like today the only usage for this namespace is to access the data previously passed viaio_env(which now may becomeawait_context). Do we envision getting other things va this mechanism (like getting direct access to the promise object)?Because these "tags" could be shorter and have names corresponding to those used when passing the context:
co_await get_await_context; co_await get_await_context::allocator; co_await get_await_context::executor; co_await get_await_context::stop_token;
- locked and limited conversation to collaborators
on Oct 1, 2026
Capy's viability goes beyond I/O. Many of our types are centered around I/O. Let's fix that.
Survey of the land:
Public types
Detail types (all in include/boost/capy/detail/io_result_combinators.hpp)
Outside the library (bench/example/test only)
IoAwaitable suggestions made:
I propose the simplification of the following type names:
capy::io_result<>->capy::resultcapy::io_env->capy::envFor
capy::io_task<...>we could just drop the alias. It would becapy::task< result<...> >The same pattern can be applied to
io_sender_env. (io_contextnot included, it is correct and Corosio's).Obviously
io_awaitable_basewill follow whatever we can decide on for theIoAwaitableconcept.Comment your thoughts and opinions!