rust-lang / rust-lang/rust

Rustonomicon and ManuallyDrop's documentation contradict each other about relying on drop order.

Open
#130,505 0 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs C-bug T-lang T-libs
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

Location

https://doc.rust-lang.org/nomicon/dropck.html#a-related-side-note-about-drop-order
https://doc.rust-lang.org/std/mem/struct.ManuallyDrop.html#manuallydrop-and-drop-order

Summary

The Rustonomicon states:

While the drop order of fields inside a struct is defined, relying on it is fragile and subtle. When the order matters, it is better to use the ManuallyDrop wrapper.

The docs for ManuallyDrop states:

Rust has a well-defined drop order of values. To make sure that fields or locals are dropped in a specific order, reorder the declarations such that the implicit drop order is the correct one.
It is possible to use ManuallyDrop to control the drop order, but this requires unsafe code and is hard to do correctly in the presence of unwinding.

That is, when you rely on fields being dropped in a specific order, the Rustonomicon recommends using ManuallyDrop, while the ManuallyDrop documentation recommends using field ordering. Which of the two is correct?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read the Rustonomicon dropck section, the ManuallyDrop documentation section, and the linked Reference destructors page. Determine the intended guidance on field ordering versus ManuallyDrop, then update the two cited documentation passages so they agree and verify the rendered links and wording.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.