From 9e42d14927924036884734bd094747dd76b8b5f3 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Thu, 3 Dec 2020 10:56:13 +0800 Subject: [PATCH 1/3] Add Vec visualization to understand capacity Visualize vector while differentiating between stack and heap. Inspired by cheats.rs, as this is probably the first place beginner go, they could understand stack and heap, length and capacity with this. Not sure if adding this means we should add to other places too. Superseeds #76066 --- library/alloc/src/vec/mod.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index ccc4f03a1e505..88cdf588e3566 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -253,6 +253,26 @@ mod spec_extend; /// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`] /// whenever possible to specify how big the vector is expected to get. /// +/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be +/// visualized as: +/// +/// ```text +/// Stack ptr len capacity +/// /Heap +--------+--------+--------+ +/// | 0x0123 | 2 | 4 | +/// +--------+--------+--------+ +/// | +/// v +/// Heap +--------+--------+--------+--------+ +/// | 'a' | 'b' | uninit | uninit | +/// +--------+--------+--------+--------+ +/// ``` +/// +/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. +/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory +/// layout (including the order of fields). See [the section about +/// guarantees](#guarantees). +/// /// # Guarantees /// /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees @@ -345,6 +365,7 @@ mod spec_extend; /// [`push`]: Vec::push /// [`insert`]: Vec::insert /// [`reserve`]: Vec::reserve +/// [`MaybeUninit`]: core::mem::MaybeUninit /// [owned slice]: Box /// [slice]: ../../std/primitive.slice.html /// [`&`]: ../../std/primitive.reference.html From 9f338e18afd865e776d8f8cd7c763572a9a03ddf Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sat, 5 Dec 2020 10:21:54 +0800 Subject: [PATCH 2/3] Add more details explaning the Vec visualization Suggested by oli-obk --- library/alloc/src/vec/mod.rs | 42 +++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 88cdf588e3566..e09c3e5d23b03 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -253,26 +253,6 @@ mod spec_extend; /// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`] /// whenever possible to specify how big the vector is expected to get. /// -/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be -/// visualized as: -/// -/// ```text -/// Stack ptr len capacity -/// /Heap +--------+--------+--------+ -/// | 0x0123 | 2 | 4 | -/// +--------+--------+--------+ -/// | -/// v -/// Heap +--------+--------+--------+--------+ -/// | 'a' | 'b' | uninit | uninit | -/// +--------+--------+--------+--------+ -/// ``` -/// -/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. -/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory -/// layout (including the order of fields). See [the section about -/// guarantees](#guarantees). -/// /// # Guarantees /// /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees @@ -305,6 +285,28 @@ mod spec_extend; /// you would see if you coerced it to a slice), followed by [`capacity`]` - /// `[`len`] logically uninitialized, contiguous elements. /// +/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be +/// visualized as below. The top part is the `Vec` struct, it contains a +/// pointer to the head of the allocation in the heap, length and capacity. +/// The bottom part is the allocation on the heap, a contiguous memory block. +/// +/// ```text +/// ptr len capacity +/// +--------+--------+--------+ +/// | 0x0123 | 2 | 4 | +/// +--------+--------+--------+ +/// | +/// v +/// Heap +--------+--------+--------+--------+ +/// | 'a' | 'b' | uninit | uninit | +/// +--------+--------+--------+--------+ +/// ``` +/// +/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. +/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory +/// layout (including the order of fields). See [the section about +/// guarantees](#guarantees). +/// /// `Vec` will never perform a "small optimization" where elements are actually /// stored on the stack for two reasons: /// From 9844d9ee97f27f3d603f633e64bd03e1cc14e55b Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Thu, 21 Jan 2021 13:18:12 +0800 Subject: [PATCH 3/3] Remove link to current section Co-authored-by: Mara Bos --- library/alloc/src/vec/mod.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index e09c3e5d23b03..0f5feb4ab8dc4 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -304,8 +304,7 @@ mod spec_extend; /// /// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. /// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory -/// layout (including the order of fields). See [the section about -/// guarantees](#guarantees). +/// layout (including the order of fields). /// /// `Vec` will never perform a "small optimization" where elements are actually /// stored on the stack for two reasons: