Clarify guarantees for Box
allocation
This commit is contained in:
parent
8ae730a442
commit
e41e694d9e
2 changed files with 13 additions and 0 deletions
|
@ -34,6 +34,9 @@ extern "Rust" {
|
||||||
/// This type implements the [`Alloc`] trait by forwarding calls
|
/// This type implements the [`Alloc`] trait by forwarding calls
|
||||||
/// to the allocator registered with the `#[global_allocator]` attribute
|
/// to the allocator registered with the `#[global_allocator]` attribute
|
||||||
/// if there is one, or the `std` crate’s default.
|
/// 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")]
|
#[unstable(feature = "allocator_api", issue = "32838")]
|
||||||
#[derive(Copy, Clone, Default, Debug)]
|
#[derive(Copy, Clone, Default, Debug)]
|
||||||
pub struct Global;
|
pub struct Global;
|
||||||
|
|
|
@ -4,6 +4,16 @@
|
||||||
//! heap allocation in Rust. Boxes provide ownership for this allocation, and
|
//! heap allocation in Rust. Boxes provide ownership for this allocation, and
|
||||||
//! drop their contents when they go out of scope.
|
//! 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
|
//! # Examples
|
||||||
//!
|
//!
|
||||||
//! Move a value from the stack to the heap by creating a [`Box`]:
|
//! Move a value from the stack to the heap by creating a [`Box`]:
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue