Function core::hint::must_use

const: unstable · source ·
pub fn must_use<T>(value: T) -> T
🔬This is a nightly-only experimental API. (hint_must_use #94745)
Expand description

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
}
Run

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();
    }
    Run
  • 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 ()
    }
    Run