ManuallyDrop suppresses the compiler's automatic invocation of Drop::drop when a value exits scope. When implementing IntoIterator for arrays or similar fixed-size collections, elements are extracted via ptr::read, which performs a bitwise move, leaving the source memory logically uninitialized. Without ManuallyDrop, if a panic occurs during destruction of a yielded element, the unwinding mechanism would invoke the array's destructor, attempting to drop all slots—including those already moved from—resulting in undefined behavior through double-drops. By wrapping the storage in ManuallyDrop, the implementer assumes responsibility for dropping only the remaining elements, typically by tracking an index and manually dropping the suffix in a custom Drop implementation.
You are building a FixedVec<T, const N: usize>—a stack-allocated vector with constant capacity—and must implement IntoIterator that consumes the collection by value.
The core problem emerges during element extraction: you must move each T out of the internal array to return it by value. If a user's T implementation panics during destruction while the iterator is partially consumed, the unwinding process must still clean up the remaining elements. However, some elements have already been bitwise-moved via ptr::read, leaving their original memory locations uninitialized. If the backing array is not wrapped in ManuallyDrop, its destructor will treat all slots as live T instances and invoke drop_in_place on them, resulting in double-drops for moved elements (undefined behavior) and potential use-after-free.
Solution 1: Use Option<T> for all slots. This approach stores Option<T> in the array, allowing you to take() values, leaving None behind. Pros: Completely safe, no unsafe code blocks required, clear semantics. Cons: Memory overhead of the discriminant (often 1 byte per element padded to word size), cache inefficiency, and requires initializing all slots to Some(value) even if never used.
Solution 2: Employ ManuallyDrop for the array. Wrap the internal [T; N] in ManuallyDrop<[T; N]>. When yielding, read the value and increment a counter. In the iterator's Drop, manually drop only the remaining range using ptr::drop_in_place. Pros: Zero overhead, identical memory layout to raw T, allows direct memory manipulation. Cons: Requires unsafe code, complex invariant maintenance regarding which slots are initialized, risk of leaks if the manual drop logic is incorrect.
Solution 3: Use a bitwise validity mask. Maintain a separate bitset tracking which indices are live. Pros: No unsafe code if using safe abstractions for the bitset. Cons: Significant complexity, overhead of bit manipulation on every access, and cache-unfriendly access patterns.
Chosen Solution and Result: Solution 2 was selected to match std::array::IntoIter behavior. The iterator struct wraps the array in ManuallyDrop and tracks the current index. The next() method uses ptr::read to move elements out. The Drop implementation checks the index and calls ptr::drop_in_place on the remaining slice. This ensures that even if a panic occurs while dropping a previously-yielded element, the unwinding process drops only the untouched suffix, preventing both leaks and double-drops. The result is a zero-cost abstraction that maintains memory safety invariants even in the presence of panicking destructors.
How does ManuallyDrop interact with the Copy trait, and why can this lead to subtle bugs when implementing iterators for Copy types?
ManuallyDrop<T> implements Copy if and only if T: Copy. When iterating over an array of Copy types wrapped in ManuallyDrop, using ptr::read or simple assignment creates bitwise copies rather than moves. Candidates often assume that ManuallyDrop prevents all forms of duplication, but for Copy types, the compiler may implicitly copy the value when you intended to move it, leading to scenarios where the "moved" value is still considered live in the source location. This can mask double-drop issues during testing with integers but manifest as undefined behavior with non-Copy types. The correct approach is to treat ManuallyDrop contents as moved regardless of Copy bounds, or to use ManuallyDrop::into_inner followed by explicit replacement.
Why is it insufficient to simply call mem::forget on the iterator if a panic occurs during iteration, rather than implementing a custom Drop that handles partial consumption?
mem::forget consumes the iterator without dropping it, which indeed prevents the double-drop of already-moved elements. However, it also leaks all remaining elements that have not yet been yielded, violating the resource management guarantees expected of Rust collections. The Drop trait exists precisely to ensure cleanup during unwinding; relying on mem::forget in error paths transforms a safety issue into a resource leak. The proper pattern uses ManuallyDrop to disable automatic destruction of the storage, then manually drops only the unyielded elements in the Drop implementation, ensuring no leaks and no double-drops.
What is the distinction between using ptr::read to move out of a ManuallyDrop<T> slot versus using ManuallyDrop::into_inner, and when is each appropriate in iterator implementation?
ptr::read performs a bitwise copy of the value and leaves the source memory unchanged (still containing a valid T), while ManuallyDrop::into_inner consumes the ManuallyDrop wrapper itself to extract the value. In iterator implementation, ptr::read is used when you need to leave the ManuallyDrop shell in place (e.g., in an array of ManuallyDrop<T>) so that the remaining slots can still be iterated and potentially dropped later. into_inner is appropriate when you are consuming the entire ManuallyDrop value at once and will not need to track partial state. Using into_inner on individual elements of an array would require re-wrapping or complex pointer arithmetic, whereas ptr::read allows treating the array as a raw buffer of potentially-uninitialized data.