---
title: RPITIT Capture Rules
tags: design-meeting
url: https://hackmd.io/sFaSIMJOQcuwCdnUvCxtuQ
---

## Background

### Opaque types: Terminology and status

An `impl Trait` appearing in the following positions creates an opaque type that references a hidden type:

* Return position (RPIT) in:
* Free functions
* Inherent impls
* Traits and trait impls (RPITIT)
* Type aliases (TAIT)
* Associated types (ATPIT, aka ITIAT)

The **opaque type** is what is seen outside the defining scope. This code can only depend on what is mentioned in the **bounds** of the opaque type (for `impl Trait + 'a`, this is the `Trait + 'a` part), modulo leaked auto traits (which are out of scope for this doc). The **hidden type** is the actual concrete type, only known inside the defining scope.

Of the above list, only RPIT on free functions and inherent impls are currently stable. The focus of today's discussion will be on the behavior of RPITIT.

### What does it mean to "capture" a lifetime?

An opaque type "captures" a lifetime if its hidden type is allowed to name that lifetime. For example:

struct HiddenMessage(String);
impl HiddenMessage {
    fn as_debug<'a>(&'a self) -> impl Debug {
        self.0.clone()
    }
}

In this case the return type of `as_debug` is not allowed to name the lifetime `'a`. This could be changed by mentioning the lifetime anywhere in the `impl Trait`:

impl HiddenMessage {
    fn as_debug<'a>(&'a self) -> impl Debug + 'a {
        &self.0
    }
}

_Note that we are using explicit lifetimes for absolute clarity, but this would commonly be written with an elided lifetime as `impl Debug + '_`._

For the borrow checker to function with an opaque type it _must_ know what lifetimes it may capture, so it's important that this information can be deduced from the signature.

## Working with capture rules today

When we discuss whether we want capture rules that are more or less inclusive, it's important to consider the options users may have for overriding them in either direction.

### Working with the capture rules for lifetime parameters

As we've seen, a lifetime parameter is not captured by an opaque type unless it is mentioned in the opaque type's bounds. In the previous example we solved that problem by adding `+ 'a` to the bounds, and this is the canonical example that is usually given for what `async fn` desugars to.

But there is a bit of a "lie" in that solution, and this lie gives rise to a cliff of complexity when multiple lifetimes are composed together.

To see this, first think about what `impl Debug + 'a` means: We have a hidden type that implements `Debug` and outlives `'a`. But _outliving_ `'a` was never actually a promise we wanted to make to our API user! Instead, we wanted to say that our hidden type might reference `'a`; in other words, *that `'a` must outlive our hidden type*.

:::info
_It is the opinion of the author that this **inversion of meaning** gives rise to a whole host of confusion surrounding lifetimes, outlives rules, and opaque types._
:::

Nevertheless, adding `+ 'a` solved our problem. Not because of its meaning on the surface, but because of its effect on the capture rules. By mentioning `'a` in the bounds of our opaque type we gained the ability to reference it in our hidden type.

There is another, more "honest" way to accomplish this; it's called the `Captures` trick. We could instead have written our impl like this:

trait Captures<T> {}
impl<T, U> Captures<T> for U {}

impl HiddenMessage {
    fn as_debug<'a>(&'a self) -> impl Debug + Captures<&'a ()> {
        &self.0
    }
}

Because any type `U` trivially implements `Captures<T>` for any type `T`, a bound on `Captures` is effectively no bound at all. But it has the same effect on the capture rules, allowing us to name the lifetime in question.

:::info
The `Captures` trick is useful in other positions. For example, if you ever wanted to say that a lifetime outlived a generic type parameter, you probably could have used the `Captures` trick to allow the type parameter to name the lifetime. This is because we allow generics to name lifetimes that appear in their bounds. [Link to example](https://hackmd.io/zgairrYRSACgTeZHP1x0Zg?view#Refresher-on-the-Captures-trick)
:::

### Working with the capture rules for type parameters

So far we have talked about the idea of capturing lifetime parameters, but the idea of capturing applies to type parameters too. It is not talked about much because _opaque types always capture all type parameters in scope_. We discuss the history and reasoning of this difference in the section below.

A majority of the time, the fact that opaque types capture type parameters in scope is not really visible outside the function. But type parameters can themselves contain lifetimes.

For example, if we had a `chain` helper defined like this:

fn chain<T, U, I>(first: T, second: U) -> impl Iterator<Item = I>
where
    T: Iterator<Item = I>,
    U: Iterator<Item = I>,
{
    Chain::new(self, other)
}

We could call it and use it like so:

let a = [1, 2, 3];
let b = [4, 5, 6];

let chained = chain(a.iter(), b.iter());
// Borrows a        ^^^^^^^^
// Borrows b                  ^^^^^^^^

for x in chained {
    dbg!(x);
}

Moreover, it would be an error to drop `b` before the for loop, because `chained` captures a borrow of `b` via its type parameter `U`.

If this behavior is not desired, the solution (using nightly-only features, today) is to define the opaque type in a scope that _cannot_ name the type parameter. For example:

type Opaque = impl Debug;
fn captures_no_types<T, U>(x: T, y: U) -> Opaque {
    ...
}

This can come up because...

TODO

### Theme: Revisiting the lifetime capture rules

The decision to capture all type parameters, but not lifetime parameters, was originally made in [RFC 1951](https://github.com/rust-lang/rfcs/blob/master/text/1951-expand-impl-trait.md#scoping-for-type-and-lifetime-parameters). It was based on some assumptions, namely:

1. Capturing all type parameters sufficed for the vast majority of use cases.
2. We would always have a more explicit syntax for controlling captures later.
3. It was considered bad ergonomics to allow lifetime capture without explicit syntax.

The authors of this doc are not aware of any evidence to contradict the first point. The second point remains as an expectation, because TAIT and to a lesser extent ATPIT give us finer grained control over what lifetimes an opaque type is allowed to capture.

On the third point however, we have since had some significant developments in the Rust language, namely the addition of async. The `async fn` syntax was created in part out of necessity because of the rather awkward desugaring it produced. We can see this in a simple example:

struct MyServer {
    db: Database,
}

impl MyServer {
    async fn query(&self) -> Response {
        let results = self.db.query().await;
        Response::new(results)
    }
}

The above method desugars to a signature like this:

impl MyServer {
    fn query(&self) -> impl Future<Output = Response> + '_ {
        async { ... }
    }
}

The reason for this is evident in the method body above. Almost every async method needs access to the `self` reference to do anything useful. Since all code in an async function runs as part of the coroutine embedded in the opaque future type, that opaque type therefore needs to capture that lifetime.

There is an argument to be made that given this, along with the ergonomics issues of doing anything different we'll go into below, we should flip the default over an edition to capturing all lifetimes in scope. If we do not, we will probably have to invent some new syntax or other clever solution out of the problems we are about to cover.

Eventually the lang team will need to decide on a resolution to this question, and it is useful context for the discussion we are having today. However, it is **not** an explicit outcome to be decided in today's meeting.

### What to do when the capture rules don't match your use case

* `+ 'a`
* `Captures`
* Desugar to ITPIT or TAIT
* Currently unstable
* Alternative: Opt out syntax. But if `+ 'a` was already confusing, `+ ?'a` is going to be much worse.

## Framing

There are two questions to be answered about RPITIT capture rules:

* When should RPITITs be allowed to name lifetimes from their *method signature*?
* When should RPITITs be allowed to name lifetimes from their *enclosing item* (impl, trait)?

Let's take these one at a time.

### When should RPITITs be allowed to name lifetimes from their *method signature*?

This question relates directly to the one we posed above.

#### Answer: Only if mentioned

...

The hazard of answering "only if mentioned" is that traits involving lifetimes and RPITITs are harder to write correctly.

#### Answer: Always

If we decide the answer should be "yes" to the "all generic lifetimes" question, we could decide to implement that behavior *now* for RPITITs.

The hazard of answering "always" is that it is inconsistent with the existing behavior of RPIT in free functions and inherent impls. This inconsistency is likely to be noticed: You would need `+ 'a` (or `+ Captures<&'a ()>`) in some places and not in others.

#### Recommendation

TODO

### When should RPITITs be allowed to name lifetimes from their *enclosing item* (impl, trait)?

#### Today: RPIT capture rules for inherent impls

(example)

The problem with this precedent is it's unworkable for RPITITs:

(examples)

#### Answer: Always

* Inconsistent with inherent impls: If you copy the signature from an inherent impl to a trait or trait impl, you no longer need to mention `+ 'a`
* Inconsistent with desugaring to ATPIT today, but this can be changed
* Presumes that we have a way to "opt out" by desugaring to ATPITs or TAITs

#### Answer: Only if mentioned in the impl

* Inconsistent with inherent on the trait
* Non copyable signatures from trait -> impl

Additionally, if we answer "always" to the above question, it would be very surprising to answer "only if mentioned" to this one.

#### Answer: Only if mentioned in the trait

* Fully consistent with inherent
* Unworkable

#### Recommendation

TODO

## Summary

TODO: Matrix showing each possible decision, plus a list of use cases (below), plus an icon that says whether it works, works with style lint, works but has versioning hazard, or errors.

Use cases:

* Copying a signature from trait to trait impl
* Copying a signature from inherent impl to trait
* Copying a signature from inherent impl to trait impl
* The above, but in reverse?? (Less important)
* Authoring a trait from scratch

Also consider:

* Restricting captures of an RPIT in various positions
* (related) Stages of desugaring

## Appendix

We can include more examples here. Examples should have names.