In-band lifetimes: Lint against single-use lifetime names

[nikomatsakis]

Once support for '_ lands in #44691, the next step for #44524 is to implement a lint that warns against "single use" lifetime names.

Current status

The lint is partially implemented but needs to be completed. Here is a checklist:

• Issue warnings at the right times; this gist provides a comprehensive test case.
  • "Warning: never used at all" falls under unused_lifetimes
• For each warning, issue a suggested fix:
  • For a single-use lifetime 'a appearing in &'a T, suggest &T
  • For a single-use lifetime 'a appearing in any other place, suggest '_
  • One challenge: the binder must be removed too
    • cc @estebank -- is it possible to give suggested fixes that make changes to multiple spots at once? I guess that might just be multiple suggestions?
• [] We'll know this is really done when we can enable by default in rustc crates and apply rustfix with suggestions

Older Background

The idea is that an explicit name like 'a should only be used (at least in a function or impl) to link together two things. Otherwise, you should just use '_ to indicate that the lifetime is not linked to anything.

Until #15872 is closed, we should only lint for single-use lifetime names that are bound in functions. Once #15872 is closed, we can also lint against those found in impl headers.

We can detect cases where a lint is valid by modifying the resolve_lifetimes code:

• This code basically walks over the HIR and resolves all lifetime names.
• It maintains a stack of scopes indicating what names are valid.
• The function with() is used to push new scopes on the stack. It is also given a closure which will execute with the new name bindings in scope.
  • with() gets called for impls and other kinds of items from here; for methods and functions in particular it is called from visit_early_late).
• Once a name is in scope, resolve_lifetime_ref() is called to resolve an actual reference to a named lifetime.
  • This could be used, for example, to update some information in the Scope, e.g. counting how many times a particular lifetime was referenced.
• Then, before with() returns, we could scan the lifetimes and check for those that were only referenced 1 time (or 0 times...) and issue a lint warning.

(There are some directions for how to add a lint under the header "Issuing future compatibility warnings" in the rustc-bug-fix-procedure page on forge -- we can skip the "future compatibility" parts here.)

[cramertj]

we should only lint for single-use lifetime names that are bound in functions

Also, I believe, only for lifetime names that appear in argument position. Currently we require explicitly binding output-only lifetimes with a name:

fn bar<'a>() -> &'a u8 { &5 } // OK
fn bar() -> &'_ u8 { &5 } // ERROR: missing lifetime specifier

[nikomatsakis]

@cramertj Hmm. I would consider the proper way to declare bar() to probably be fn bar() -> &'static u8, really, though there are subtleties involved in rare cases (e.g., around invariance).

[cramertj]

@nikomatsakis Yes, 'static is the right thing to use. I wanted to point out that we shouldn't recommend '_ here, as it won't work.

[gaurikholkar-zz]

Is this up for grabs?

[cramertj]

@gaurikholkar Go for it!

[gaurikholkar-zz]

Will start working on it

[nikomatsakis]

@gaurikholkar hey, just checking in! How's it going? Any blockers?

[nikomatsakis]

Some examples:

fn foo<'x>(_: &'x u32) { }

This should lint against 'x and suggest &u32 instead.

struct Foo<'a> { x: &'a u32 }
fn foo<'x>(_: Foo<'x>) { }

This should lint against 'x and suggest Foo<'_> instead.

struct Foo<'a, 'b> { f: &'a &'b u32 }
fn foo<'x, 'y>(foo: Foo<'x, 'y>) -> &'x u32 { foo.f }

This should lint against 'y and suggest Foo<'x, '_> instead.

struct Foo<'a, 'b> { f: &'a &'b u32 }
fn foo<'x, 'y>(foo: Foo<'x, 'y>) -> &'y u32 { foo.f }

This should lint against 'x and suggest Foo<'_, 'y> instead.

fn foo<'x>() -> &'x u32 { &22 }

This should not lint, because 'x appears only in the return type.

trait Trait<'a> { }
impl<'a, T> Trait<'a> for T { }

fn foo<'x, T>(t: T)
where T: Trait<'x>
{ 
}

fn main() { 
  foo(22);
}

This should not lint, because at present '_ does not work in that position (which we should fix).

[nikomatsakis]

OK, let's start with this specific test:

fn deref<'x>(v: &'x u32) -> u32 {
    *v
}

fn main() { }

When we are done, we want to issue a warning, probably like this:

fn deref<'x>(v: &'x u32) -> u32 {
//       ^^ lifetime name `'x` only used once
    *v
}

fn main() { }

In this case, the one use of 'x is as the operand to a &-type, so I think we don't have to say much more than that. If the one use of 'x were in a struct, we might want to have a hint indicating that it can be replaced with '_, but let's leave that stuff to future work.

The first thing we want to do then is to figure out how many times each name is used and where. Now, accounting around lifetimes (e.g., early-bound, late-bound, etc) can get kind of complicated, but luckily we can ignore most of that crap for our purposes. I imagine we would want to add to the LifetimeContext struct a new field:

lifetime_uses: DefIdMap<LifetimeUseSet<'tcx>

where a LifetimeUseSet<'tcx> is defined like:

enum LifetimeUseSet<'tcx> {
    One(&'tcx hir::Lifetime),
    Many,
}

We don't really need to track more detail than that -- once there are many uses of a lifetime, we don't want to warn about it anymore, so we don't need to track them. Now, when we are resolving a lifetime in resolve_lifetime_ref, we want to update these lifetime use sets. Actually, I think the place to add code is the insert_lifetime method, which records a successful lifetime resolution:

rust/src/librustc/middle/resolve_lifetime.rs

Lines 1516 to 1518 in 3cf28f3

	fn insert_lifetime(&mut self,
	lifetime_ref: &hir::Lifetime,
	def: Region) {

Here, we want to match on the def, which is of the type Region. We want to do something like:

match def {
    LateBoundAnon(..) | Static => {
        // These are anonymous lifetimes or lifetimes that are not declared.
    }

    Free(_, def_id) | LateBound(_, def_id) | EarlyBound(_, def_id) => {
        // A lifetime declared by the user.
        if !self.lifetime_uses.contains_key(&def_id) {
            self.lifetime_uses.insert(def_id, LifetimeUseSet::One(lifetime_ref));
        } else {
            self.lifetime_uses.insert(def_id, LifetimeUseSet::Many);
        }
    }
}

Now we have a record of where each lifetime def was used. The next step will be going over the set of lifetime names defined and warning if they are LifetimeUseSet::One. I'm going to stop here, but we can talk about the best way to do that later.

[gaurikholkar-zz]

I've been in touch with @nikomatsakis over this. The current status is: I've followed the instructions he has given above and written code for the same locally.

[nikomatsakis]

So, if we follow the steps above, we wind up with a map from the def-id of each LifetimeDef to either zero (no key), one, or many uses of it. I think maybe the easiest thing way to handle things is to do a second walk of the krate, just looking for lifetime defs, and issuing the warnings. Originally I had thought we could do them as we walk the first time, but now that seems like it would just clutter the code unnecessary.

This is the main function for resolve_lifetime:

https://github.com/rust-lang/rust/blob/master/src/librustc/middle/resolve_lifetime.rs#L259-L285

I am imagining that we can basically write a second visitor, struct LifetimeSingleUseWarnVisitor or something. Like LintContext, it will implement the visitor trait and return All for its nested_visitor_map:

https://github.com/rust-lang/rust/blob/master/src/librustc/middle/resolve_lifetime.rs#L287-L290

It would only implement one method, though, visit_lifetime_def:

fn visit_lifetime_def(&mut self, lifetime_def: &hir::LifetimeDef) {
    let def_id = self.tcx.hir.as_local_def_id(lifetime_def.id);
    ...
}

In there, it will check if the map contains def_id. If not, it can issue a warning "lifetime never used". If so, and it contains One, it will issue a warning "lifetime used only once". Otherwise, no warning. (Issuing a warning is done by calling add_lint, you can grep around for example.)

OK, this is a not quite right -- we're going to eventually want to be a bit more selective, since it will depend whether that use is one that could be elided or replaced with '_. But let's start there and then narrow it down.

[nikomatsakis]

Actually I take that back. Don't use a visitor. Just iterate over the map we built and look things up in the HIR map. For example, given the DefId of some lifetime def, we can look up its span in the HIR map by doing

let node_id = hir.as_local_node_id(def_id).unwrap(); // guarnateed to be local
let hir_lifetime: &hir::Lifetime = match hir.get(node_id) {
    hir_map::NodeLifetime(l) => l,
    _ => bug!()
};
let span = hir_lifetime.span;

[nikomatsakis]

Well, that won't allow you to catch lifetimes used zero times. To do that, we either need a separate visitor, or visit the map during with and store a "zero times" entry (extending the enum), or to visit the entries at the end of with and issue warnings.

[gaurikholkar-zz]

Track the progress here

[gaurikholkar-zz]

  |
3 | fn deref<'x>(v: &'x u32) -> u32 {
  |          ^^
  |
note: lint level defined here
 --> /home/user/mp/foo.rs:1:9
  |
1 | #![warn(single_use_lifetime)]
  |         ^^^^^^^^^^^^^^^^^^^

Is what gets generated for now

[gaurikholkar-zz]

@nikomatsakis it's compile-fail tests that are failing now

[nikomatsakis]

I started trying to record all places where this lint might be needed and document their expected behavior. This is not done, but I have to go, so I'm saving my status here for now. My goal is to make a checklist and try to mentor the remaining improvements.

File can be found in this gist.

[nikomatsakis]

Here is an updated check-list of the overall goals:

moved to issue header

[scottmcm]

Wow, it's been three years...

I still think this is important. I started looking at how in_band_lifetimes in rustc_mir_transform, and I immediately found a bunch of examples of unnecessary 'as. Here's just in coverage/spans.rs, since it was at the bottom of the error list:

-    pub fn format(&self, tcx: TyCtxt<'tcx>, mir_body: &'a mir::Body<'tcx>) -> String {
+    pub fn format<'tcx>(&self, tcx: TyCtxt<'tcx>, mir_body: &mir::Body<'tcx>) -> String {

-    pub fn format(&self, tcx: TyCtxt<'tcx>, mir_body: &'a mir::Body<'tcx>) -> String {
+    pub fn format<'tcx>(&self, tcx: TyCtxt<'tcx>, mir_body: &mir::Body<'tcx>) -> String {

-    pub fn format_coverage_statements(
+    pub fn format_coverage_statements<'tcx>(
         &self,
         tcx: TyCtxt<'tcx>,
-        mir_body: &'a mir::Body<'tcx>,
+        mir_body: &mir::Body<'tcx>,
     ) -> String {

-pub(super) fn filtered_statement_span(statement: &'a Statement<'tcx>) -> Option<Span> {
+pub(super) fn filtered_statement_span<'tcx>(statement: &Statement<'tcx>) -> Option<Span> {

-pub(super) fn filtered_terminator_span(terminator: &'a Terminator<'tcx>) -> Option<Span> {
+pub(super) fn filtered_terminator_span<'tcx>(terminator: &Terminator<'tcx>) -> Option<Span> {

[jackh726]

Okay, I've created the F-lint-single_use_lifetiems label and tagged the 6 relevant issues open for this.

The examples in the "current status" section at the top all warn and have a suggestion, except for the unused lifetime, which falls under the unused_lifetime lint.

Marking S-tracking-impl-complete, given that there are several linked issues that need to be fixed.

[est31]

With #96833 merged, there has been progress on this issue recently. The number of false positives is now way down, but there's still one remaining, according to the PR's description.

[cjgillot]

@est31 what is the remaining false positive?

[est31]

@cjgillot I was referring to:

Remaining false positive: single-use lifetimes in argument-position impl-trait.
I'm waiting for #96529 to be fixed to have a clean and proper solution here.

Or is the false positive fixed now?

[cjgillot]

Indeed, the remaining false positive is:

trait Foo<'a> {}

#[warn(single_use_lifetimes)]
fn foo<'a>(_: impl Foo<'a>) {}

Where the lifetime cannot be elided. There is an inconsistency here between plain functions and async functions (which allow elision). I suggested to allow elision in #97720.

If that change is accepted, there won't be a false positive any more, and the suggestion will be correct.

[bstrie]

I think the following might be an unaddressed false positive:

    pub fn get_json<T>(&self, limit: u64) -> Result<(Meta, T)>
    where
        for<'de> T: Deserialize<'de>,

error: lifetime parameter `'de` only used once
   --> crates/client/src/entity.rs:182:13
    |
182 |         for<'de> T: Deserialize<'de>,
    |             ^^^                 --- ...is used only here
    |             |
    |             this lifetime...

I'm not aware of any way to use anonymous lifetimes to avoid the single-use lifetime here.

[bstrie]

Another false positive:

fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Mime, D::Error> {

error: lifetime parameter `'de` only used once
  --> crates/type/src/meta.rs:31:16
   |
31 | fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Mime, D::Error> {
   |                ^^^ this lifetime... --- ...is used only here

Are anonymous lifetimes supposed to work here? The error:

error[E0637]: `'_` cannot be used here
  --> crates/type/src/meta.rs:31:32
   |
31 | fn deserialize<D: Deserializer<'_>>(deserializer: D) -> Result<Mime, D::Error> {
   |                                ^^ `'_` is a reserved lifetime name

---

Similar example:

    fn decode<'i, I>(values: &mut I) -> Result<Self, HeadErr>
    where
        Self: Sized,
        I: Iterator<Item = &'i HeaderValue>,

[cjgillot]

@bstrie, those cases are correctly handled by beta 1.63.0 https://play.rust-lang.org/?version=beta&mode=debug&edition=2021&gist=4fd54ae5a4d4a3a936054787f6655b7b

[clarfonthey]

This appears to ignore the fact that lifetimes inside impl Trait are currently unstable. See:

#![warn(single_use_lifetimes)]
fn test<'a>(val: &(impl 'a + Iterator)) {}

This actually suggests removing the lifetime, which in turn is suggested to be added back with:

#![warn(single_use_lifetimes)]
fn test(val: &(impl '_ + Iterator)) {}