Capy types need renaming

[sgerbino]

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

• IoAwaitable — concept, include/boost/capy/concept/io_awaitable.hpp:127
• IoAwaitableRange — concept, include/boost/capy/concept/io_awaitable.hpp:155
• IoRunnable — concept, include/boost/capy/concept/io_runnable.hpp:91
• io_result — alias template for std::tuple<std::error_code, Ts...>, include/boost/capy/io_result.hpp:52
• io_task — alias template for task<io_result<Ts...>>, include/boost/capy/io_task.hpp:33
• io_env — struct, include/boost/capy/ex/io_env.hpp:44
• io_awaitable_promise_base — class, include/boost/capy/ex/io_awaitable_promise_base.hpp:86

Detail types (all in include/boost/capy/detail/io_result_combinators.hpp)

• io_result_payload — struct template, line 47 (specializations at 50 and 56)
• io_result_payload_t — alias template, line 62
• io_result_from_payload — struct template, line 85 (specializations at 88 and 97)

Outside the library (bench/example/test only)

• io_env — struct, bench/beman/sender_io_env.hpp:211
• io_sender_env — struct, example/awaitable-sender/awaitable_sender_detail.hpp:62
• io_context — class in a doc-reference test, test/doc/reference/execution_context.record.cpp:48
• Test fixtures: io_param_test, io_awaitable_promise_base_test, io_result_test, io_awaitable_test
• Doc-snippet helpers: io_step (4h_lambda_captures.cpp:36, 4g_allocators.cpp:197), io_awaitable_form (9o_why_not_tmc.cpp:57), io_awaiter_signature (4d_io_awaitable.cpp:62), io_awaitable_sketch (9k_executor.cpp:134)

---

IoAwaitable suggestions made:

• EnvAwaitable (Vinnie)
• ExecAwaitable (Steve)
• EnvAwareAwaitable (Andrezj)

I propose the simplification of the following type names:
capy::io_result<> -> capy::result
capy::io_env -> capy::env

For capy::io_task<...> we could just drop the alias. It would be capy::task< result<...> >

The same pattern can be applied to io_sender_env. (io_context not included, it is correct and Corosio's).

Obviously io_awaitable_base will follow whatever we can decide on for the IoAwaitable concept.

Comment your thoughts and opinions!

[akrzemi1]

I do not know why, but while I do not mind reusing popular names like task in namespace capy, I feel uncomfortable with capy::result and it having a quite opposite meaning to boost::result.

[gubnik]

ExecAwaitable feels like the most explicit name to highlight the idea of inherent executor affinity built into the protocol. EnvAwaitable and EnvAwareAwaitable are also a bit confusing in light of std::execution::task<T, Environment> as per P3552. If (or rather when) std:execution model becomes common it would be confusing to have EnvAwareAwaitable that isn't related to std::execution environment. capy::env is 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 with boost::result and all the other result people write. I would prefer something more explicit, for example capy::partial. I am not proposing this specifically but it indicates what the user is dealing with better than just capy::result.

[akrzemi1]

capy::env is fine because it is not something an unprepared user would normally encounter

IoAwaitable or its rename is also something normal people will never encouter. They will only be exposed to task<> 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 type tuple<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 simple tuple no 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 a variant<error_code, T>. The famous push_to/pull_from operations that operate on two streams suddenly need statuses of two streams to be reported.

Long story short, @gubnik's capy::partial is quite good. Other candidates: stream_result<...>.

[gubnik]

IoAwaitable or its rename is also something normal people will never encouter

You are right, yes. I was thinking about a potential API outside of Capy which could use an IoAwaitable but that's highly unlikely now that I try to actually think of one.

[klemens-morgenstern]

• capy::env is good.
• capy::io_result - I don't know why we need io_result at all, just use a tuple. I want to tie my ecs.
• capy::task - yes, in theory we could do the same for io_awaitable.

Ok, let's bikeshed io_awaitable: maybe some obscure name is better, something that screams at you?

awaitable is an alright name for a concept, in the same way that drivable would 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>.

IoAwaitable is bad because it sounds like something that can await io. It's like saying RoadDrivable but 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 the env awareness - e.g. groundedAwaitable. env_awaitable sounds like it's awaiting the environment.

[akrzemi1]

[...] Or we find a way to express the env awareness - e.g. groundedAwaitable. env_awaitable sounds like it's awaiting the environment.

Looks like EnvAwareAwaitable satisfies 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".

[anarthal]

I like capy::env. I don't like capy::partial at all - that'd mean Corosio's resolver returns capy::partial<resolver_results>. I'd consider dropping the alias. capy::result kind conflicts with system::result, but if the alias is to be kept, I'd be ok with it.

I'm ok with task defaulting to todays io_task if you rename the base template to basic_task.

EnvAwaitable looks like the most explicit to me.

[sgerbino]

• capy::io_result - I don't know why we need io_result at all, just use a tuple. I want to tie my ecs.

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?

[sgerbino]

Updating 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_base

[akrzemi1]

While at harmonizing names, I suggest that the naming around this_coro be reconsidered. Looks like today the only usage for this namespace is to access the data previously passed via io_env (which now may become await_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;