Rollup merge of #58183 - jethrogb:jb/alloc-box-guarantees, r=SimonSapin

Clarify guarantees for `Box` allocation

This basically says `Box` does the obvious things for its allocations.

See also: https://users.rust-lang.org/t/alloc-crate-guarantees/24981

This may require a T-libs FCP? Not sure.

r? @sfackler

diff --git a/src/liballoc/alloc.rs b/src/liballoc/alloc.rs
index ec652df3b37a49829a1f2972a7f3b99ef82e0a3d..f3877e51a6633f2589885ce08015fa5d0da46b85 100644 (file)
--- a/src/liballoc/alloc.rs
+++ b/src/liballoc/alloc.rs
@@ -34,6 +34,9 @@ fn __rust_realloc(ptr: *mut u8,
 /// This type implements the [`Alloc`] trait by forwarding calls
 /// to the allocator registered with the `#[global_allocator]` attribute
 /// if there is one, or the `std` crate’s default.
+///
+/// Note: while this type is unstable, the functionality it provides can be
+/// accessed through the [free functions in `alloc`](index.html#functions).
 #[unstable(feature = "allocator_api", issue = "32838")]
 #[derive(Copy, Clone, Default, Debug)]
 pub struct Global;

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index 0cd2373c7f0215c19d9924522610eac7294f3d02..e99ae6315f830c605c0f76d6f6809bc80f865e27 100644 (file)
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -4,6 +4,16 @@
 //! heap allocation in Rust. Boxes provide ownership for this allocation, and
 //! drop their contents when they go out of scope.
 //!
+//! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for
+//! its allocation. 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)`.
+//!
 //! # Examples
 //!
 //! Move a value from the stack to the heap by creating a [`Box`]: