Text of rust.docs.kernel.org › core › hint › fn.must_use.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

must_use in core::hint - Rust

Skip to main content must_use core :: hint Function must_ use Source pub const 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 = 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 () }