Update boxed::Box docs on memory layout #60963
Merged
Conversation
This file contains 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
|
r? @shepmaster (rust_highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
The job Click to expand the log.I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
|
Whew. Above my paygrade. |
|
Could you rebase and then force-push your commits? Merge commits are not wanted. See https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests |
src/liballoc/boxed.rs
Outdated
| /// only valid pointer to pass to this function is the one taken | ||
| /// from another `Box` via the [`Box::into_raw`] function. | ||
| /// the destructor of `T` and free the allocated memory. For this | ||
| /// to be safe, the memory must have been allocated in the precise |
There was a problem hiding this comment.
Could this perhaps avoid duplicating the module docs? Maybe a section could be created in the module docs specifying the global allocator business, and this coul djust point there indicating how to interact with it?
There was a problem hiding this comment.
Sounds great! I've just pushed a commit up to do this, creating a section called "Memory Layout" in the module docs. I also moved this section down to the bottom since it seemed better to have the simple examples first, before the more detailed information on memory layout.
src/liballoc/boxed.rs
Outdated
| /// | ||
| /// let ptr = unsafe{ alloc(Layout::new::<i32>()) } as *mut i32; | ||
| /// unsafe{ *ptr = 5; } | ||
| /// let x = unsafe{ Box::from_raw(ptr) }; |
There was a problem hiding this comment.
Instead of an unsafe on each line, could this just be wrapped in one block? Additionally could "rustfmt be run over the code examples" here? I think that there's typically a space after the unsafe word, for example.
There was a problem hiding this comment.
rustfmt be run over the code examples
This can actually be done with an unstable rustfmt option. You'll want to make sure to only add the formatting changes to the code you were already changing.
There was a problem hiding this comment.
Done! And thanks for the tip on the new rustfmt feature; it worked!
|
@bors: r+ rollup |
|
📌 Commit 4e37785 has been approved by |
bors
added
S-waiting-on-bors
Centril
added a commit
to Centril/rust
that referenced
this pull request
May 21, 2019
Update boxed::Box docs on memory layout The existing docs for the `Box` type state that "the way `Box` allocates and releases memory is unspecified", and that therefore the only valid pointer to pass to `Box::from_raw` is one obtained from `Box::into_raw`. This is inconsistent with the module-level docs which specify, > It is valid to convert both ways between a Box and a raw pointer allocated with the Global allocator, given that the Layout used with the allocator is correct for the type. More precisely, a value: *mut T that has been allocated with the Global allocator with Layout::for_value(&*value) may be converted into a box using Box::<T>::from_raw(value). Conversely, the memory backing a value: *mut T obtained from Box::<T>::into_raw may be deallocated using the Global allocator with Layout::for_value(&*value). This pull request updates the docs for `Box` to make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction with `Box::from_raw` and `Box::into_raw`.
Centril
added a commit
to Centril/rust
that referenced
this pull request
May 21, 2019
Update boxed::Box docs on memory layout The existing docs for the `Box` type state that "the way `Box` allocates and releases memory is unspecified", and that therefore the only valid pointer to pass to `Box::from_raw` is one obtained from `Box::into_raw`. This is inconsistent with the module-level docs which specify, > It is valid to convert both ways between a Box and a raw pointer allocated with the Global allocator, given that the Layout used with the allocator is correct for the type. More precisely, a value: *mut T that has been allocated with the Global allocator with Layout::for_value(&*value) may be converted into a box using Box::<T>::from_raw(value). Conversely, the memory backing a value: *mut T obtained from Box::<T>::into_raw may be deallocated using the Global allocator with Layout::for_value(&*value). This pull request updates the docs for `Box` to make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction with `Box::from_raw` and `Box::into_raw`.
Centril
added a commit
to Centril/rust
that referenced
this pull request
May 21, 2019
Update boxed::Box docs on memory layout The existing docs for the `Box` type state that "the way `Box` allocates and releases memory is unspecified", and that therefore the only valid pointer to pass to `Box::from_raw` is one obtained from `Box::into_raw`. This is inconsistent with the module-level docs which specify, > It is valid to convert both ways between a Box and a raw pointer allocated with the Global allocator, given that the Layout used with the allocator is correct for the type. More precisely, a value: *mut T that has been allocated with the Global allocator with Layout::for_value(&*value) may be converted into a box using Box::<T>::from_raw(value). Conversely, the memory backing a value: *mut T obtained from Box::<T>::into_raw may be deallocated using the Global allocator with Layout::for_value(&*value). This pull request updates the docs for `Box` to make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction with `Box::from_raw` and `Box::into_raw`.
Centril
added a commit
to Centril/rust
that referenced
this pull request
May 22, 2019
Update boxed::Box docs on memory layout The existing docs for the `Box` type state that "the way `Box` allocates and releases memory is unspecified", and that therefore the only valid pointer to pass to `Box::from_raw` is one obtained from `Box::into_raw`. This is inconsistent with the module-level docs which specify, > It is valid to convert both ways between a Box and a raw pointer allocated with the Global allocator, given that the Layout used with the allocator is correct for the type. More precisely, a value: *mut T that has been allocated with the Global allocator with Layout::for_value(&*value) may be converted into a box using Box::<T>::from_raw(value). Conversely, the memory backing a value: *mut T obtained from Box::<T>::into_raw may be deallocated using the Global allocator with Layout::for_value(&*value). This pull request updates the docs for `Box` to make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction with `Box::from_raw` and `Box::into_raw`.
Centril
added a commit
to Centril/rust
that referenced
this pull request
May 22, 2019
Update boxed::Box docs on memory layout The existing docs for the `Box` type state that "the way `Box` allocates and releases memory is unspecified", and that therefore the only valid pointer to pass to `Box::from_raw` is one obtained from `Box::into_raw`. This is inconsistent with the module-level docs which specify, > It is valid to convert both ways between a Box and a raw pointer allocated with the Global allocator, given that the Layout used with the allocator is correct for the type. More precisely, a value: *mut T that has been allocated with the Global allocator with Layout::for_value(&*value) may be converted into a box using Box::<T>::from_raw(value). Conversely, the memory backing a value: *mut T obtained from Box::<T>::into_raw may be deallocated using the Global allocator with Layout::for_value(&*value). This pull request updates the docs for `Box` to make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction with `Box::from_raw` and `Box::into_raw`.
bors
added a commit
that referenced
this pull request
May 22, 2019
Rollup of 10 pull requests Successful merges: - #59742 (Move `edition` outside the hygiene lock and avoid accessing it) - #60581 (convert custom try macro to `?`) - #60963 (Update boxed::Box docs on memory layout) - #60973 (Avoid symbol interning in `file_metadata`.) - #60982 (Do not fail on child without DefId) - #60991 (LocalDecl push returns Local len) - #60995 (Add stream_to_parser_with_base_dir) - #60998 (static_assert: make use of anonymous constants) - #61003 (Remove impls for `InternedString`/string equality.) - #61006 (adjust deprecation date of mem::uninitialized) Failed merges: r? @ghost
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
The existing docs for the
Boxtype state that "the wayBoxallocates and releases memory is unspecified", and that therefore the only valid pointer to pass toBox::from_rawis one obtained fromBox::into_raw. This is inconsistent with the module-level docs which specify,This pull request updates the docs for
Boxto make them consistent with the module-level docs and adds some examples of how to use the global allocator in conjunction withBox::from_rawandBox::into_raw.