From 9c1415edb55b3a30e4c3a732d0890ca2d8fd7ca9 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sat, 29 Aug 2020 19:28:16 +0800 Subject: [PATCH 01/10] Add Vec visualization to understand capacity Visualize vector while differentiating between stack and heap. --- library/alloc/src/vec.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index b4ad238680f79..fef88fb6a453f 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -194,6 +194,19 @@ use crate::raw_vec::RawVec; /// 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. /// +/// In summary, a vector containing 1, 2 with capacity 4 can be visualized as: +/// ```text +/// Stack +--------+--------+--------+ +/// | ptr |capacity| len | +/// | 0x0123 | 4 | 2 | +/// +--------+--------+--------+ +/// | +/// v +/// Heap +--------+--------+--------+--------+ +/// | 1 | 2 | | | +/// +--------+--------+--------+--------+ +/// ``` +/// /// # Guarantees /// /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees From ea337c642c0e00bdfdea6cf1bbe2d5dbf0656a9c Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sat, 29 Aug 2020 20:11:54 +0800 Subject: [PATCH 02/10] Center align ptr and len box vec doc --- library/alloc/src/vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index fef88fb6a453f..c1c719919b7c1 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -197,7 +197,7 @@ use crate::raw_vec::RawVec; /// In summary, a vector containing 1, 2 with capacity 4 can be visualized as: /// ```text /// Stack +--------+--------+--------+ -/// | ptr |capacity| len | +/// | ptr |capacity| len | /// | 0x0123 | 4 | 2 | /// +--------+--------+--------+ /// | From f2bd46bbf3da961ffbdae43c60fafbfd3c522694 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sun, 30 Aug 2020 22:37:35 +0800 Subject: [PATCH 03/10] Link uninitialized memory to MaybeUninit --- library/alloc/src/vec.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index c1c719919b7c1..ef55f20df4941 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -203,10 +203,12 @@ use crate::raw_vec::RawVec; /// | /// v /// Heap +--------+--------+--------+--------+ -/// | 1 | 2 | | | +/// | 1 | 2 | uninit | uninit | /// +--------+--------+--------+--------+ /// ``` /// +/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`] +/// /// # Guarantees /// /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees @@ -300,6 +302,7 @@ use crate::raw_vec::RawVec; /// [`insert`]: Vec::insert /// [`reserve`]: Vec::reserve /// [owned slice]: Box +/// [`MaybeUninit`]: crate::mem::MaybeUninit #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "vec_type")] pub struct Vec { From 53af7b8eedade6fcdb9e8afae656b810018fd0cf Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sun, 30 Aug 2020 22:39:35 +0800 Subject: [PATCH 04/10] Vec visualization separate description --- library/alloc/src/vec.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index ef55f20df4941..61f9b95af5d95 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -196,8 +196,8 @@ use crate::raw_vec::RawVec; /// /// In summary, a vector containing 1, 2 with capacity 4 can be visualized as: /// ```text -/// Stack +--------+--------+--------+ -/// | ptr |capacity| len | +/// Stack ptr capacity len +/// +--------+--------+--------+ /// | 0x0123 | 4 | 2 | /// +--------+--------+--------+ /// | From a9195163a9b3ed64d4117f11df5fa49b75270bdc Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Mon, 31 Aug 2020 22:06:36 +0800 Subject: [PATCH 05/10] Link Vec visualization to core::mem::MaybeUninit Co-authored-by: Joshua Nelson --- library/alloc/src/vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index 61f9b95af5d95..430a7e5dcb1c5 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -302,7 +302,7 @@ use crate::raw_vec::RawVec; /// [`insert`]: Vec::insert /// [`reserve`]: Vec::reserve /// [owned slice]: Box -/// [`MaybeUninit`]: crate::mem::MaybeUninit +/// [`MaybeUninit`]: core::mem::MaybeUninit #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "vec_type")] pub struct Vec { From 55ad7f2aba4088462497cfd414467a68e9a3eefd Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Tue, 1 Sep 2020 09:34:44 +0800 Subject: [PATCH 06/10] Vec visualization mention unstable ABI --- library/alloc/src/vec.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index 430a7e5dcb1c5..b484cced99063 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -208,6 +208,7 @@ use crate::raw_vec::RawVec; /// ``` /// /// - **uninit** represents memory that is not initialized, see [`MaybeUninit`] +/// - Note, ABI is not stable so the layout is not guaranteed to be the same /// /// # Guarantees /// From 44e9b7f7606150c7aaf7493317ed27171ed4ecb7 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Thu, 15 Oct 2020 23:08:39 +0800 Subject: [PATCH 07/10] Use explicit details to relate to the diagram Co-authored-by: Lukas Kalbertodt --- library/alloc/src/vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index b484cced99063..bcee0d297a94a 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -194,7 +194,7 @@ use crate::raw_vec::RawVec; /// 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. /// -/// In summary, a vector containing 1, 2 with capacity 4 can be visualized as: +/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be visualized as: /// ```text /// Stack ptr capacity len /// +--------+--------+--------+ From 6900744da34fdfe7bd4b07744a4cdf7eb31b207a Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Thu, 15 Oct 2020 23:11:40 +0800 Subject: [PATCH 08/10] Make vec note for visualization more explicit Co-authored-by: Lukas Kalbertodt --- library/alloc/src/vec.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index bcee0d297a94a..9044632cc3948 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -207,8 +207,10 @@ use crate::raw_vec::RawVec; /// +--------+--------+--------+--------+ /// ``` /// -/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`] -/// - Note, ABI is not stable so the layout is not guaranteed to be the same +/// - **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 /// From 79918c1e6243f209cea7ff7e484a028eda2d4344 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Tue, 27 Oct 2020 18:42:34 +0800 Subject: [PATCH 09/10] Use alphabetical example in vec visualization Co-authored-by: Lukas Kalbertodt --- library/alloc/src/vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index 9044632cc3948..a3bcc0c7cba9e 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -203,7 +203,7 @@ use crate::raw_vec::RawVec; /// | /// v /// Heap +--------+--------+--------+--------+ -/// | 1 | 2 | uninit | uninit | +/// | 'a' | 'b' | uninit | uninit | /// +--------+--------+--------+--------+ /// ``` /// From 62ba5b1b56deaac2a3b3665c6621d43aadf49e94 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Tue, 1 Dec 2020 19:29:54 +0800 Subject: [PATCH 10/10] Fix vec doc merge conflict --- library/alloc/src/vec.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/library/alloc/src/vec.rs b/library/alloc/src/vec.rs index a3bcc0c7cba9e..718aa370cd170 100644 --- a/library/alloc/src/vec.rs +++ b/library/alloc/src/vec.rs @@ -306,6 +306,9 @@ use crate::raw_vec::RawVec; /// [`reserve`]: Vec::reserve /// [owned slice]: Box /// [`MaybeUninit`]: core::mem::MaybeUninit +/// [`MaybeUninit`]: core::mem::MaybeUninit +/// [slice]: ../../std/primitive.slice.html +/// [`&`]: ../../std/primitive.reference.html #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "vec_type")] pub struct Vec {