# modifier generics / keyword generics lang team meeting

### [Initiative Repo](https://github.com/yoshuawuyts/keyword-generics-initiative) | [Initiative Book](https://yoshuawuyts.github.io/keyword-generics-initiative/) | [Inception Draft](https://hackmd.io/bdELQXLATfCZNyyhOEM-dw) | [Lang Team Notes](https://hackmd.io/GJL6G0A5QqCAJctBv-zXCA)

## Introduction

One of Rust's defining features is the ability to write functions which are _generic_ over their input types. That allows us to write a function once, leaving it up to the compiler to generate the right implementations for us.

When we introduce a new keyword for something which used to be a trait or type, we not only gain new functionality - we also lose the ability to be generic. This proposal seeks to fill in that loss of functionality that by introducing "modifier generics": the ability to be generic over keywords such as `const` and `async`.

To limit the scope of the proposal, only the `const` and `async` keywords are considered at the time - but the proposal is being designed with the explicit goal to eventually be used for other keywords too.

## Problem Statement

### const

Before `const fn` (2018), we had to write a regular function for runtime computations and associated const of generic type logic for compile-time computations. As an example, to add 1 to a constant that someone supplies to you, you had to write:

trait Val {
    const VAL: i32;
}
struct Foo<T: Val>;
impl<T: Val> Foo<T> {
    const FOO: i32 = <T as Val>::VAL + 1;
}
struct FourtyTwo;
impl Val for FourtyTwo {
    const VAL: i32 = 42;
}
Foo::<FourtyTwo>::FOO

Today this is as easy as writing a simple `const fn`

const fn foo(i: i32) -> i32 {
    i + 1
}
foo(42)

The interesting part here is that you can also just call this function in runtime code, thus sharing the implementation.

### async

People write duplicate code for async/non-async with the only difference being the `async` keyword. A good example of that code today is [`async-std`](https://docs.rs/async-std/latest/async_std/), which duplicates and translates a large part of the stdlib's API surface to be async [^async-std]. And because the Async WG has made it an explicit goal to [bring async Rust up to par with non-async Rust](https://rust-lang.github.io/wg-async/vision/how_it_feels.html), the issue of code duplication is particularly relevant for the Async WG as well. Nobody on the Async WG seems particularly keen on proposing we duplicate the API surface of the entire stdlib.

[^async-std]: (Note by Yosh): Some limitations in `async-std` apply: async Rust is missing async `Drop`, async traits, and async closures. So not all APIs could be duplicated. Also we explicitly didn't reimplement any of the collection APIs to be async-aware, which means users are subject to the "sandwich problem" (see appendix). The purpose of `async-std` has been to be a proving ground to test whether creating an async mirror of the stdlib would be possible: and we've proven (modulo missing language features) that it is.

We're in a similar situation with `async` today as `const` was prior to 2018. Duplicating entire interfaces and wrapping them in inefficient `block_on` calls is the approach taken by e.g. the `mongodb` [[async](https://docs.rs/mongodb/latest/mongodb/index.html), [!async](https://docs.rs/mongodb/latest/mongodb/sync/index.html)], `postgres` [[async](https://docs.rs/tokio-postgres/latest/tokio_postgres/index.html), [!async](https://docs.rs/postgres/latest/postgres/)], and `reqwest` [[async](https://docs.rs/reqwest/latest/reqwest/), [!async](https://docs.rs/reqwest/latest/reqwest/blocking/index.html)] crates:

// "crate_name"
async fn foo() -> Bar { ... }


// "blocking_crate_name" or "crate_name::blocking"
// take the `async fn foo` and block the thread until
// it finishes executing.
fn foo() -> Bar {
    futures::executor::block_on(crate_name::foo())
}

This requires effort on the user's side to find and use the right crates for their code. And it requires effort by the crate authors to keep the sync and async APIs in sync with each other.

Then there's an automated way of doing this using the [`maybe-async` crate](https://docs.rs/maybe-async/0.2.6/maybe_async/) which relies on proc macros.
Instead of writing two separate copies of `foo`, it generates a sync and async variant for you:

#[maybe_async]
async fn foo() -> Bar { ... }

This macro however is limited, and has clear issues with respect to diagnostics and ergonomics. That is because it is in effect implementing a way to be generic over the `async` keyword entirely using macros, which is the type of transformation a compiler / type system is better equipped to deal with.

### sandwich problems

A pervasive issue in existing Rust is the _sandwich_ problem. This requires traits, which we are intentionally considering out of scope for this meeting, but it _is_ relevant to the wider problem space so we want to at least mention it. The classic example is a `map` operation:

enum Option<T> {
    Some(T),
    None,
}

impl<T> Option<T> {
    fn map<J>(self, f: impl FnOnce(T) -> J) -> Option<J> { ... }
}

my_option.map(|x| x.await)

This will produce a compiler error: the closure `f` is not an async context, so `.await` cannot be used within it. In order to solve this issue, we could provide an `async_map` method which _does_ provide an async closure. But we may want to repeat those for more effects, and that would result in a combinatorial explosion of effects.

Just by introducing fallibility, we'd then have `map`, `try_map`, `async_map`, and `async_try_map`. That's a lot of API surface for just a single method, and that problem multiplies across the _entire_ API surface in the stdlib.

We expect that once we start applying "modifier generics" to traits, we will be able to solve the sandwich problem. The type `f` would be marked generic over a set of effects, and the compiler would choose the right variant during compilation. But as mentioned: we ar considering traits explicitly out of scope for this meeting, but we expect to to eventually extend the proposal to cover the sandwich problem as well.

### affecting all the effects

Both `const` and `async` share a very similar issue, and we expect that other "effects" will face the same issue. "fallibility" particularly on our mind here, but it isn't the only effect. In order for the language to feel consistent we need consistent solutions.

## Preliminaries

### subset / superset relationships

Before going into a concrete proposal, we need to establish some shared context. We've mentioned that `const fn` and `async fn` share similarities: but the way they differ from "base Rust" (Rust without any modifier keywords) is different.

`const` creates a _subset_ of "base Rust". For example `std::net` or `std::fs` will never be marked `const`, and so only a subset of all existing functions ever be able to be called from `const` contexts.

`async` works the other way around: it creates a _superset_ of "base Rust". All functions in "base Rust" can be called in `async` contexts (though we may not always want to), but functions marked `async` cannot be directly be execute (`await`ed) from "base Rust". In order to do this bridging functions such as `block_on` must be used.

**tldr**: "base Rust" is Rust without any `const` or `async` modifier keywords. `const` is a subset of "base Rust". `async` is a superset of "base Rust".

*For an overview of how we believe `const`, "base", and `async` Rust related to each other, see Appendix A.*

### Modifier keywords and execution context

The `const` and `async` modifier keywords differ somewhat in how they are applied in functions. `const fn` is a function which can be called both during compilation and runtime. While `async fn` can only be `.await`ed from other `async fn`s.

This means that when we talk about "conditional compilation", it's only the `async` keyword which doesn't have it. `const fn` _always_ always defines conditional execution. This has been incredibly beneficial for the consistency of the language, because it's allowed for a gradual _constification_ of the existing stdlib: and that in turn is great for keeping "const Rust" and "base Rust" consistent with one another (one is a strict subset of the other).

Defining an `async fn`, however, is not conditional. This means that in order to perform a similar _asyncification_ of the stdlib the way we did with `const`, we need to find a way to create "conditional async fns".

In the following table we map out the differences between `async` and `const` keywords. There is no way to define an "always `const`" function, but a similar effect can be achieved using `const FOO: () = {}` expressions:

| | keyword `async` | keyword `const` |
| --------------------------------- | -------------------- | --------------------- |
| **keyword never applies** | `fn foo() {}` | `fn foo() {}` |
| **keyword always applies** | `async fn foo() {}` | `const FOO: () = {};` |
| **keyword conditionally applies** | ❌ | `const fn foo() {}` |

## Proposal
### Proposal for "maybe"-`async`

We want to be able to write functions that can be async or not, depending on the call site. We also want to be able to make standard library functions "maybe-async" without that change being breaking.

In order to achieve that, we want to generalize the existing "maybe const" feature. This means, effectively `const fn foo() {}` is sugar for

for<effect A> const<A> fn foo() {}

Extending this limited effect system to async, will allow us to also write

for<effect A> async<A> fn foo() {}

Essentially this means that the keywords `async` and `const` can be made conditional/generic over an effect (which is essentially a boolean).

A maybe-const function can call other maybe-const functions, but not base Rust functions:

for<effect A> const<A> fn bar<T>() {}
for<effect A> const<A> fn foo() {
    bar::<effect A, i32>()
}

Effects must be specified explicitly in generic parameter lists with the contextual keyword `effect`. This makes sure that `bar::<i32>` keeps working as it does right now, while allowing us to experiment with passing effects explicitly.

In maybe-async functions, any call to a maybe-async function is treated *as if* it were returning a future and must thus be awaited.

for<effect A> async<A> fn bar<T>() {}
for<effect A> async<A> fn foo() {
    bar::<effect A, i32>().await
}

The difference to normal `async` functions is that you *must* await immediately when calling a maybe-async function from another maybe-async function. So for now we will consider the following illegal:

for<effect A> async<A> fn foo() {
    let x = bar::<effect A, i32>();
    x.await
}

Furthermore, any `await` inside a maybe-async function must be on a function call to another `maybe-async` function:

async fn boo() {}
struct MyFuture;
impl Future for MyFuture {
    ...
}
for<effect A> async<A> fn foo() {
    boo().await // compiler error: cannot call an `async fn` from a `maybe async fn`
    MyFuture.await // compiler error: not a maybe-async future
}

If the async effect is disabled (because `foo` is called in a regular function), then no await is needed:

fn main() {
    foo::<effect false>()
}

Because `async fn` functions are not possible to be called from `maybe async fn` functions, it means not all async code will be accessible from maybe-async code. This is an entirely expected outcome of the design. We consider "async Rust" to be a superset of "base Rust", and despite the need to write `.await`, maybe-async functions cannot call any functions which exhibit behavior exclusive to async Rust. This includes: ad-hoc concurrency (`join`, `race`, etc.) and ad-hoc cancellation of execution (`timeout`, etc.). See the "select/specialization" section for details on how this functionality may still be used in maybe-async code.

If the async effect is enabled (because `foo` is called from an `async` function), then await is required:

async fn cake() {
    foo::<effect true>().await;
    foo::<effect false>(); // also legal, but non-async
}

#### Syntax Sugar at call sites

Specifying the effects at all call sites is annoying, we want to infer it automatically. So we allow both ways to call `bar`, because a maybe-async function implies forwarding its maybeness:

for<effect A> async<A> fn bar<T>() {}
for<effect A> async<A> fn foo() {
    bar::<effect A, i32>().await;
    bar::<i32>().await;
}

A regular Rust function will imply not-async, so both `bar` calls are equivalent.

for<effect A> async<A> fn bar<T>() {}
fn foo() {
    bar::<effect false, i32>();
    bar::<i32>();
}

Similarly an `async` function will imply async, so both `bar` calls are again equivalent.

for<effect A> async<A> fn bar<T>() {}
async fn foo() {
    bar::<effect true, i32>().await;
    bar::<i32>().await;
}

Converting an existing sync function to a maybe-async variant has implications for backwards-compatibility. See the [backwards-compatibility][back-compat] section for more details.

[back-compat]: #Backwards-compatibility--Mode-selection

#### Syntax sugar for definitions of maybe-async functions

At this time we are not considering any sugar for defining maybe-async functions and will keep using the explicit `for<effect E>` syntax.

### Select/Specialization

Sometimes it is desirable to write a `const fn` that at runtime should do very performant things like SIMD, but at compile-time run a pure-Rust version of that code. The unstable [`const_eval_select`][select] helper allows specifying these two different versions and automatically picks the right one depending on whether it's being const evaluated or codegened.

`async` has similar problems where it is desirable to just write out the `async` and not-`async` logic explicitly instead of using a single (possibly suboptimal) version. For example: it may be more efficient for async code paths to execute operations concurrently instead of seqentially through methods such as `Future::join`. There are no counterparts for this in non-async Rust, so the code must necessarily be specialized to support this.

We are explicitly not suggesting any specific way to handle this situation, but whatever solution we come up with must be the same for `async` and `const`. For experimentation we will add the equivalent to `const_eval_select`: `async_select`. No stable code is allowed to depend on either of these beyond trivialities like debug assertions (already discussed in previous lang team and libs team meetings).

[select]: https://doc.rust-lang.org/std/intrinsics/fn.const_eval_select.html

### Proposal for "maybe"-traits, "maybe"-trait-bounds, and "maybe"-impls

With the "maybe"-`async` proposal we're bringing async and const to parity, but we want to go beyond that. The limiting factor is the ability to call trait methods on generic parameters of const or async functions.

For const: but we have the [experimental RFC](https://github.com/rust-lang/rfcs/pull/2632) for const trait impls. Which explicitly avoids this issue. In order to scope this lang team meeting, we're considering traits as a topic we should discuss in a future meeting.

### Backwards compatibility / Mode selection

_asyncifying_ the stdlib could lead to some issues. Take for example the following example, where we have a "maybe async" version of `Option::map`:

// Rust 2021
async fn foo() {                      // <-- note the `async` here.
    let my_option = Some(12u8);
    let _ = my_option.map(|x| x * 2); // this is the way it works today.
}

// Rust 2024?
async fn foo() {                      // <-- note the `async` here.
    let my_option = Some(12u8);
    let _ = my_option.map(|x| x * 2); // should this error: "must `.await`"?
}

- How do we decide which variant to use here?
- Inference from the calling context?
- Infer based on the passed closure
- Explicitly choose which option via turbofish
- Others?
- What leeway do edition bounds provide us here?

This is an important topic to figure out, because it allows us to asyncify existing code. But we must balance it with ensuring we don't introduce any backwards-incompatible behavior. This is something we're still researching, and we're aware it is crucial to resolve.

### User-defined modifier generics?

We do not plan to support this. "modifier generics"/"keyword generics" are only required because they have a relationship to existing keywords. Users are not able to define their own keywords, so it has not relationship to this feature.
Instead we refer to (planned) initiatives such as ["contexts/capabilities"](https://nikomatsakis.github.io/context-capabilities-initiative/evaluation/syntax.html) for ways to improve the UX of non-modifier generics.

### Concrete types and modifier generics

Concrete types such as `std::net::TcpStream` will want to be generic over asyncness. The constructor of the type will determine which "mode" the type remainder of the type is in, which means the `for` clause needs to be lifted to the type level. This is particularly relevant for the File type on Windows.

The exact semantics of this need to be determined still.

# Appendix

## Appendix A: Capabilities and restrictions of `const` and `async`

This is a simplified sketch of how we view `const`, "base", and `async` Rust relate to each other. Layers have a subset / superset relationship to each other, and each step up enables more capabilities.

This is a simplification: one could plausibly conceive of an `async const fn` which doesn't fit the mold. And it doesn't account for other effects or concepts such as "`no-std` Rust", which would have different subset / superset relationships.

Still though, we believe this is a useful framework for how to think about the `const` and `async` keywords in relation to this proposal, as it may not be immediately obvious how their respective capabilities relate to each other.

                      +---------------------------+                               
                      | +-----------------------+ |     Compute values:
                      | | +-------------------+ | |     - types
                      | | |                   | | |     - numbers
                      | | |    const Rust     |-------{ - functions               
                      | | |                   | | |     - control flow            
 Access to the host:  | | +-------------------+ | |     - traits (planned)                 
 - networking         | |                       | |     - containers (planned)
 - filesystem  }--------|      "base" Rust      | |                               
 - threads            | |                       | |                               
 - system time        | +-----------------------+ |     
                      |                           |     Control over execution:      
                      |         async Rust        |---{ - ad-hoc concurrency      
                      |                           |     - ad-hoc cancellation     
                      +---------------------------+     - ad-hoc pausing/resumption

## Trait stuff

*We're intentionally keeping traits out of the scope for the initial lang meeting. We only have one hour, and we could fill it entirely with traits. For now our primary focus is on the problem definition, and covering the base of the proposal. Any trait-related concepts we find time to include in this doc will be added to this section.*