From 47a7a07a8b9f9c1b7a2de3de4632e4e261260cf4 Mon Sep 17 00:00:00 2001 From: The8472 Date: Tue, 24 Aug 2021 23:30:05 +0200 Subject: [PATCH 1/5] rename module to better reflect its purpose --- .../src/vec/{source_iter_marker.rs => in_place_collect.rs} | 0 library/alloc/src/vec/mod.rs | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename library/alloc/src/vec/{source_iter_marker.rs => in_place_collect.rs} (100%) diff --git a/library/alloc/src/vec/source_iter_marker.rs b/library/alloc/src/vec/in_place_collect.rs similarity index 100% rename from library/alloc/src/vec/source_iter_marker.rs rename to library/alloc/src/vec/in_place_collect.rs diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 5131168db0c82..07d109ea8e1f5 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -108,7 +108,7 @@ use self::is_zero::IsZero; mod is_zero; #[cfg(not(no_global_oom_handling))] -mod source_iter_marker; +mod in_place_collect; mod partial_eq; From 79b43b35bee22c89334485d8847c4fae0b54a6c6 Mon Sep 17 00:00:00 2001 From: The8472 Date: Tue, 24 Aug 2021 23:54:14 +0200 Subject: [PATCH 2/5] move AsIntoIter helper trait and mark it as unsafe --- library/alloc/src/collections/binary_heap.rs | 2 +- library/alloc/src/vec/in_place_collect.rs | 9 ++++++++- library/alloc/src/vec/into_iter.rs | 12 ++++-------- library/alloc/src/vec/mod.rs | 2 +- 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs index e6c3d38dab3a2..9849503f546b3 100644 --- a/library/alloc/src/collections/binary_heap.rs +++ b/library/alloc/src/collections/binary_heap.rs @@ -1416,7 +1416,7 @@ unsafe impl SourceIter for IntoIter { #[doc(hidden)] unsafe impl InPlaceIterable for IntoIter {} -impl AsIntoIter for IntoIter { +unsafe impl AsIntoIter for IntoIter { type Item = I; fn as_into_iter(&mut self) -> &mut vec::IntoIter { diff --git a/library/alloc/src/vec/in_place_collect.rs b/library/alloc/src/vec/in_place_collect.rs index 6e78534cf5b10..ff7780ee07d6f 100644 --- a/library/alloc/src/vec/in_place_collect.rs +++ b/library/alloc/src/vec/in_place_collect.rs @@ -2,7 +2,7 @@ use core::iter::{InPlaceIterable, SourceIter, TrustedRandomAccessNoCoerce}; use core::mem::{self, ManuallyDrop}; use core::ptr::{self}; -use super::{AsIntoIter, InPlaceDrop, SpecFromIter, SpecFromIterNested, Vec}; +use super::{InPlaceDrop, SpecFromIter, SpecFromIterNested, Vec}; /// Specialization marker for collecting an iterator pipeline into a Vec while reusing the /// source allocation, i.e. executing the pipeline in place. @@ -154,3 +154,10 @@ where len } } + +// internal helper trait for in-place iteration specialization. +#[rustc_specialization_trait] +pub(crate) unsafe trait AsIntoIter { + type Item; + fn as_into_iter(&mut self) -> &mut super::IntoIter; +} diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs index f985fb78465b9..7cbf3395269ff 100644 --- a/library/alloc/src/vec/into_iter.rs +++ b/library/alloc/src/vec/into_iter.rs @@ -1,3 +1,5 @@ +#[cfg(not(no_global_oom_handling))] +use super::AsIntoIter; use crate::alloc::{Allocator, Global}; use crate::raw_vec::RawVec; use core::fmt; @@ -338,14 +340,8 @@ unsafe impl SourceIter for IntoIter { } } -// internal helper trait for in-place iteration specialization. -#[rustc_specialization_trait] -pub(crate) trait AsIntoIter { - type Item; - fn as_into_iter(&mut self) -> &mut IntoIter; -} - -impl AsIntoIter for IntoIter { +#[cfg(not(no_global_oom_handling))] +unsafe impl AsIntoIter for IntoIter { type Item = T; fn as_into_iter(&mut self) -> &mut IntoIter { diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 07d109ea8e1f5..0b305b49d5129 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -96,7 +96,7 @@ mod drain; mod cow; #[cfg(not(no_global_oom_handling))] -pub(crate) use self::into_iter::AsIntoIter; +pub(crate) use self::in_place_collect::AsIntoIter; #[stable(feature = "rust1", since = "1.0.0")] pub use self::into_iter::IntoIter; From a1a602adde806fb63853f705d8c98884e991545b Mon Sep 17 00:00:00 2001 From: The8472 Date: Sat, 31 Jul 2021 17:39:35 +0200 Subject: [PATCH 3/5] add module-level documentation for vec's in-place iteration --- library/alloc/src/collections/binary_heap.rs | 2 + library/alloc/src/vec/in_place_collect.rs | 172 ++++++++++++++++--- library/alloc/src/vec/into_iter.rs | 5 + library/core/src/iter/adapters/mod.rs | 5 + library/core/src/iter/traits/marker.rs | 4 + 5 files changed, 168 insertions(+), 20 deletions(-) diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs index 9849503f546b3..2ab52a4d58401 100644 --- a/library/alloc/src/collections/binary_heap.rs +++ b/library/alloc/src/collections/binary_heap.rs @@ -1401,6 +1401,8 @@ impl ExactSizeIterator for IntoIter { #[stable(feature = "fused", since = "1.26.0")] impl FusedIterator for IntoIter {} +// In addition to the SAFETY invariants of the following three unsafe traits +// also refer to the vec::in_place_collect module documentation to get an overview #[unstable(issue = "none", feature = "inplace_iteration")] #[doc(hidden)] unsafe impl SourceIter for IntoIter { diff --git a/library/alloc/src/vec/in_place_collect.rs b/library/alloc/src/vec/in_place_collect.rs index ff7780ee07d6f..59f7cc6b004d1 100644 --- a/library/alloc/src/vec/in_place_collect.rs +++ b/library/alloc/src/vec/in_place_collect.rs @@ -1,3 +1,132 @@ +//! Inplace iterate-and-collect specialization for `Vec` +//! +//! The specialization in this module applies to iterators in the shape of +//! `source.adapter().adapter().adapter().collect::>()` +//! where `source` is an owning iterator obtained from [`Vec`], [`Box<[T]>`] (by conversion to `Vec`) +//! or [`BinaryHeap`], the adapters each consume one or more items per step +//! (represented by [`InPlaceIterable`]), provide transitive access to `source` (via [`SourceIter`]) +//! and thus the underlying allocation. And finally the layouts of `T` and `U` must +//! have the same size and alignment, this is currently ensured via const eval instead of trait +//! bounds. +//! +//! [`BinaryHeap`]: crate::collections::BinaryHeap +//! [`Box<[T]>`]: crate::boxed::Box +//! +//! By extension some other collections which use `collect::Vec<_>()` internally in their +//! `FromIterator` implementation benefit from this too. +//! +//! Access to the underlying source goes through a further layer of indirection via the private +//! trait [`AsIntoIter`] to hide the implementation detail that other collections may use +//! `vec::IntoIter` internally. +//! +//! In-place iteration depends on the interaction of several unsafe traits, implementation +//! details of multiple parts in the iterator pipeline and often requires holistic reasoning +//! across multiple structs since iterators are executed cooperatively rather than having +//! a central evaluator/visitor struct executing all iterator components. +//! +//! # Reading from and writing to the same allocation +//! +//! By its nature collecting in place means that the reader and writer side of the iterator +//! use the same allocation. Since `fold()` and co. take a reference to the iterator for the +//! duration of the iteration that means we can't interleave the step of reading a value +//! and getting a reference to write to. Instead raw pointers must be used on the reader +//! and writer side. +//! +//! That writes never clobber a yet-to-be-read item is ensured by the [`InPlaceIterable`] requirements. +//! +//! # Layout constraints +//! +//! [`Allocator`] requires that `allocate()` and `deallocate()` have matching alignment and size. +//! Additionally this specialization doesn't make sense for ZSTs as there is no reallocation to +//! avoid and it would make pointer arithmetic more difficult. +//! +//! [`Allocator`]: core::alloc::Allocator +//! +//! # Drop- and panic-safety +//! +//! Iteration can panic, requiring dropping the already written parts but also the remainder of +//! the source. Iteration can also leave some source items unconsumed which must be dropped. +//! All those drops in turn can panic which then must either leak the allocation or abort to avoid +//! double-drops. +//! +//! These tasks are handled by [`InPlaceDrop`] and [`vec::IntoIter::forget_allocation_drop_remaining()`] +//! +//! [`vec::IntoIter::forget_allocation_drop_remaining()`]: super::IntoIter::forget_allocation_drop_remaining() +//! +//! # O(1) collect +//! +//! The main iteration itself is further specialized when the iterator implements +//! [`TrustedRandomAccessNoCoerce`] to let the optimizer see that it is a counted loop with a single +//! induction variable. This can turn some iterators into a noop, i.e. it reduces them from O(n) to +//! O(1). This particular optimization is quite fickle and doesn't always work, see [#79308] +//! +//! [#79308]: https://github.com/rust-lang/rust/issues/79308 +//! +//! Since unchecked accesses through that trait do not advance the read pointer of `IntoIter` +//! this would interact unsoundly with the requirements about dropping the tail described above. +//! But since the normal `Drop` implementation of `IntoIter` would suffer from the same problem it +//! is only correct for `TrustedRandomAccessNoCoerce` to be implemented when the items don't +//! have a destructor. Thus that implicit requirement also makes the specialization safe to use for +//! in-place collection. +//! +//! # Adapter implementations +//! +//! The invariants for adapters are documented in [`SourceIter`] and [`InPlaceIterable`], but +//! getting them right can be rather subtle for multiple, sometimes non-local reasons. +//! For example `InPlaceIterable` would be valid to implement for [`Peekable`], except +//! that it is stateful, cloneable and `IntoIter`'s clone implementation shortens the underlying +//! allocation which means if the iterator has been peeked and then gets cloned there no longer is +//! enough room, thus breaking an invariant (#85322). +//! +//! [#85322]: https://github.com/rust-lang/rust/issues/85322 +//! [`Peekable`]: core::iter::Peekable +//! +//! +//! # Examples +//! +//! Some cases that are optimized by this specialization, more can be found in the `Vec` +//! benchmarks: +//! +//! ```rust +//! # #[allow(dead_code)] +//! /// Converts a usize vec into an isize one. +//! pub fn cast(vec: Vec) -> Vec { +//! // Does not allocate, free or panic. On optlevel>=2 it does not loop. +//! // Of course this particular case could and should be written with `into_raw_parts` and +//! // `from_raw_parts` instead. +//! vec.into_iter().map(|u| u as isize).collect() +//! } +//! ``` +//! +//! ```rust +//! # #[allow(dead_code)] +//! /// Drops remaining items in `src` and if the layouts of `T` and `U` match it +//! /// returns an empty Vec backed by the original allocation. Otherwise it returns a new +//! /// empty vec. +//! pub fn recycle_allocation(src: Vec) -> Vec { +//! src.into_iter().filter_map(|_| None).collect() +//! } +//! ``` +//! +//! ```rust +//! let vec = vec![13usize; 1024]; +//! let _ = vec.into_iter() +//! .enumerate() +//! .filter_map(|(idx, val)| if idx % 2 == 0 { Some(val+idx) } else {None}) +//! .collect::>(); +//! +//! // is equivalent to the following, but doesn't require bounds checks +//! +//! let mut vec = vec![13usize; 1024]; +//! let mut write_idx = 0; +//! for idx in 0..vec.len() { +//! if idx % 2 == 0 { +//! vec[write_idx] = vec[idx] + idx; +//! write_idx += 1; +//! } +//! } +//! vec.truncate(write_idx); +//! ``` use core::iter::{InPlaceIterable, SourceIter, TrustedRandomAccessNoCoerce}; use core::mem::{self, ManuallyDrop}; use core::ptr::{self}; @@ -16,11 +145,8 @@ where I: Iterator + SourceIter + InPlaceIterableMarker, { default fn from_iter(mut iterator: I) -> Self { - // Additional requirements which cannot expressed via trait bounds. We rely on const eval - // instead: - // a) no ZSTs as there would be no allocation to reuse and pointer arithmetic would panic - // b) size match as required by Alloc contract - // c) alignments match as required by Alloc contract + // See "Layout constraints" section in the module documentation. We rely on const + // optimization here since these conditions currently cannot be expressed as trait bounds if mem::size_of::() == 0 || mem::size_of::() != mem::size_of::<<::Source as AsIntoIter>::Item>() @@ -58,21 +184,13 @@ where ); } - // drop any remaining values at the tail of the source - // but prevent drop of the allocation itself once IntoIter goes out of scope - // if the drop panics then we also leak any elements collected into dst_buf + // Drop any remaining values at the tail of the source but prevent drop of the allocation + // itself once IntoIter goes out of scope. + // If the drop panics then we also leak any elements collected into dst_buf. // - // FIXME: Since `SpecInPlaceCollect::collect_in_place` above might use - // `__iterator_get_unchecked` internally, this call might be operating on - // a `vec::IntoIter` with incorrect internal state regarding which elements - // have already been “consumed”. However, the `TrustedRandomIteratorNoCoerce` - // implementation of `vec::IntoIter` is only present if the `Vec` elements - // don’t have a destructor, so it doesn’t matter if elements are “dropped multiple times” - // in this case. - // This argument technically currently lacks justification from the `# Safety` docs for - // `SourceIter`/`InPlaceIterable` and/or `TrustedRandomAccess`, so it might be possible that - // someone could inadvertently create new library unsoundness - // involving this `.forget_allocation_drop_remaining()` call. + // Note: This access to the source wouldn't be allowed by the TrustedRandomIteratorNoCoerce + // contract (used by SpecInPlaceCollect below). But see the "O(1) collect" section in the + // module documenttation why this is ok anyway. src.forget_allocation_drop_remaining(); let vec = unsafe { Vec::from_raw_parts(dst_buf, len, cap) }; @@ -155,7 +273,21 @@ where } } -// internal helper trait for in-place iteration specialization. +/// Internal helper trait for in-place iteration specialization. +/// +/// Currently this is only implemented by [`vec::IntoIter`] - returning a reference to itself - and +/// [`binary_heap::IntoIter`] which returns a reference to its inner representation. +/// +/// Since this is an internal trait it hides the implementation detail `binary_heap::IntoIter` +/// uses `vec::IntoIter` internally. +/// +/// [`vec::IntoIter`]: super::IntoIter +/// [`binary_heap::IntoIter`]: crate::collections::binary_heap::IntoIter +/// +/// # Safety +/// +/// In-place iteration relies on implementation details of `vec::IntoIter`, most importantly that +/// it does not create references to the whole allocation during iteration, only raw pointers #[rustc_specialization_trait] pub(crate) unsafe trait AsIntoIter { type Item; diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs index 7cbf3395269ff..f80d22d6bdb6d 100644 --- a/library/alloc/src/vec/into_iter.rs +++ b/library/alloc/src/vec/into_iter.rs @@ -99,6 +99,9 @@ impl IntoIter { /// (&mut into_iter).for_each(core::mem::drop); /// unsafe { core::ptr::write(&mut into_iter, Vec::new().into_iter()); } /// ``` + /// + /// This method is used by in-place iteration, refer to the vec::in_place_collect + /// documentation for an overview. #[cfg(not(no_global_oom_handling))] pub(super) fn forget_allocation_drop_remaining(&mut self) { let remaining = self.as_raw_mut_slice(); @@ -325,6 +328,8 @@ unsafe impl<#[may_dangle] T, A: Allocator> Drop for IntoIter { } } +// In addition to the SAFETY invariants of the following three unsafe traits +// also refer to the vec::in_place_collect module documentation to get an overview #[unstable(issue = "none", feature = "inplace_iteration")] #[doc(hidden)] unsafe impl InPlaceIterable for IntoIter {} diff --git a/library/core/src/iter/adapters/mod.rs b/library/core/src/iter/adapters/mod.rs index d82fde4752020..4500b44b7e9af 100644 --- a/library/core/src/iter/adapters/mod.rs +++ b/library/core/src/iter/adapters/mod.rs @@ -78,6 +78,11 @@ pub use self::zip::zip; /// The trait is unsafe because implementers must uphold additional safety properties. /// See [`as_inner`] for details. /// +/// The primary use of this trait is in-place iteration. Refer to the [`vec::in_place_collect`] +/// module documentation for more information. +/// +/// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html +/// /// # Examples /// /// Retrieving a partially consumed source: diff --git a/library/core/src/iter/traits/marker.rs b/library/core/src/iter/traits/marker.rs index 844459d77cd96..da753745740d7 100644 --- a/library/core/src/iter/traits/marker.rs +++ b/library/core/src/iter/traits/marker.rs @@ -51,6 +51,10 @@ unsafe impl TrustedLen for &mut I {} /// in its place, assuming structural constraints of the source allow such an insertion. /// In other words this trait indicates that an iterator pipeline can be collected in place. /// +/// The primary use of this trait is in-place iteration. Refer to the [`vec::in_place_collect`] +/// module documentation for more information. +/// +/// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html /// [`SourceIter`]: crate::iter::SourceIter /// [`next()`]: Iterator::next /// [`try_fold()`]: Iterator::try_fold From 7549cfa599004715a57fa17f8a988c216e0f6f4e Mon Sep 17 00:00:00 2001 From: The 8472 Date: Tue, 22 Mar 2022 00:02:54 +0100 Subject: [PATCH 4/5] rename internal helper trait AsIntoIter to AsVecIntoIter --- library/alloc/src/collections/binary_heap.rs | 4 ++-- library/alloc/src/vec/in_place_collect.rs | 10 +++++----- library/alloc/src/vec/into_iter.rs | 4 ++-- library/alloc/src/vec/mod.rs | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/library/alloc/src/collections/binary_heap.rs b/library/alloc/src/collections/binary_heap.rs index 2ab52a4d58401..ef5bef0253a56 100644 --- a/library/alloc/src/collections/binary_heap.rs +++ b/library/alloc/src/collections/binary_heap.rs @@ -151,7 +151,7 @@ use core::ptr; use crate::collections::TryReserveError; use crate::slice; -use crate::vec::{self, AsIntoIter, Vec}; +use crate::vec::{self, AsVecIntoIter, Vec}; use super::SpecExtend; @@ -1418,7 +1418,7 @@ unsafe impl SourceIter for IntoIter { #[doc(hidden)] unsafe impl InPlaceIterable for IntoIter {} -unsafe impl AsIntoIter for IntoIter { +unsafe impl AsVecIntoIter for IntoIter { type Item = I; fn as_into_iter(&mut self) -> &mut vec::IntoIter { diff --git a/library/alloc/src/vec/in_place_collect.rs b/library/alloc/src/vec/in_place_collect.rs index 59f7cc6b004d1..6dc548fc8e9ae 100644 --- a/library/alloc/src/vec/in_place_collect.rs +++ b/library/alloc/src/vec/in_place_collect.rs @@ -16,7 +16,7 @@ //! `FromIterator` implementation benefit from this too. //! //! Access to the underlying source goes through a further layer of indirection via the private -//! trait [`AsIntoIter`] to hide the implementation detail that other collections may use +//! trait [`AsVecIntoIter`] to hide the implementation detail that other collections may use //! `vec::IntoIter` internally. //! //! In-place iteration depends on the interaction of several unsafe traits, implementation @@ -142,16 +142,16 @@ impl InPlaceIterableMarker for T where T: InPlaceIterable {} impl SpecFromIter for Vec where - I: Iterator + SourceIter + InPlaceIterableMarker, + I: Iterator + SourceIter + InPlaceIterableMarker, { default fn from_iter(mut iterator: I) -> Self { // See "Layout constraints" section in the module documentation. We rely on const // optimization here since these conditions currently cannot be expressed as trait bounds if mem::size_of::() == 0 || mem::size_of::() - != mem::size_of::<<::Source as AsIntoIter>::Item>() + != mem::size_of::<<::Source as AsVecIntoIter>::Item>() || mem::align_of::() - != mem::align_of::<<::Source as AsIntoIter>::Item>() + != mem::align_of::<<::Source as AsVecIntoIter>::Item>() { // fallback to more generic implementations return SpecFromIterNested::from_iter(iterator); @@ -289,7 +289,7 @@ where /// In-place iteration relies on implementation details of `vec::IntoIter`, most importantly that /// it does not create references to the whole allocation during iteration, only raw pointers #[rustc_specialization_trait] -pub(crate) unsafe trait AsIntoIter { +pub(crate) unsafe trait AsVecIntoIter { type Item; fn as_into_iter(&mut self) -> &mut super::IntoIter; } diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs index f80d22d6bdb6d..f17b8d71b3a1a 100644 --- a/library/alloc/src/vec/into_iter.rs +++ b/library/alloc/src/vec/into_iter.rs @@ -1,5 +1,5 @@ #[cfg(not(no_global_oom_handling))] -use super::AsIntoIter; +use super::AsVecIntoIter; use crate::alloc::{Allocator, Global}; use crate::raw_vec::RawVec; use core::fmt; @@ -346,7 +346,7 @@ unsafe impl SourceIter for IntoIter { } #[cfg(not(no_global_oom_handling))] -unsafe impl AsIntoIter for IntoIter { +unsafe impl AsVecIntoIter for IntoIter { type Item = T; fn as_into_iter(&mut self) -> &mut IntoIter { diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 0b305b49d5129..9a66e69bdc061 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -96,7 +96,7 @@ mod drain; mod cow; #[cfg(not(no_global_oom_handling))] -pub(crate) use self::in_place_collect::AsIntoIter; +pub(crate) use self::in_place_collect::AsVecIntoIter; #[stable(feature = "rust1", since = "1.0.0")] pub use self::into_iter::IntoIter; From 29e29ce65d4a798927d1e2055613b81de8503b9f Mon Sep 17 00:00:00 2001 From: The 8472 Date: Wed, 23 Mar 2022 20:57:49 +0100 Subject: [PATCH 5/5] fix some links, clarify documentation based on review feedback --- library/alloc/src/vec/in_place_collect.rs | 31 ++++++++++++++--------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/library/alloc/src/vec/in_place_collect.rs b/library/alloc/src/vec/in_place_collect.rs index 6dc548fc8e9ae..282af8cc33fdd 100644 --- a/library/alloc/src/vec/in_place_collect.rs +++ b/library/alloc/src/vec/in_place_collect.rs @@ -1,18 +1,21 @@ //! Inplace iterate-and-collect specialization for `Vec` //! +//! Note: This documents Vec internals, some of the following sections explain implementation +//! details and are best read together with the source of this module. +//! //! The specialization in this module applies to iterators in the shape of //! `source.adapter().adapter().adapter().collect::>()` -//! where `source` is an owning iterator obtained from [`Vec`], [`Box<[T]>`] (by conversion to `Vec`) +//! where `source` is an owning iterator obtained from [`Vec`], [`Box<[T]>`][box] (by conversion to `Vec`) //! or [`BinaryHeap`], the adapters each consume one or more items per step //! (represented by [`InPlaceIterable`]), provide transitive access to `source` (via [`SourceIter`]) //! and thus the underlying allocation. And finally the layouts of `T` and `U` must -//! have the same size and alignment, this is currently ensured via const eval instead of trait -//! bounds. +//! have the same size and alignment, this is currently ensured via const eval instead of trait bounds +//! in the specialized [`SpecFromIter`] implementation. //! //! [`BinaryHeap`]: crate::collections::BinaryHeap -//! [`Box<[T]>`]: crate::boxed::Box +//! [box]: crate::boxed::Box //! -//! By extension some other collections which use `collect::Vec<_>()` internally in their +//! By extension some other collections which use `collect::>()` internally in their //! `FromIterator` implementation benefit from this too. //! //! Access to the underlying source goes through a further layer of indirection via the private @@ -27,10 +30,10 @@ //! # Reading from and writing to the same allocation //! //! By its nature collecting in place means that the reader and writer side of the iterator -//! use the same allocation. Since `fold()` and co. take a reference to the iterator for the -//! duration of the iteration that means we can't interleave the step of reading a value -//! and getting a reference to write to. Instead raw pointers must be used on the reader -//! and writer side. +//! use the same allocation. Since `try_fold()` (used in [`SpecInPlaceCollect`]) takes a +//! reference to the iterator for the duration of the iteration that means we can't interleave +//! the step of reading a value and getting a reference to write to. Instead raw pointers must be +//! used on the reader and writer side. //! //! That writes never clobber a yet-to-be-read item is ensured by the [`InPlaceIterable`] requirements. //! @@ -49,7 +52,8 @@ //! All those drops in turn can panic which then must either leak the allocation or abort to avoid //! double-drops. //! -//! These tasks are handled by [`InPlaceDrop`] and [`vec::IntoIter::forget_allocation_drop_remaining()`] +//! This is handled by the [`InPlaceDrop`] guard for sink items (`U`) and by +//! [`vec::IntoIter::forget_allocation_drop_remaining()`] for remaining source items (`T`). //! //! [`vec::IntoIter::forget_allocation_drop_remaining()`]: super::IntoIter::forget_allocation_drop_remaining() //! @@ -57,10 +61,11 @@ //! //! The main iteration itself is further specialized when the iterator implements //! [`TrustedRandomAccessNoCoerce`] to let the optimizer see that it is a counted loop with a single -//! induction variable. This can turn some iterators into a noop, i.e. it reduces them from O(n) to +//! [induction variable]. This can turn some iterators into a noop, i.e. it reduces them from O(n) to //! O(1). This particular optimization is quite fickle and doesn't always work, see [#79308] //! //! [#79308]: https://github.com/rust-lang/rust/issues/79308 +//! [induction variable]: https://en.wikipedia.org/wiki/Induction_variable //! //! Since unchecked accesses through that trait do not advance the read pointer of `IntoIter` //! this would interact unsoundly with the requirements about dropping the tail described above. @@ -68,6 +73,8 @@ //! is only correct for `TrustedRandomAccessNoCoerce` to be implemented when the items don't //! have a destructor. Thus that implicit requirement also makes the specialization safe to use for //! in-place collection. +//! Note that this safety concern is about the correctness of `impl Drop for IntoIter`, +//! not the guarantees of `InPlaceIterable`. //! //! # Adapter implementations //! @@ -76,7 +83,7 @@ //! For example `InPlaceIterable` would be valid to implement for [`Peekable`], except //! that it is stateful, cloneable and `IntoIter`'s clone implementation shortens the underlying //! allocation which means if the iterator has been peeked and then gets cloned there no longer is -//! enough room, thus breaking an invariant (#85322). +//! enough room, thus breaking an invariant ([#85322]). //! //! [#85322]: https://github.com/rust-lang/rust/issues/85322 //! [`Peekable`]: core::iter::Peekable