Tracking issue for core::hint::must_use

[dtolnay]

Feature gate: #![feature(hint_must_use)]

This is a tracking issue for the function core::hint::must_use

Public API

// core::hint

#[must_use]
pub const fn must_use<T>(value: T) -> T {
    value
}

Steps / History

• Implementation: Add core::hint::must_use #94723
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Alternative: #[must_use] on an arbitrary block or expression?

  #[must_use]
  {
      some_expr
  }

  This feels more native, and might behave slightly better in some subtle edge cases—type inference may not always 'see through' the identity function in terms of whether unsize coercions occur before or after the call, whereas through a block that isn't an issue.

  Blocked on Tracking issue for stmt_expr_attributes: Add attributes to expressions, etc. #15701.

• Alternative: #[must_use] integrated into 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.

[dtolnay]

Copied over 2 proposed alternatives from #94723 (comment). I like #[must_use] on blocks if that can be made to work. Though it would be blocked on #15701 which has been open since 2014.

[Mark-Simulacrum]

I don't think it would be blocked on #15701 -- I believe exprs on blocks are currently permitted, e.g., cfg and lint attrs (allow etc) work:

fn foo() -> i32 {
    #[cfg(unix)]
    #[allow(unused)]
    {
        println!("test");
        let bar = 5;
        3
    }
}

I am not familiar with the implementation details of must_use enough to know whether putting it on a block causes problems, though naively I would assume it should not.

[nagisa]

I'm somewhat concerned it might give an impression to a developer that

fn my_function() -> u32 {
    core::hint::must_use(42)
}

is equivalent to

#[must_use]
fn my_function() -> u32 {
    42
}

[dtolnay]

@Mark-Simulacrum what currently works is attributes on statements. In order for us to use #[must_use] as a replacement for core::hint::must_use it would need to work on expressions in general, not on statements, which is not supported:

let _ = #[allow(unused_must_use)] { 0 };

error[E0658]: attributes on expressions are experimental
 --> src/lib.rs:2:13
  |
2 |     let _ = #[allow(unused_must_use)] { 0 };
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: see issue #15701 <https://github.com/rust-lang/rust/issues/15701> for more information

[dtolnay]

Alternatively I suppose it would be possible to support attributes only on an outermost macro-produced expression/block, without going all the way to attributes on expressions in general, if that's less prone to grammatical ambiguities or whatever is holding up #15701.

That is we could conceivably make the following work (which it doesn't today) without making the code in my previous comment work:

macro_rules! repro {
    () => {
        #[allow(unused_must_use)] { 0 }
    };
}


fn f() {
    let _ = repro!();
}

[CAD97]

To clarify, what @Mark-Simulacrum shows is not a statement; its' the entire body of the function, including tail return. You can use this to put an attribute on the body of any block:

[playground]

fn main() {
    let _ = { #[allow(unused_must_use)] 0 };
}

[playground]

pub fn is_foo_enabled() -> bool {
    #[cfg(feature = "foo")] {
        true
    }
    #[cfg(not(feature = "foo"))] {
        false
    }
}

[playground]

macro_rules! repro {
    () => {
        {
            // does not create a lint; the outer block "uses" it, I suspect
            #[must_use] {
                let [some, complicated, expansion] = [(); 3];
                let _ = [some, complicated, expansion];
                5
            }
        }
    };
}


pub fn f() {
    repro!();
}

[dtolnay]

All of what you showed are attributes on statements (StmtKind::Expr specifically). Attributes on expressions, where the expression is not a statement, are not supported on stable yet and would require #15701.

[dtolnay]

The reason #[must_use] on statements isn't suitable for the use case described in the docs of https://doc.rust-lang.org/nightly/core/hint/fn.must_use.html, which is an expression macro, is because you'd either need to write:

macro_rules! make_error {
    (...) => {
        #[must_use]
        {
            let error = ...;
            error
        }
    };
}

in which case a call site let _ = make_error!(...); becomes illegal (because attributes are not allowed on expressions); or you'd need to write:

macro_rules! make_error {
    (...) => {
        {
            #[must_use]
            {
                let error = ...;
                error
            }
        }
    };
}

in which case the #[must_use] doesn't do anything, because the value is always used as the value of the outer block, even if the macro caller does not use the value of the outer block:

macro_rules! repro {
    () => {
        {
            f()
        }
    }
}

#[must_use]
fn f() -> i32 {
    0
}

fn main() {
    repro!(); // not used, but no warning
}

[est31]

I've been wondering about using this function in the offset_of macro (#111669). It would be nice if you could customize the message. Ideally this would work via a &'static str const param:

#[lang = "must_use_fn"]
pub const fn must_use<T, const msg: &'static str>(value: T) -> T {
    value
}

This would require the adt_const_params feature though (#95174).

[wmmc88]

I'm somewhat concerned it might give an impression to a developer that

fn my_function() -> u32 {
    core::hint::must_use(42)
}

is equivalent to

#[must_use]
fn my_function() -> u32 {
    42
}

I am that developer 😄 . What exactly is the difference between these two must-use code blocks?

[est31]

@wmmc88 the former attaches the lint to the specific site (so it only fires once), while latter attaches it to every site my_function is called (so it fires as many times as you call my_function. Also, for former, only code inside the function matters while for latter, code at the site the function is called does. There is no cross-function dataflow analysis for the unused_must_use lint.