discussion/tracking issue for #[must_use] functions in the standard library

[zackmdavis]

RFC 1940 authorized use of the #[must_use] attribute on functions (with the result that invocations of the function behave as if the return type was #[must_use].

This has been implemented for a while under a fn_must_use feature gate (tracking issue), and PR #48925 proposes stabilization.

#[must_use] has been added to the comparison methods in the standard library (.eq, .lt, &c.), but we never got a consensus as to what other standard library methods, if any, should get it. In principle, any function or with no side effects could be must-use (e.g., .len() on collections), but adding dozens or hundreds of annotations to the standard library feels kind of dramatic: perhaps must-use should instead be reserved for functions with "unusually result-like" semantics—after all, users who want to be really sure they're not uselessly throwing away a return value can always opt in to the (allow-by-default) unused-results lint.

If we wanted to be very conservative, we could refuse to stabilize until we've made a decision on this: if we were to stabilize first, any new #[must_use] annotations in the standard library would be insta-stable. But, maybe this isn't a big deal (cargo passes cap-lints allow to dependencies, so tinkering with lints shouldn't break people's builds).

[scottmcm]

I'm not sure "result-like" is broad enough. Maybe something like "things that may have side effects, but which ought never be used for their side effects, especially if often expensive". As a canonical example of such a thing, Iterator::collect. Perhaps more controversially, Clone::clone.

I definitely don't think this needs to block stabilization, because any deny(warnings) impact will be the same whether with stabilization or after it.

[scottmcm]

As of #49533, this is now on Iterator::collect, Clone::clone, and ToOwned::to_owned.

[jonhoo]

I think the non-assigning arithmetic functions are good candidates for this (see #50124).

[shepmaster]

Another metric could be: "things that (are highly likely to) allocate".

[shepmaster]

There's a concrete question around String::from_raw_parts, if people are interested in chiming in. My position is that such a function is mostly used for the purpose of converting back from FFI to be dropped, and shouldn't use the attribute.

[scottmcm]

A thought: I agree we don't want to clutter code with #[must_use] everywhere. But would we be open to the warnings if they came free? Is there some cheap conservative heuristic that would give a bunch of the warnings without the annotation noise? Perhaps "any &self method on a : Freeze type"?

[shepmaster]

Perhaps "any &self method

I was starting to think down these lines:

Any function which:

• returns non-() (and maybe some others, like !?)
• has no &mut arguments of any kind (including and beyond self)

And then we opt-out of things with internal mutability?

We may still end up with a lot of attributes if we follow @Manishearth's suggestion to have explanatory text on every function. (Not sure if I agree with that or not).

[est31]

In principle, any function or with no side effects could be must-use (e.g., .len() on collections), but adding dozens or hundreds of annotations to the standard library feels kind of dramatic

The Rust language already has a concept of side-effect freedom which is const fn. So what about adding a warn-by-default lint to the compiler that complains about any unused result of a const fn invocation? This would remove the need to add #[must_use] everywhere, and wouldn't water it down.

MUST is a very strong word. When I see #[must_use], I think that if the result isn't used, this is most likely a dangerous bug. Using the attribute to lint for dead code seems wrong to me because it would water down the strong meaning of MUST. Of course, dead code might hide a bug as well so this distinction is a bit muddy.

[jonhoo]

Hmm, I'm not sure that warning on unused const fn results is sufficient. I could be mistaken, but isn't it currently impossible to write a const fn that, say, does allocation (e.g., one that returns HashMap::new())?

[sfackler]

HashMap::new doesn't allocate.

[jonhoo]

Sorry, you're right. I guess String::from would be a better example.

[est31]

I've made an implementation of my lint idea here: #50805

@jonhoo allocating functions can be const fn. String::from is not const fn for a different reason: it needs a const impl Trait for Struct like feature as e.g. proposed in this RFC. But there is no good reason why the language can't be extended to make String::from const as well.

Edit: fixed link

[est31]

I've opened an RFC now as it seems that it requires one: rust-lang/rfcs#2450

[jonhoo]

As discussed in #52201, I think another set of candidates for this is methods like compare_and_swap on atomics; methods that do not return Result, but nonetheless need to have their return value checked to determine the outcome of the operation.

[LukasKalbertodt]

Just to give another example: I just noticed a bug in code that I wrote which could have been caught early with a proper #[must_use] lint. I assumed that a Vec has at leastone element and I wanted to remove the last element. So I wrote this:

vec.pop();

I didn't think about what would happen if the vec is empty. This empty case is a special case I need to cover elsewhere in my code. If the statement above would have caused a warning, I would have thought about it. So I guess the Option<T> returned by pop() is kind of "result like"?

I think marking pop with #[must_use] is a good idea. I think it's extremely rare that the programmer doesn't care about the returned value and also doesn't care about whether or not the method actually modified the vector.

[shepmaster]

I recently watched a newcomer to Rust write this shape of code:

let mut s = String::new();
stdin.read_line(&mut s);
s.trim();
if s == "hello" { /* ... */ }

They either believed that trim operates in-place or simply forgot to use the result, but a must_use on that would have helped them.

[rkjnsn]

I think marking pop with #[must_use] is a good idea. I think it's extremely rare that the programmer doesn't care about the returned value and also doesn't care about whether or not the method actually modified the vector.

I think I would lean more toward #[must_use] being reserved for situations where ignoring the return value is almost certainly a programmer error. It does not seem unreasonable that code might inspect the last element and, if a certain condition is met, discard it using pop. (Indeed, I have written similar code in other languages.)

In contrast, something like calling trim without checking the return value is surely an error, as there is no possible use for doing so.

[BatmanAoD]

@Jasperav That might be too big a change to make except at an edition boundary, but Rust 2021 is right around the corner 😃

[BatmanAoD]

It would also be appropriate to create an off-by-default clippy lint implementing that behavior, I think.

[scottmcm]

No need for a clippy lint; it already exists in rustc: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unused-results

[cuviper]

FYI, I've added a must_use on mem::replace in #71256. It doesn't quite meet the rough guidelines here about being useless otherwise, but I made the suggestion to use direct assignment if you don't need that return value. This idea came from noticing such unused values in some of my own code.

[scottmcm]

I like that change. I'd support a guideline for that kind of thing, perhaps

Add #[must_use] if there's a simpler construct that you can suggest in the message when the result is unused

That also covers things like the attribute that was added on split_off to suggest truncate.

[m-ou-se]

Is there any progress towards clearer guidelines for #[must_use]? #78225 adds #[must_use] for Iterator::count and Iterator::last, which seem to fall outside of the current rough guidelines. It would be nice to have some documentation to link and check PRs like that against.

[camsteffen]

I propose the following guideline:

Add #[must_use] to a function when, for any perceivable usage, not using the return value is a logic error or sub-optimal usage.

I disagree with the following:

MUST is a very strong word. When I see #[must_use], I think that if the result isn't used, this is most likely a dangerous bug.

"must" does not indicate the severity of the bug; It indicates the level of certainty that not using the value is wrong or sub-optimal.

I believe with this guideline, Iterator::count and Iterator::last can clearly be included.

[camsteffen]

After thinking some more, I think I can do better. I see three distinct reasons for adding #[must_use] (and all valid reasons IMHO). So here is another attempt at a comprehensive guideline:

Add #[must_use] if at least one of the following conditions is true:

1. The function has no effect other than producing a return value (a pure function).
2. There exists a better (more idiomatic, performant, etc.) way to do the same thing if the return value is not used.
3. The return value can indicate an exceptional outcome.

To say more about those 3 conditions:

1. Can be determined just by looking at the function itself. Unfortunately this is very common. But at the same time it should not cause any false positives. Examples: checked_add, Vec::new, str::trim, Iterator::map (includes builder-like patterns).

2. Can be determined by considering other API or language features. Thus it is more nuanced, but with the right justification, it should also be a rather confident decision. Examples: mem::replace, String::split_off, Iterator::last, Iterator::collect.

3. Can be determined by asking, "Does this function sometimes not do what it normally does?". I believe this is inescapably subjective: you need to define "normal" and "exceptional". For example, we probably don't want to include Vec::pop because None is "not very exceptional". But this is arguably the most important category for helping people avoid logic errors. By adding #[must_use], you are declaring, "If you're going to ignore the return value, you should do so explicitly." (how to idiomatically ignore a #[must_use] value is separate discussion). The good news is, for most instances, this is applied by simply returning Result. However, this category could also include mem::compare_and_swap.

Looking at the 3 conditions from another perspective:

1. Detects noop or possibly logic errors if the function was expected to modify input.
2. Detects non-idiomatic or sub-optimal usage.
3. Detects logic errors.

Condition #2 seems to stand out as "not as severe". But personally I don't think this is something to get hung up on - any unused_must_use warning could easily point to a huge logic error.

Bonus condition #4: The return value is literally designed to determine control flow (looking at you, ops::ControlFlow). Seems like a very strong case for #[must_use], but for a very unique reason that may never be repeated 😆.

It might be nice to have a special annotation for #1 like #[must_use(pure)] to avoid writing a bunch of similar error messages.

[scottmcm]

@m-ou-se No, I don't know of any. It really needs someone to pick it up and find a "hits the majority" subset so that must_use doesn't just become a "put it on everything" annotation.

Unfortunately this is very common

It might be nice to have a special annotation for #‍1 like #[must_use(pure)] to avoid writing a bunch of similar error messages.

Yeah, exactly. But because it's so common -- and the downside to not using something is often so minor -- I think this is a place for a lint to heuristically do it.

We know that unused_results is too strong, but it seems very plausible to start making lints to cut down on the frequency of needing extra annotations about this stuff.

For example, we could start with a lint for any const fns that are only passed &impl Freeze or impl Copy + 'static arguments. (Idea reference above.) Basically piggy-back on existing annotation work that's already happening, but also as a separate lint so people could decide they don't care if there's a few unnecessary calls to u32::wrapping_add, say, since they're very reliably get optimized out, even if they do want to know about the more important must_use warnings.

---

We could also consider an #[important_side_effect] annotation that would let the heuristics be more aggressive, though logistically transitioning to that might be awkward.

[shepmaster]

a lint to heuristically do it

Looking at this from the other direction, manually annotating a bunch of functions that fit into these categories (whatever they may be) could be a way to gauge the efficacy of any proposed heuristic. Effectively, this would be like how lifetime elision was established based on feedback from real world usages.

[jkugelman]

@camsteffen just brought this discussion to my attention.
cc @joshtriplett

Recently I independently asked around on Zulip and IRLO about adding #[must_use] throughout the standard library. Several Rust team members and many community members at large gave the green light.

• Zulip discussion
• internals.rust-lang.org discussion

With that go ahead, I put together a list of around 800 changes and have been working them off bit by bit. I'm about halfway done at this point. You can see the tracking issue here:

• Tracking issue for adding #[must_use] annotations throughout the standard library #89692

I'd appreciate everyone's feedback as I continue working on this.

[camsteffen]

It looks like your work is focused on the "pure function" case, which is the most straightforward.

[jkugelman]

Done! The MCP was accepted and the tracking issue is closed. std is now chock full of #[must_use]s.

[camsteffen]

The MCP adds clear guidelines for some cases that should have #[must_use], but I don't think it is a complete guideline. For example it would not include String::split_off. Namely cases 2 and 3 from my previous post are still open-ended. And some PRs were blocked on this discussion. What would happen to those PRs today if this issue is closed?

[jkugelman]

I concur. The guidelines in the MCP were for what I was using to scope my changes. I did not intend them to be proscriptive. There are certainly more cases that should be added.

I fudged my own rules a bit, even. To wit, I added a number of functions that take and return &mut when it was clear the mut is a passthrough and the function doesn't itself modify anything. For example:

HashMap::key_mut(&mut self) -> &mut K;
HashMap::get_mut(&mut self) -> &mut V;
HashMap::get_key_value(&mut self) -> (&K, &V);
HashMap::get_key_value_mut(&mut self) -> (&mut K, &mut V);