Add "# Safety" and "# Examples" section in std::mem::uninitialized
#151033
+33
−18
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Documentation of `std::mem::uninitialized` now have a # Safety section and a # Examples section.
rustbot
added
S-waiting-on-review
Collaborator
rustbot
added
S-waiting-on-author
rustbot
added
S-waiting-on-review
Contributor
|
Cc @rust-lang/libs for thoughts but I feel like we may not want this. There is never a time when I think that if somebody is interested in the actual semantics here, it's okay for them to read the source code. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Member
Agreed, we should let this deprecated function die. I'm especially wary that explicitly documenting safety conditions is really an API guarantee of sorts, while we really don't want anything that encourages its use. The current ambiguity serves as an additional warning flag not to use it. |
Member
|
I agree with not having an example, but I think listing out safety preconditions is still good (I'd reword them a bit though to clearly discourage use) |
Contributor
|
@rustbot author If you are still interested in pursuing this, please drop the examples and apply some rewording as Nora suggested. |
rustbot
added
S-waiting-on-author
Collaborator
|
Reminder, once the PR becomes ready for a review, use |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
tgross35
reviewed
Jan 22, 2026
Comment on lines
+715
to
+716
| /// - `T` must be *valid* with any sequence of bytes of the appropriate length, | ||
| /// initialized or uninitialized. |
Contributor
There was a problem hiding this comment.
I think we should hint that non-ZST T effectively needs to be all MaybeUninit to account for the uninitialized requirement. Not sure about best wording but maybe something like:
"... That is, if T is not a ZST, it must be MaybeUninit or an ADT containing only MaybeUninit and padding."
Contributor
Author
There was a problem hiding this comment.
I agree, but wouldn't that suggest a correct usage of this function? I removed that part because it would suggest that using uninitialized() with ZSTs is acceptable (and you said that we should discourage usage of uninitialized() by not providing any example, that's why I kept the safety conditions a bit more "abstract"). What do you think?
Contributor
There was a problem hiding this comment.
I don't think mentioning the MaybeUninit requirement suggests anything more than what is already there, just makes it more obvious that this isn't sound even for POD types (since that's been a confusion point in the past). Not mentioning ZSTs seems reasonable though.
Collaborator
|
This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed. Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers. |
Collaborator
|
Collaborator
|
The job Click to see the possible cause of the failure (guessed by this bot) |
Contributor
|
☔ The latest upstream changes (presumably #151634) made this pull request unmergeable. Please resolve the merge conflicts. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR improves documentation to
std::mem::uninitialized. While the function is deprecated, it currently lacks a formal # Safety section and clear examples on how to use it, even if it is almost always UB.