kernel/alloc/
kvec.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Implementation of [`Vec`].
4
5// May not be needed in Rust 1.87.0 (pending beta backport).
6#![allow(clippy::ptr_eq)]
7
8use super::{
9    allocator::{KVmalloc, Kmalloc, Vmalloc},
10    layout::ArrayLayout,
11    AllocError, Allocator, Box, Flags,
12};
13use core::{
14    fmt,
15    marker::PhantomData,
16    mem::{ManuallyDrop, MaybeUninit},
17    ops::Deref,
18    ops::DerefMut,
19    ops::Index,
20    ops::IndexMut,
21    ptr,
22    ptr::NonNull,
23    slice,
24    slice::SliceIndex,
25};
26
27/// Create a [`KVec`] containing the arguments.
28///
29/// New memory is allocated with `GFP_KERNEL`.
30///
31/// # Examples
32///
33/// ```
34/// let mut v = kernel::kvec![];
35/// v.push(1, GFP_KERNEL)?;
36/// assert_eq!(v, [1]);
37///
38/// let mut v = kernel::kvec![1; 3]?;
39/// v.push(4, GFP_KERNEL)?;
40/// assert_eq!(v, [1, 1, 1, 4]);
41///
42/// let mut v = kernel::kvec![1, 2, 3]?;
43/// v.push(4, GFP_KERNEL)?;
44/// assert_eq!(v, [1, 2, 3, 4]);
45///
46/// # Ok::<(), Error>(())
47/// ```
48#[macro_export]
49macro_rules! kvec {
50    () => (
51        $crate::alloc::KVec::new()
52    );
53    ($elem:expr; $n:expr) => (
54        $crate::alloc::KVec::from_elem($elem, $n, GFP_KERNEL)
55    );
56    ($($x:expr),+ $(,)?) => (
57        match $crate::alloc::KBox::new_uninit(GFP_KERNEL) {
58            Ok(b) => Ok($crate::alloc::KVec::from($crate::alloc::KBox::write(b, [$($x),+]))),
59            Err(e) => Err(e),
60        }
61    );
62}
63
64/// The kernel's [`Vec`] type.
65///
66/// A contiguous growable array type with contents allocated with the kernel's allocators (e.g.
67/// [`Kmalloc`], [`Vmalloc`] or [`KVmalloc`]), written `Vec<T, A>`.
68///
69/// For non-zero-sized values, a [`Vec`] will use the given allocator `A` for its allocation. For
70/// the most common allocators the type aliases [`KVec`], [`VVec`] and [`KVVec`] exist.
71///
72/// For zero-sized types the [`Vec`]'s pointer must be `dangling_mut::<T>`; no memory is allocated.
73///
74/// Generally, [`Vec`] consists of a pointer that represents the vector's backing buffer, the
75/// capacity of the vector (the number of elements that currently fit into the vector), its length
76/// (the number of elements that are currently stored in the vector) and the `Allocator` type used
77/// to allocate (and free) the backing buffer.
78///
79/// A [`Vec`] can be deconstructed into and (re-)constructed from its previously named raw parts
80/// and manually modified.
81///
82/// [`Vec`]'s backing buffer gets, if required, automatically increased (re-allocated) when elements
83/// are added to the vector.
84///
85/// # Invariants
86///
87/// - `self.ptr` is always properly aligned and either points to memory allocated with `A` or, for
88///   zero-sized types, is a dangling, well aligned pointer.
89///
90/// - `self.len` always represents the exact number of elements stored in the vector.
91///
92/// - `self.layout` represents the absolute number of elements that can be stored within the vector
93///   without re-allocation. For ZSTs `self.layout`'s capacity is zero. However, it is legal for the
94///   backing buffer to be larger than `layout`.
95///
96/// - The `Allocator` type `A` of the vector is the exact same `Allocator` type the backing buffer
97///   was allocated with (and must be freed with).
98pub struct Vec<T, A: Allocator> {
99    ptr: NonNull<T>,
100    /// Represents the actual buffer size as `cap` times `size_of::<T>` bytes.
101    ///
102    /// Note: This isn't quite the same as `Self::capacity`, which in contrast returns the number of
103    /// elements we can still store without reallocating.
104    layout: ArrayLayout<T>,
105    len: usize,
106    _p: PhantomData<A>,
107}
108
109/// Type alias for [`Vec`] with a [`Kmalloc`] allocator.
110///
111/// # Examples
112///
113/// ```
114/// let mut v = KVec::new();
115/// v.push(1, GFP_KERNEL)?;
116/// assert_eq!(&v, &[1]);
117///
118/// # Ok::<(), Error>(())
119/// ```
120pub type KVec<T> = Vec<T, Kmalloc>;
121
122/// Type alias for [`Vec`] with a [`Vmalloc`] allocator.
123///
124/// # Examples
125///
126/// ```
127/// let mut v = VVec::new();
128/// v.push(1, GFP_KERNEL)?;
129/// assert_eq!(&v, &[1]);
130///
131/// # Ok::<(), Error>(())
132/// ```
133pub type VVec<T> = Vec<T, Vmalloc>;
134
135/// Type alias for [`Vec`] with a [`KVmalloc`] allocator.
136///
137/// # Examples
138///
139/// ```
140/// let mut v = KVVec::new();
141/// v.push(1, GFP_KERNEL)?;
142/// assert_eq!(&v, &[1]);
143///
144/// # Ok::<(), Error>(())
145/// ```
146pub type KVVec<T> = Vec<T, KVmalloc>;
147
148// SAFETY: `Vec` is `Send` if `T` is `Send` because `Vec` owns its elements.
149unsafe impl<T, A> Send for Vec<T, A>
150where
151    T: Send,
152    A: Allocator,
153{
154}
155
156// SAFETY: `Vec` is `Sync` if `T` is `Sync` because `Vec` owns its elements.
157unsafe impl<T, A> Sync for Vec<T, A>
158where
159    T: Sync,
160    A: Allocator,
161{
162}
163
164impl<T, A> Vec<T, A>
165where
166    A: Allocator,
167{
168    #[inline]
169    const fn is_zst() -> bool {
170        core::mem::size_of::<T>() == 0
171    }
172
173    /// Returns the number of elements that can be stored within the vector without allocating
174    /// additional memory.
175    pub fn capacity(&self) -> usize {
176        if const { Self::is_zst() } {
177            usize::MAX
178        } else {
179            self.layout.len()
180        }
181    }
182
183    /// Returns the number of elements stored within the vector.
184    #[inline]
185    pub fn len(&self) -> usize {
186        self.len
187    }
188
189    /// Forcefully sets `self.len` to `new_len`.
190    ///
191    /// # Safety
192    ///
193    /// - `new_len` must be less than or equal to [`Self::capacity`].
194    /// - If `new_len` is greater than `self.len`, all elements within the interval
195    ///   [`self.len`,`new_len`) must be initialized.
196    #[inline]
197    pub unsafe fn set_len(&mut self, new_len: usize) {
198        debug_assert!(new_len <= self.capacity());
199
200        // INVARIANT: By the safety requirements of this method `new_len` represents the exact
201        // number of elements stored within `self`.
202        self.len = new_len;
203    }
204
205    /// Returns a slice of the entire vector.
206    #[inline]
207    pub fn as_slice(&self) -> &[T] {
208        self
209    }
210
211    /// Returns a mutable slice of the entire vector.
212    #[inline]
213    pub fn as_mut_slice(&mut self) -> &mut [T] {
214        self
215    }
216
217    /// Returns a mutable raw pointer to the vector's backing buffer, or, if `T` is a ZST, a
218    /// dangling raw pointer.
219    #[inline]
220    pub fn as_mut_ptr(&mut self) -> *mut T {
221        self.ptr.as_ptr()
222    }
223
224    /// Returns a raw pointer to the vector's backing buffer, or, if `T` is a ZST, a dangling raw
225    /// pointer.
226    #[inline]
227    pub fn as_ptr(&self) -> *const T {
228        self.ptr.as_ptr()
229    }
230
231    /// Returns `true` if the vector contains no elements, `false` otherwise.
232    ///
233    /// # Examples
234    ///
235    /// ```
236    /// let mut v = KVec::new();
237    /// assert!(v.is_empty());
238    ///
239    /// v.push(1, GFP_KERNEL);
240    /// assert!(!v.is_empty());
241    /// ```
242    #[inline]
243    pub fn is_empty(&self) -> bool {
244        self.len() == 0
245    }
246
247    /// Creates a new, empty `Vec<T, A>`.
248    ///
249    /// This method does not allocate by itself.
250    #[inline]
251    pub const fn new() -> Self {
252        // INVARIANT: Since this is a new, empty `Vec` with no backing memory yet,
253        // - `ptr` is a properly aligned dangling pointer for type `T`,
254        // - `layout` is an empty `ArrayLayout` (zero capacity)
255        // - `len` is zero, since no elements can be or have been stored,
256        // - `A` is always valid.
257        Self {
258            ptr: NonNull::dangling(),
259            layout: ArrayLayout::empty(),
260            len: 0,
261            _p: PhantomData::<A>,
262        }
263    }
264
265    /// Returns a slice of `MaybeUninit<T>` for the remaining spare capacity of the vector.
266    pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {
267        // SAFETY:
268        // - `self.len` is smaller than `self.capacity` and hence, the resulting pointer is
269        //   guaranteed to be part of the same allocated object.
270        // - `self.len` can not overflow `isize`.
271        let ptr = unsafe { self.as_mut_ptr().add(self.len) } as *mut MaybeUninit<T>;
272
273        // SAFETY: The memory between `self.len` and `self.capacity` is guaranteed to be allocated
274        // and valid, but uninitialized.
275        unsafe { slice::from_raw_parts_mut(ptr, self.capacity() - self.len) }
276    }
277
278    /// Appends an element to the back of the [`Vec`] instance.
279    ///
280    /// # Examples
281    ///
282    /// ```
283    /// let mut v = KVec::new();
284    /// v.push(1, GFP_KERNEL)?;
285    /// assert_eq!(&v, &[1]);
286    ///
287    /// v.push(2, GFP_KERNEL)?;
288    /// assert_eq!(&v, &[1, 2]);
289    /// # Ok::<(), Error>(())
290    /// ```
291    pub fn push(&mut self, v: T, flags: Flags) -> Result<(), AllocError> {
292        self.reserve(1, flags)?;
293
294        // SAFETY:
295        // - `self.len` is smaller than `self.capacity` and hence, the resulting pointer is
296        //   guaranteed to be part of the same allocated object.
297        // - `self.len` can not overflow `isize`.
298        let ptr = unsafe { self.as_mut_ptr().add(self.len) };
299
300        // SAFETY:
301        // - `ptr` is properly aligned and valid for writes.
302        unsafe { core::ptr::write(ptr, v) };
303
304        // SAFETY: We just initialised the first spare entry, so it is safe to increase the length
305        // by 1. We also know that the new length is <= capacity because of the previous call to
306        // `reserve` above.
307        unsafe { self.set_len(self.len() + 1) };
308        Ok(())
309    }
310
311    /// Creates a new [`Vec`] instance with at least the given capacity.
312    ///
313    /// # Examples
314    ///
315    /// ```
316    /// let v = KVec::<u32>::with_capacity(20, GFP_KERNEL)?;
317    ///
318    /// assert!(v.capacity() >= 20);
319    /// # Ok::<(), Error>(())
320    /// ```
321    pub fn with_capacity(capacity: usize, flags: Flags) -> Result<Self, AllocError> {
322        let mut v = Vec::new();
323
324        v.reserve(capacity, flags)?;
325
326        Ok(v)
327    }
328
329    /// Creates a `Vec<T, A>` from a pointer, a length and a capacity using the allocator `A`.
330    ///
331    /// # Examples
332    ///
333    /// ```
334    /// let mut v = kernel::kvec![1, 2, 3]?;
335    /// v.reserve(1, GFP_KERNEL)?;
336    ///
337    /// let (mut ptr, mut len, cap) = v.into_raw_parts();
338    ///
339    /// // SAFETY: We've just reserved memory for another element.
340    /// unsafe { ptr.add(len).write(4) };
341    /// len += 1;
342    ///
343    /// // SAFETY: We only wrote an additional element at the end of the `KVec`'s buffer and
344    /// // correspondingly increased the length of the `KVec` by one. Otherwise, we construct it
345    /// // from the exact same raw parts.
346    /// let v = unsafe { KVec::from_raw_parts(ptr, len, cap) };
347    ///
348    /// assert_eq!(v, [1, 2, 3, 4]);
349    ///
350    /// # Ok::<(), Error>(())
351    /// ```
352    ///
353    /// # Safety
354    ///
355    /// If `T` is a ZST:
356    ///
357    /// - `ptr` must be a dangling, well aligned pointer.
358    ///
359    /// Otherwise:
360    ///
361    /// - `ptr` must have been allocated with the allocator `A`.
362    /// - `ptr` must satisfy or exceed the alignment requirements of `T`.
363    /// - `ptr` must point to memory with a size of at least `size_of::<T>() * capacity` bytes.
364    /// - The allocated size in bytes must not be larger than `isize::MAX`.
365    /// - `length` must be less than or equal to `capacity`.
366    /// - The first `length` elements must be initialized values of type `T`.
367    ///
368    /// It is also valid to create an empty `Vec` passing a dangling pointer for `ptr` and zero for
369    /// `cap` and `len`.
370    pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self {
371        let layout = if Self::is_zst() {
372            ArrayLayout::empty()
373        } else {
374            // SAFETY: By the safety requirements of this function, `capacity * size_of::<T>()` is
375            // smaller than `isize::MAX`.
376            unsafe { ArrayLayout::new_unchecked(capacity) }
377        };
378
379        // INVARIANT: For ZSTs, we store an empty `ArrayLayout`, all other type invariants are
380        // covered by the safety requirements of this function.
381        Self {
382            // SAFETY: By the safety requirements, `ptr` is either dangling or pointing to a valid
383            // memory allocation, allocated with `A`.
384            ptr: unsafe { NonNull::new_unchecked(ptr) },
385            layout,
386            len: length,
387            _p: PhantomData::<A>,
388        }
389    }
390
391    /// Consumes the `Vec<T, A>` and returns its raw components `pointer`, `length` and `capacity`.
392    ///
393    /// This will not run the destructor of the contained elements and for non-ZSTs the allocation
394    /// will stay alive indefinitely. Use [`Vec::from_raw_parts`] to recover the [`Vec`], drop the
395    /// elements and free the allocation, if any.
396    pub fn into_raw_parts(self) -> (*mut T, usize, usize) {
397        let mut me = ManuallyDrop::new(self);
398        let len = me.len();
399        let capacity = me.capacity();
400        let ptr = me.as_mut_ptr();
401        (ptr, len, capacity)
402    }
403
404    /// Ensures that the capacity exceeds the length by at least `additional` elements.
405    ///
406    /// # Examples
407    ///
408    /// ```
409    /// let mut v = KVec::new();
410    /// v.push(1, GFP_KERNEL)?;
411    ///
412    /// v.reserve(10, GFP_KERNEL)?;
413    /// let cap = v.capacity();
414    /// assert!(cap >= 10);
415    ///
416    /// v.reserve(10, GFP_KERNEL)?;
417    /// let new_cap = v.capacity();
418    /// assert_eq!(new_cap, cap);
419    ///
420    /// # Ok::<(), Error>(())
421    /// ```
422    pub fn reserve(&mut self, additional: usize, flags: Flags) -> Result<(), AllocError> {
423        let len = self.len();
424        let cap = self.capacity();
425
426        if cap - len >= additional {
427            return Ok(());
428        }
429
430        if Self::is_zst() {
431            // The capacity is already `usize::MAX` for ZSTs, we can't go higher.
432            return Err(AllocError);
433        }
434
435        // We know that `cap <= isize::MAX` because of the type invariants of `Self`. So the
436        // multiplication by two won't overflow.
437        let new_cap = core::cmp::max(cap * 2, len.checked_add(additional).ok_or(AllocError)?);
438        let layout = ArrayLayout::new(new_cap).map_err(|_| AllocError)?;
439
440        // SAFETY:
441        // - `ptr` is valid because it's either `None` or comes from a previous call to
442        //   `A::realloc`.
443        // - `self.layout` matches the `ArrayLayout` of the preceding allocation.
444        let ptr = unsafe {
445            A::realloc(
446                Some(self.ptr.cast()),
447                layout.into(),
448                self.layout.into(),
449                flags,
450            )?
451        };
452
453        // INVARIANT:
454        // - `layout` is some `ArrayLayout::<T>`,
455        // - `ptr` has been created by `A::realloc` from `layout`.
456        self.ptr = ptr.cast();
457        self.layout = layout;
458
459        Ok(())
460    }
461}
462
463impl<T: Clone, A: Allocator> Vec<T, A> {
464    /// Extend the vector by `n` clones of `value`.
465    pub fn extend_with(&mut self, n: usize, value: T, flags: Flags) -> Result<(), AllocError> {
466        if n == 0 {
467            return Ok(());
468        }
469
470        self.reserve(n, flags)?;
471
472        let spare = self.spare_capacity_mut();
473
474        for item in spare.iter_mut().take(n - 1) {
475            item.write(value.clone());
476        }
477
478        // We can write the last element directly without cloning needlessly.
479        spare[n - 1].write(value);
480
481        // SAFETY:
482        // - `self.len() + n < self.capacity()` due to the call to reserve above,
483        // - the loop and the line above initialized the next `n` elements.
484        unsafe { self.set_len(self.len() + n) };
485
486        Ok(())
487    }
488
489    /// Pushes clones of the elements of slice into the [`Vec`] instance.
490    ///
491    /// # Examples
492    ///
493    /// ```
494    /// let mut v = KVec::new();
495    /// v.push(1, GFP_KERNEL)?;
496    ///
497    /// v.extend_from_slice(&[20, 30, 40], GFP_KERNEL)?;
498    /// assert_eq!(&v, &[1, 20, 30, 40]);
499    ///
500    /// v.extend_from_slice(&[50, 60], GFP_KERNEL)?;
501    /// assert_eq!(&v, &[1, 20, 30, 40, 50, 60]);
502    /// # Ok::<(), Error>(())
503    /// ```
504    pub fn extend_from_slice(&mut self, other: &[T], flags: Flags) -> Result<(), AllocError> {
505        self.reserve(other.len(), flags)?;
506        for (slot, item) in core::iter::zip(self.spare_capacity_mut(), other) {
507            slot.write(item.clone());
508        }
509
510        // SAFETY:
511        // - `other.len()` spare entries have just been initialized, so it is safe to increase
512        //   the length by the same number.
513        // - `self.len() + other.len() <= self.capacity()` is guaranteed by the preceding `reserve`
514        //   call.
515        unsafe { self.set_len(self.len() + other.len()) };
516        Ok(())
517    }
518
519    /// Create a new `Vec<T, A>` and extend it by `n` clones of `value`.
520    pub fn from_elem(value: T, n: usize, flags: Flags) -> Result<Self, AllocError> {
521        let mut v = Self::with_capacity(n, flags)?;
522
523        v.extend_with(n, value, flags)?;
524
525        Ok(v)
526    }
527}
528
529impl<T, A> Drop for Vec<T, A>
530where
531    A: Allocator,
532{
533    fn drop(&mut self) {
534        // SAFETY: `self.as_mut_ptr` is guaranteed to be valid by the type invariant.
535        unsafe {
536            ptr::drop_in_place(core::ptr::slice_from_raw_parts_mut(
537                self.as_mut_ptr(),
538                self.len,
539            ))
540        };
541
542        // SAFETY:
543        // - `self.ptr` was previously allocated with `A`.
544        // - `self.layout` matches the `ArrayLayout` of the preceding allocation.
545        unsafe { A::free(self.ptr.cast(), self.layout.into()) };
546    }
547}
548
549impl<T, A, const N: usize> From<Box<[T; N], A>> for Vec<T, A>
550where
551    A: Allocator,
552{
553    fn from(b: Box<[T; N], A>) -> Vec<T, A> {
554        let len = b.len();
555        let ptr = Box::into_raw(b);
556
557        // SAFETY:
558        // - `b` has been allocated with `A`,
559        // - `ptr` fulfills the alignment requirements for `T`,
560        // - `ptr` points to memory with at least a size of `size_of::<T>() * len`,
561        // - all elements within `b` are initialized values of `T`,
562        // - `len` does not exceed `isize::MAX`.
563        unsafe { Vec::from_raw_parts(ptr as _, len, len) }
564    }
565}
566
567impl<T> Default for KVec<T> {
568    #[inline]
569    fn default() -> Self {
570        Self::new()
571    }
572}
573
574impl<T: fmt::Debug, A: Allocator> fmt::Debug for Vec<T, A> {
575    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
576        fmt::Debug::fmt(&**self, f)
577    }
578}
579
580impl<T, A> Deref for Vec<T, A>
581where
582    A: Allocator,
583{
584    type Target = [T];
585
586    #[inline]
587    fn deref(&self) -> &[T] {
588        // SAFETY: The memory behind `self.as_ptr()` is guaranteed to contain `self.len`
589        // initialized elements of type `T`.
590        unsafe { slice::from_raw_parts(self.as_ptr(), self.len) }
591    }
592}
593
594impl<T, A> DerefMut for Vec<T, A>
595where
596    A: Allocator,
597{
598    #[inline]
599    fn deref_mut(&mut self) -> &mut [T] {
600        // SAFETY: The memory behind `self.as_ptr()` is guaranteed to contain `self.len`
601        // initialized elements of type `T`.
602        unsafe { slice::from_raw_parts_mut(self.as_mut_ptr(), self.len) }
603    }
604}
605
606impl<T: Eq, A> Eq for Vec<T, A> where A: Allocator {}
607
608impl<T, I: SliceIndex<[T]>, A> Index<I> for Vec<T, A>
609where
610    A: Allocator,
611{
612    type Output = I::Output;
613
614    #[inline]
615    fn index(&self, index: I) -> &Self::Output {
616        Index::index(&**self, index)
617    }
618}
619
620impl<T, I: SliceIndex<[T]>, A> IndexMut<I> for Vec<T, A>
621where
622    A: Allocator,
623{
624    #[inline]
625    fn index_mut(&mut self, index: I) -> &mut Self::Output {
626        IndexMut::index_mut(&mut **self, index)
627    }
628}
629
630macro_rules! impl_slice_eq {
631    ($([$($vars:tt)*] $lhs:ty, $rhs:ty,)*) => {
632        $(
633            impl<T, U, $($vars)*> PartialEq<$rhs> for $lhs
634            where
635                T: PartialEq<U>,
636            {
637                #[inline]
638                fn eq(&self, other: &$rhs) -> bool { self[..] == other[..] }
639            }
640        )*
641    }
642}
643
644impl_slice_eq! {
645    [A1: Allocator, A2: Allocator] Vec<T, A1>, Vec<U, A2>,
646    [A: Allocator] Vec<T, A>, &[U],
647    [A: Allocator] Vec<T, A>, &mut [U],
648    [A: Allocator] &[T], Vec<U, A>,
649    [A: Allocator] &mut [T], Vec<U, A>,
650    [A: Allocator] Vec<T, A>, [U],
651    [A: Allocator] [T], Vec<U, A>,
652    [A: Allocator, const N: usize] Vec<T, A>, [U; N],
653    [A: Allocator, const N: usize] Vec<T, A>, &[U; N],
654}
655
656impl<'a, T, A> IntoIterator for &'a Vec<T, A>
657where
658    A: Allocator,
659{
660    type Item = &'a T;
661    type IntoIter = slice::Iter<'a, T>;
662
663    fn into_iter(self) -> Self::IntoIter {
664        self.iter()
665    }
666}
667
668impl<'a, T, A: Allocator> IntoIterator for &'a mut Vec<T, A>
669where
670    A: Allocator,
671{
672    type Item = &'a mut T;
673    type IntoIter = slice::IterMut<'a, T>;
674
675    fn into_iter(self) -> Self::IntoIter {
676        self.iter_mut()
677    }
678}
679
680/// An [`Iterator`] implementation for [`Vec`] that moves elements out of a vector.
681///
682/// This structure is created by the [`Vec::into_iter`] method on [`Vec`] (provided by the
683/// [`IntoIterator`] trait).
684///
685/// # Examples
686///
687/// ```
688/// let v = kernel::kvec![0, 1, 2]?;
689/// let iter = v.into_iter();
690///
691/// # Ok::<(), Error>(())
692/// ```
693pub struct IntoIter<T, A: Allocator> {
694    ptr: *mut T,
695    buf: NonNull<T>,
696    len: usize,
697    layout: ArrayLayout<T>,
698    _p: PhantomData<A>,
699}
700
701impl<T, A> IntoIter<T, A>
702where
703    A: Allocator,
704{
705    fn into_raw_parts(self) -> (*mut T, NonNull<T>, usize, usize) {
706        let me = ManuallyDrop::new(self);
707        let ptr = me.ptr;
708        let buf = me.buf;
709        let len = me.len;
710        let cap = me.layout.len();
711        (ptr, buf, len, cap)
712    }
713
714    /// Same as `Iterator::collect` but specialized for `Vec`'s `IntoIter`.
715    ///
716    /// # Examples
717    ///
718    /// ```
719    /// let v = kernel::kvec![1, 2, 3]?;
720    /// let mut it = v.into_iter();
721    ///
722    /// assert_eq!(it.next(), Some(1));
723    ///
724    /// let v = it.collect(GFP_KERNEL);
725    /// assert_eq!(v, [2, 3]);
726    ///
727    /// # Ok::<(), Error>(())
728    /// ```
729    ///
730    /// # Implementation details
731    ///
732    /// Currently, we can't implement `FromIterator`. There are a couple of issues with this trait
733    /// in the kernel, namely:
734    ///
735    /// - Rust's specialization feature is unstable. This prevents us to optimize for the special
736    ///   case where `I::IntoIter` equals `Vec`'s `IntoIter` type.
737    /// - We also can't use `I::IntoIter`'s type ID either to work around this, since `FromIterator`
738    ///   doesn't require this type to be `'static`.
739    /// - `FromIterator::from_iter` does return `Self` instead of `Result<Self, AllocError>`, hence
740    ///   we can't properly handle allocation failures.
741    /// - Neither `Iterator::collect` nor `FromIterator::from_iter` can handle additional allocation
742    ///   flags.
743    ///
744    /// Instead, provide `IntoIter::collect`, such that we can at least convert a `IntoIter` into a
745    /// `Vec` again.
746    ///
747    /// Note that `IntoIter::collect` doesn't require `Flags`, since it re-uses the existing backing
748    /// buffer. However, this backing buffer may be shrunk to the actual count of elements.
749    pub fn collect(self, flags: Flags) -> Vec<T, A> {
750        let old_layout = self.layout;
751        let (mut ptr, buf, len, mut cap) = self.into_raw_parts();
752        let has_advanced = ptr != buf.as_ptr();
753
754        if has_advanced {
755            // Copy the contents we have advanced to at the beginning of the buffer.
756            //
757            // SAFETY:
758            // - `ptr` is valid for reads of `len * size_of::<T>()` bytes,
759            // - `buf.as_ptr()` is valid for writes of `len * size_of::<T>()` bytes,
760            // - `ptr` and `buf.as_ptr()` are not be subject to aliasing restrictions relative to
761            //   each other,
762            // - both `ptr` and `buf.ptr()` are properly aligned.
763            unsafe { ptr::copy(ptr, buf.as_ptr(), len) };
764            ptr = buf.as_ptr();
765
766            // SAFETY: `len` is guaranteed to be smaller than `self.layout.len()`.
767            let layout = unsafe { ArrayLayout::<T>::new_unchecked(len) };
768
769            // SAFETY: `buf` points to the start of the backing buffer and `len` is guaranteed to be
770            // smaller than `cap`. Depending on `alloc` this operation may shrink the buffer or leaves
771            // it as it is.
772            ptr = match unsafe {
773                A::realloc(Some(buf.cast()), layout.into(), old_layout.into(), flags)
774            } {
775                // If we fail to shrink, which likely can't even happen, continue with the existing
776                // buffer.
777                Err(_) => ptr,
778                Ok(ptr) => {
779                    cap = len;
780                    ptr.as_ptr().cast()
781                }
782            };
783        }
784
785        // SAFETY: If the iterator has been advanced, the advanced elements have been copied to
786        // the beginning of the buffer and `len` has been adjusted accordingly.
787        //
788        // - `ptr` is guaranteed to point to the start of the backing buffer.
789        // - `cap` is either the original capacity or, after shrinking the buffer, equal to `len`.
790        // - `alloc` is guaranteed to be unchanged since `into_iter` has been called on the original
791        //   `Vec`.
792        unsafe { Vec::from_raw_parts(ptr, len, cap) }
793    }
794}
795
796impl<T, A> Iterator for IntoIter<T, A>
797where
798    A: Allocator,
799{
800    type Item = T;
801
802    /// # Examples
803    ///
804    /// ```
805    /// let v = kernel::kvec![1, 2, 3]?;
806    /// let mut it = v.into_iter();
807    ///
808    /// assert_eq!(it.next(), Some(1));
809    /// assert_eq!(it.next(), Some(2));
810    /// assert_eq!(it.next(), Some(3));
811    /// assert_eq!(it.next(), None);
812    ///
813    /// # Ok::<(), Error>(())
814    /// ```
815    fn next(&mut self) -> Option<T> {
816        if self.len == 0 {
817            return None;
818        }
819
820        let current = self.ptr;
821
822        // SAFETY: We can't overflow; decreasing `self.len` by one every time we advance `self.ptr`
823        // by one guarantees that.
824        unsafe { self.ptr = self.ptr.add(1) };
825
826        self.len -= 1;
827
828        // SAFETY: `current` is guaranteed to point at a valid element within the buffer.
829        Some(unsafe { current.read() })
830    }
831
832    /// # Examples
833    ///
834    /// ```
835    /// let v: KVec<u32> = kernel::kvec![1, 2, 3]?;
836    /// let mut iter = v.into_iter();
837    /// let size = iter.size_hint().0;
838    ///
839    /// iter.next();
840    /// assert_eq!(iter.size_hint().0, size - 1);
841    ///
842    /// iter.next();
843    /// assert_eq!(iter.size_hint().0, size - 2);
844    ///
845    /// iter.next();
846    /// assert_eq!(iter.size_hint().0, size - 3);
847    ///
848    /// # Ok::<(), Error>(())
849    /// ```
850    fn size_hint(&self) -> (usize, Option<usize>) {
851        (self.len, Some(self.len))
852    }
853}
854
855impl<T, A> Drop for IntoIter<T, A>
856where
857    A: Allocator,
858{
859    fn drop(&mut self) {
860        // SAFETY: `self.ptr` is guaranteed to be valid by the type invariant.
861        unsafe { ptr::drop_in_place(ptr::slice_from_raw_parts_mut(self.ptr, self.len)) };
862
863        // SAFETY:
864        // - `self.buf` was previously allocated with `A`.
865        // - `self.layout` matches the `ArrayLayout` of the preceding allocation.
866        unsafe { A::free(self.buf.cast(), self.layout.into()) };
867    }
868}
869
870impl<T, A> IntoIterator for Vec<T, A>
871where
872    A: Allocator,
873{
874    type Item = T;
875    type IntoIter = IntoIter<T, A>;
876
877    /// Consumes the `Vec<T, A>` and creates an `Iterator`, which moves each value out of the
878    /// vector (from start to end).
879    ///
880    /// # Examples
881    ///
882    /// ```
883    /// let v = kernel::kvec![1, 2]?;
884    /// let mut v_iter = v.into_iter();
885    ///
886    /// let first_element: Option<u32> = v_iter.next();
887    ///
888    /// assert_eq!(first_element, Some(1));
889    /// assert_eq!(v_iter.next(), Some(2));
890    /// assert_eq!(v_iter.next(), None);
891    ///
892    /// # Ok::<(), Error>(())
893    /// ```
894    ///
895    /// ```
896    /// let v = kernel::kvec![];
897    /// let mut v_iter = v.into_iter();
898    ///
899    /// let first_element: Option<u32> = v_iter.next();
900    ///
901    /// assert_eq!(first_element, None);
902    ///
903    /// # Ok::<(), Error>(())
904    /// ```
905    #[inline]
906    fn into_iter(self) -> Self::IntoIter {
907        let buf = self.ptr;
908        let layout = self.layout;
909        let (ptr, len, _) = self.into_raw_parts();
910
911        IntoIter {
912            ptr,
913            buf,
914            len,
915            layout,
916            _p: PhantomData::<A>,
917        }
918    }
919}