Guarantees of content preservation on `try_reserve` failure?

[lo48576]

Location

Any try_reserve methods of container types (12 in Rust 1,62.1, including duplicated ones in alloc), and maybe corresponding try_reserve_exact methods.

• std::collections::BinaryHeap::try_reserve[_exact]
• std::collections::VecDeque::try_reserve[_exact]
• std::collections::HashMap::try_reserve
• std::collections::HashSet::try_reserve
• std::ffi::OsString::try_reserve[_exact]
• std::path::PathBuf::try_reserve[_exact]
• std::string::String::try_reserve[_exact]
• std::vec::Vec::try_reserve[_exact]
• ... and corresponding methods in alloc.

Summary

Documentations for try_reserve describes "If the capacity overflows, or the allocator reports a failure, then an error is returned.".
However, it does not give any guarantees about whether the content is preserved or not on that error.
This guarantee (or absence of the guarantee) should be explicitly described.

[scottmcm]

At least for Vec (and Vec-based things like String) it's obvious to guarantee that, so we might as well. (Thank you, Rust, for insisting on move-is-memcpy so we don't have the "what if the move constructor panics" problems like C++.)

I think it'll need to be added to hashbrown before we can consider promising it for HashMap/HashSet, through -- there's no guarantee in https://rust-lang.github.io/hashbrown/hashbrown/hash_map/struct.HashMap.html#method.try_reserve.

[joshtriplett]

Modulo needing to add it in hashbrown, shall we see if we have consensus to say that try_reserve failures preserve the current contents?

@rfcbot merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.