mark as_inner as unsafe and update comments

Author: the8472

src/liballoc/collections/binary_heap.rs

@@ -1150,7 +1150,7 @@ unsafe impl<T> SourceIter for IntoIter<T> {
     type Source = IntoIter<T>;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut Self::Source {
+    unsafe fn as_inner(&mut self) -> &mut Self::Source {
         self
     }
 }

src/liballoc/vec.rs

@@ -2061,6 +2061,8 @@ where
     }
 }
 
+// A helper struct for in-place iteration that drops the destination slice of iteration.
+// The source slice is dropped by IntoIter
 struct InPlaceDrop<T> {
     inner: *mut T,
     dst: *mut T,
@@ -2125,8 +2127,10 @@ where
             return SpecFromNested::from_iter(iterator);
         }
 
-        let src_buf = iterator.as_inner().as_into_iter().buf.as_ptr();
-        let src_end = iterator.as_inner().as_into_iter().end;
+        let (src_buf, src_end) = {
+            let inner = unsafe { iterator.as_inner().as_into_iter() };
+            (inner.buf.as_ptr(), inner.end)
+        };
         let dst = src_buf;
 
         let dst = if mem::needs_drop::<T>() {
@@ -2168,7 +2172,7 @@ where
                 .unwrap()
         };
 
-        let src = iterator.as_inner().as_into_iter();
+        let src = unsafe { iterator.as_inner().as_into_iter() };
         // check if SourceIter and InPlaceIterable contracts were upheld.
         // caveat: if they weren't we may not even make it to this point
         debug_assert_eq!(src_buf, src.buf.as_ptr());
@@ -2839,7 +2843,7 @@ unsafe impl<T> SourceIter for IntoIter<T> {
     type Source = IntoIter<T>;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut Self::Source {
+    unsafe fn as_inner(&mut self) -> &mut Self::Source {
         self
     }
 }

src/libcore/iter/adapters/mod.rs

@@ -20,7 +20,7 @@ pub use self::zip::Zip;
 #[unstable(issue = "0", feature = "std_internals")]
 pub use self::zip::TrustedRandomAccess;
 
-/// This trait provides transitive access to source-stages in an interator-adapter pipeline
+/// This trait provides transitive access to source-stage in an interator-adapter pipeline
 /// under the conditions that
 /// * the iterator source `S` itself implements `SourceIter<Source = S>`
 /// * there is a delegating implementation of this trait for each adapter in the pipeline between
@@ -47,7 +47,7 @@ pub use self::zip::TrustedRandomAccess;
 ///
 /// let mut iter = vec![9, 9, 9].into_iter().map(|i| i * i);
 /// let _ = iter.next();
-/// let mut remainder = std::mem::replace(iter.as_inner(), Vec::new().into_iter());
+/// let mut remainder = std::mem::replace(unsafe { iter.as_inner() }, Vec::new().into_iter());
 /// println!("n = {} elements remaining", remainder.len());
 /// ```
 ///
@@ -58,29 +58,33 @@ pub unsafe trait SourceIter {
     /// A source stage in an iterator pipeline.
     type Source: Iterator;
 
-    /// Extract the source of an iterator pipeline.
+    /// Retrieve the source of an iterator pipeline.
     ///
-    /// Callers may assume that calls to [`next()`] or any method taking `&self`
-    /// does no replace the referenced value.
-    /// But callers may replace the referenced values as long they in turn do not
-    /// expose it through a delegating implementation of this trait.
-    /// Which means that while adapters may not modify the reference they cannot
-    /// rely on it not being modified.
+    /// # Safety
     ///
-    /// Adapters must not rely on exclusive ownership or immutability of the source.
-    /// The lack of exclusive ownership also requires that adapters must uphold the source's
-    /// public API even when they have crate- or module-internal access.
+    /// Implementations of must return the same mutable reference for their lifetime, unless
+    /// replaced by a caller.
+    /// Callers may only replace the reference when they stopped iteration and drop the
+    /// iterator pipeline after extracting the source.
+    ///
+    /// This means iterator adapters can rely on the source not changing during
+    /// iteration but they cannot rely on it in their Drop implementations.
+    ///
+    /// Implementing this method means adapters relinquish private-only access to their
+    /// source and can only rely on guarantees made based on method receiver types.
+    /// The lack of restricted access also requires that adapters must uphold the source's
+    /// public API even when they have access to its internals.
     ///
     /// Callers in turn must expect the source to be in any state that is consistent with
     /// its public API since adapters sitting between it and the source have the same
     /// access. In particular an adapter may have consumed more elements than strictly necessary.
     ///
-    /// The overall goal of these requirements is to grant the consumer of a pipeline
-    /// access to the underlying storage of an iterator while restricting any statefulness
-    /// and side-effects of the pipeline stages from affecting or relying on that storage.
+    /// The overall goal of these requirements is to let the consumer of a pipeline use
+    /// * whatever remains in the source after iteration has stopped
+    /// * the memory that has become unused by advancing a consuming iterator
     ///
     /// [`next()`]: trait.Iterator.html#method.next
-    fn as_inner(&mut self) -> &mut Self::Source;
+    unsafe fn as_inner(&mut self) -> &mut Self::Source;
 }
 
 /// A double-ended iterator with the direction inverted.
@@ -959,7 +963,7 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -1106,7 +1110,7 @@ unsafe impl<S: Iterator, P, I: Iterator> SourceIter for Filter<I, P> where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -1249,7 +1253,7 @@ unsafe impl<S: Iterator, B, I: Iterator, F> SourceIter for FilterMap<I, F> where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -1479,7 +1483,7 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -1709,7 +1713,7 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -1826,7 +1830,7 @@ unsafe impl<S: Iterator, P, I: Iterator> SourceIter for SkipWhile<I, P> where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2033,7 +2037,7 @@ unsafe impl<S: Iterator, P, I: Iterator> SourceIter for TakeWhile<I, P> where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2232,7 +2236,7 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2341,7 +2345,7 @@ unsafe impl<S: Iterator, I: Iterator> SourceIter for Take<I> where I: SourceIter
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2489,7 +2493,7 @@ unsafe impl<St, F, B, S: Iterator, I: Iterator> SourceIter for Scan<I, St, F>
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2763,7 +2767,7 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }
@@ -2925,7 +2929,7 @@ unsafe impl<S: Iterator, I: Iterator, F> SourceIter for Inspect<I, F> where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.iter)
     }
 }

src/libcore/iter/adapters/zip.rs

@@ -305,13 +305,18 @@ where
     type Source = S;
 
     #[inline]
-    fn as_inner(&mut self) -> &mut S {
+    unsafe fn as_inner(&mut self) -> &mut S {
         SourceIter::as_inner(&mut self.a)
     }
 }
 
 #[unstable(issue = "0", feature = "inplace_iteration")]
-unsafe impl<A: InPlaceIterable, B: Iterator> InPlaceIterable for Zip<A, B> {}
+// Limited to Item: Copy since interaction between Zip's use of TrustedRandomAccess
+// and Drop implementation of the source is unclear.
+//
+// An additional method returning the number of times the source has been logically advanced
+// (without calling next()) would be needed to properly drop the remainder of the source.
+unsafe impl<A: InPlaceIterable, B: Iterator> InPlaceIterable for Zip<A, B> where A::Item: Copy {}
 
 /// An iterator whose items are random-accessible efficiently
 ///