Add core::hint::must_use

[dtolnay]

The example code in this documentation is minimized from a real-world situation in the anyhow crate where this function would have been valuable.

Having this provided by the standard library is especially useful for proc macros, even more than for macro_rules. That's because proc macro crates aren't allowed to export anything other than macros, so they couldn't make their own must_use function for their macro-generated code to call.

Rendered documentation

An identity function that causes an unused_must_use warning to be triggered if the given value is not used (returned, stored in a variable, etc) by the caller.

This is primarily intended for use in macro-generated code, in which a #[must_use] attribute either on a type or a function would not be convenient.

Example

#![feature(hint_must_use)]

use core::fmt;

pub struct Error(/* ... */);

#[macro_export]
macro_rules! make_error {
    ($($args:expr),*) => {
        core::hint::must_use({
            let error = $crate::make_error(core::format_args!($($args),*));
            error
        })
    };
}

// Implementation detail of make_error! macro.
#[doc(hidden)]
pub fn make_error(args: fmt::Arguments<'_>) -> Error {
    Error(/* ... */)
}

fn demo() -> Option<Error> {
    if true {
        // Oops, meant to write `return Some(make_error!("..."));`
        Some(make_error!("..."));
    }
    None
}

In the above example, we'd like an unused_must_use lint to apply to the value created by make_error!. However, neither #[must_use] on a struct nor #[must_use] on a function is appropriate here, so the macro expands using core::hint::must_use instead.

• We wouldn't want #[must_use] on the struct Error because that would make the following unproblematic code trigger a warning:

  fn f(arg: &str) -> Result<(), Error>
  
  #[test]
  fn t() {
      // Assert that `f` returns error if passed an empty string.
      // A value of type `Error` is unused here but that's not a problem.
      f("").unwrap_err();
  }

• Using #[must_use] on fn make_error can't help because the return value is used, as the right-hand side of a let statement. The let statement looks useless but is in fact necessary for ensuring that temporaries within the format_args expansion are not kept alive past the creation of the Error, as keeping them alive past that point can cause autotrait issues in async code:

  async fn f() {
      // Using `let` inside the make_error expansion causes temporaries like
      // `unsync()` to drop at the semicolon of that `let` statement, which
      // is prior to the await point. They would otherwise stay around until
      // the semicolon on *this* statement, which is after the await point,
      // and the enclosing Future would not implement Send.
      log(make_error!("look: {:p}", unsync())).await;
  }
  
  async fn log(error: Error) {/* ... */}
  
  // Returns something without a Sync impl.
  fn unsync() -> *const () {
      0 as *const ()
  }

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

This seems pretty elegant, but I suppose there are a couple language-altering alternatives that spring to mind:

• #[must_use] on macro_rules! (perhaps on each arm, or on the whole macro), perhaps with a lint or error if the macro does not produce an expression. Likely pretty complicated, not really worthwhile.
• #[must_use] on an arbitrary block:

#[must_use]
{
    some_expr
}

I feel like the second option in particular feels somewhat nice, though it's definitely more work to implement and may have design problems I'm missing. It feels a little more "native" in some sense, and might make a slight difference in some subtle edge cases -- I'm not sure whether for example type inference will always 'see through' the identity function, whereas through just a block it might be easier to do so. But I don't have immediate cases that I can think of.

[Mark-Simulacrum]

That said, I would be totally fine adding this as unstable (r=me), if you want to file a tracking issue for it (maybe with my options as "questions", or feel free to r? a libs-api member if you want another pair of eyes from the team proper.

[dtolnay]

Added tracking issue: #94745.

#[must_use] on blocks would be better than this function if it's doable. Let's definitely reevaluate before stabilizing. I recorded the alternatives in the tracking issue.

@bors r=Mark-Simulacrum

[bors]

📌 Commit b2473e9 has been approved by Mark-Simulacrum