Additional methods for Vec
Subsystems (2)
Alice Ryhl
maintainerv2 cover Additional methods for Vec
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
I'm not sure what we concluded on the set_len / dec_len changes, so I don't depend on that series for now.
This series is based on top of Vec::truncate from
https://lore.kernel.org/rust-for-linux/[email protected]/
---
Changes in v2:
- Add two more methods that I needed.
- Introduce some uses of set_len.
- Add example to retain.
- Simplify pop.
- Adjust 11 to 10 in push_within_capacity example.
- Link to v1: https://lore.kernel.org/r/[email protected]
---
Alice Ryhl (7):
rust: alloc: add Vec::clear
rust: alloc: add Vec::pop
rust: alloc: add Vec::push_within_capacity
rust: alloc: add Vec::drain_all
rust: alloc: add Vec::retain
rust: alloc: add Vec::remove
rust: alloc: add Vec::insert_within_capacity
rust/kernel/alloc/kvec.rs | 202 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+)
---
base-commit: a337a03281efc4553191b432d757d4c04884bf4c
change-id: 20250320-vec-methods-adfa41e55311
Best regards,
Signature · 1 line
Alice Ryhl <[email protected]>
Alice Ryhl
maintainerPATCH v2 1/7 rust: alloc: add Vec::clear
Our custom Vec type is missing the stdlib method clear, thus add it. It will be used in the miscdevice sample.
--- rust/kernel/alloc/kvec.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
rust/kernel/alloc/kvec.rs +20 -0
@@ -395,6 +395,26 @@ pub fn into_raw_parts(self) -> (*mut T, usize, usize) { (ptr, len, capacity) } +/// Clears the vector, removing all values. +/// +/// Note that this method has no effect on the allocated capacity +/// of the vector. +/// +/// # Examples +/// +/// ``` +/// let mut v = kernel::kvec![1, 2, 3]?; +/// +/// v.clear(); +/// +/// assert!(v.is_empty()); +/// # Ok::<(), Error>(()) +/// ``` +#[inline] +pub fn clear (&mut self) { + self.truncate (0 ); + } +/// Ensures that the capacity exceeds the length by at least `additional` elements. /// /// # Examples
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 2/7 rust: alloc: add Vec::pop
In reply to Alice RyhlThis introduces a basic method that our custom Vec is missing. I expect that it will be used in many places, but at the time of writing, Rust Binder has six calls to Vec::pop.
--- rust/kernel/alloc/kvec.rs | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+)
rust/kernel/alloc/kvec.rs +29 -0
@@ -302,6 +302,35 @@ pub fn push(&mut self, v: T, flags: Flags) -> Result<(), AllocError> {Ok (()) } +/// Removes the last element from a vector and returns it, or `None` if it is empty. +/// +/// # Examples +/// +/// ``` +/// let mut v = KVec::new(); +/// v.push(1, GFP_KERNEL)?; +/// v.push(2, GFP_KERNEL)?; +/// assert_eq!(&v, &[1, 2]); +/// +/// assert_eq!(v.pop(), Some(2)); +/// assert_eq!(v.pop(), Some(1)); +/// assert_eq!(v.pop(), None); +/// # Ok::<(), Error>(()) +/// ``` +pub fn pop (&mut self) ->Option <T > { +let len_sub_1 = self.len.checked_sub (1 )?; + +// SAFETY: If the first `len` elements are valid, then the first `len - 1` elements are +// valid. + self.set_len (len_sub_1); + +// This invalidates a value in this vector's allocation, but the Vec invariants do not +// require it to be valid because `self.len <= len_sub_1`. +// SAFETY: Since `len_sub_1` is less than the value `self.len` had at the beginning of +// `pop`, this index holds a valid value. +Some (unsafe { self.as_mut_ptr ().add (len_sub_1).read () }) + } +/// Creates a new [`Vec`] instance with at least the given capacity. /// /// # Examples
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 3/7 rust: alloc: add Vec::push_within_capacity
In reply to Alice RyhlThis introduces a new method called push_within_capacity for appending to a vector without attempting to allocate if the capacity is full. Rust Binder will use this in various places to safely push to a vector while holding a spinlock.
The existing Vec::push method is reimplemented in terms of the new method.
--- rust/kernel/alloc/kvec.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+)
rust/kernel/alloc/kvec.rs +25 -0
@@ -284,6 +284,31 @@ pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {/// ``` pub fn push (&mut self, v:T , flags:Flags ) ->Result <(),AllocError > { self.reserve (1 , flags)?; +let err = self.push_within_capacity (v); +// SAFETY: The call to `reserve` was successful, so `push_within_capacity` cannot fail. +unsafe { err.unwrap_unchecked () }; +Ok (()) + } + +/// Appends an element to the back of the [`Vec`] instance. +/// +/// Fails if the vector does not have capacity for the new element. +/// +/// # Examples +/// +/// ``` +/// let mut v = KVec::with_capacity(10, GFP_KERNEL); +/// for i in 0..10 { +/// v.push_within_capacity(i).unwrap(); +/// } +/// +/// assert!(v.push_within_capacity(10).is_err()); +/// # Ok::<(), Error>(()) +/// ``` +pub fn push_within_capacity (&mut self, v:T ) ->Result <(),T > { +if self.len () >= self.capacity () { +return Err (v); + }// SAFETY: // - `self.len` is smaller than `self.capacity` and hence, the resulting pointer is
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 4/7 rust: alloc: add Vec::drain_all
In reply to Alice RyhlThis is like the stdlib method drain, except that it's hard-coded to use the entire vector's range. Rust Binder uses it in the range allocator to take ownership of everything in a vector in a case where reusing the vector is desirable.
Implementing DrainAll in terms of slice::IterMut lets us reuse some nice optimizations in core for the case where T is a ZST.
--- rust/kernel/alloc/kvec.rs | 57 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+)
rust/kernel/alloc/kvec.rs +57 -0
@@ -562,6 +562,30 @@ pub fn truncate(&mut self, len: usize) {// len, therefore we have exclusive access to [`new_len`, `old_len`) unsafe { ptr::drop_in_place (ptr) }; } + +/// Takes ownership of all items in this vector without consuming the allocation. +/// +/// # Examples +/// +/// ``` +/// let mut v = kernel::kvec![0, 1, 2, 3]?; +/// +/// for (i, j) in v.drain_all().enumerate() { +/// assert_eq!(i, j); +/// } +/// +/// assert!(v.capacity() >= 4); +/// ``` +pub fn drain_all (&mut self) ->DrainAll <'_,T > { +let len = self.len (); +// SAFETY: The first 0 elements are valid. + self.set_len (0 ); +// INVARIANT: The first `len` elements of the spare capacity are valid values, and as we +// just set the length to zero, we may transfer ownership to the `DrainAll` object. +DrainAll { + elements: self.spare_capacity_mut ()[..len].iter_mut (), + } + } }impl <T :Clone ,A :Allocator >Vec <T ,A > {
@@ -1047,3 +1071,36 @@ fn into_iter(self) -> Self::IntoIter { } } } + +/// An iterator that owns all items in a vector, but does not own its allocation. +/// +/// # Invariants +/// +/// Every `&mut MaybeUninit<T>` returned by the iterator contains a valid `T` owned by this +/// `DrainAll`. +pub struct DrainAll <'vec,T > { + elements: slice::IterMut <'vec,MaybeUninit <T >>, +} + +impl <'vec,T >Iterator for DrainAll <'vec,T > { +type Item =T ; + +fn next (&mut self) ->Option <T > { +let elem = self.elements.next ()?; +// SAFETY: By the type invariants, we may take ownership of the value in this +// `MaybeUninit<T>`. +Some (unsafe { elem.assume_init_read () }) + } + +fn size_hint (&self) -> (usize ,Option <usize >) { + self.elements.size_hint () + } +} + +impl <'vec,T >Drop for DrainAll <'vec,T > { +fn drop (&mut self) { +if core::mem::needs_drop ::<T >() { +while self.next ().is_some () {} + } + } +}
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 5/7 rust: alloc: add Vec::retain
In reply to Alice RyhlThis adds a common Vec method called retain that removes all elements that don't match a certain condition. Rust Binder uses it to find all processes that match a given pid.
The stdlib retain method takes &T rather than &mut T and has a separate retain_mut for the &mut T case. However, this is considered an API mistake that can't be fixed now due to backwards compatibility. There's no reason for us to repeat that mistake.
To verify the correctness of this implementation, you may run the following program in userspace:
fn retain<T>(vec: &mut Vec<T>, f: impl Fn(&T) -> bool) {
let mut num_kept = 0;
let mut next_to_check = 0;
while let Some(to_check) = vec.get_mut(next_to_check) {
if f(to_check) {
vec.swap(num_kept, next_to_check);
num_kept += 1;
}
next_to_check += 1;
}
vec.truncate(num_kept);
}
fn verify(c: &[bool]) {
let mut vec1: Vec<usize> = (0..c.len()).collect();
let mut vec2: Vec<usize> = (0..c.len()).collect();
vec1.retain(|i| c[*i]);
retain(&mut vec2, |i| c[*i]);
assert_eq!(vec1, vec2);
}
// Used to loop through all 2^n bit vectors.
fn add(value: &mut [bool]) -> bool {
let mut carry = true;
for v in value {
let new_v = carry != *v;
carry = carry && *v;
*v = new_v;
}
carry
}
fn main() {
for len in 0..10 {
let mut retain = vec![false; len];
while !add(&mut retain) {
verify(&retain);
}
}
println!("ok!");
}--- rust/kernel/alloc/kvec.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+)
rust/kernel/alloc/kvec.rs +22 -0
@@ -586,6 +586,28 @@ pub fn drain_all(&mut self) -> DrainAll<'_, T> { elements: self.spare_capacity_mut()[..len].iter_mut(), } } + +/// Removes all elements that don't match the provided closure. +/// +/// # Examples +/// +/// ``` +/// let mut v = kernel::kvec![1, 2, 3, 4]?; +/// v.retain(|i| i % 2 == 0); +/// assert_eq!(v, [2, 4]); +/// ``` +pub fn retain (&mut self,mut f:impl FnMut (&mut T ) ->bool ) { +let mut num_kept =0 ; +let mut next_to_check =0 ; +while let Some (to_check) = self.get_mut (next_to_check) { +if f (to_check) { + self.swap (num_kept, next_to_check); + num_kept +=1 ; + } + next_to_check +=1 ; + } + self.truncate (num_kept); + } }impl <T :Clone ,A :Allocator >Vec <T ,A > {
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 6/7 rust: alloc: add Vec::remove
In reply to Alice RyhlThis is needed by Rust Binder in the range allocator, and by upcoming GPU drivers during firmware initialization.
--- rust/kernel/alloc/kvec.rs | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+)
rust/kernel/alloc/kvec.rs +28 -0
@@ -356,6 +356,34 @@ pub fn pop(&mut self) -> Option<T> {Some (unsafe { self.as_mut_ptr ().add (len_sub_1).read () }) } +/// Removes the element at the given index. +/// +/// # Examples +/// +/// ``` +/// let mut v = kernel::kvec![1, 2, 3]?; +/// assert_eq!(v.remove(1), 2); +/// assert_eq!(v, [1, 3]); +/// # Ok::<(), Error>(()) +/// ``` +pub fn remove (&mut self, i:idx ) ->T { +// INVARIANT: This breaks the invariants by invalidating the value at index `i`, but we +// restore the invariants below. +// SAFETY: Since `&self[i]` did not result in a panic, the value at index `i` is valid. +let value =unsafe { ptr::read (&self[i]) }; + +// SAFETY: We checked that `i` is in-bounds. +let p =unsafe { self.as_mut_ptr ().add (i) }; +// INVARIANT: The invariants are still broken, but now the invalid value is the last +// element of the vector. +// SAFETY: `p.add(1).add(self.len - i - 1)` is `i+1+len-i-1 == len` elements after the +// beginning of the vector, so this is in-bounds of the vector. +unsafe { ptr::copy (p.add (1 ), p, self.len - i -1 ) }; +// INVARIANT: This restores the invariants since the invalid element no longer needs to be +// valid. + self.len = self.len -1 ; + } +/// Creates a new [`Vec`] instance with at least the given capacity. /// /// # Examples
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Alice Ryhl
maintainerPATCH v2 7/7 rust: alloc: add Vec::insert_within_capacity
In reply to Alice RyhlThis adds a variant of Vec::insert that does not allocate memory. This makes it safe to use this function while holding a spinlock. Rust Binder uses it for the range allocator fast path.
--- rust/kernel/alloc/kvec.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+)
rust/kernel/alloc/kvec.rs +21 -0
@@ -327,6 +327,27 @@ pub fn push_within_capacity(&mut self, v: T) -> Result<(), T> {Ok (()) } +pub fn insert_within_capacity (&mut self, index:usize , element:T ) ->Result <(),T > { +assert! (index <= self.len ()); + +if self.len () >= self.capacity () { +return Err (element); + } + +// SAFETY: This is in bounds since `index <= len < capacity`. +let p =unsafe { vec.as_mut_ptr ().add (index) }; +// INVARIANT: This breaks the Vec invariants by making `index` contain an invalid element, +// but we restore the invariants below. +// SAFETY: Both the src and dst ranges end no later than one element after the length. +// Since the length is less than the capacity, both ranges are in bounds of the allocation. +unsafe { ptr::copy (p, p.add (1 ), len - index) }; +// INVARIANT: This restores the Vec invariants. +// SAFETY: The pointer is in-bounds of the allocation. +unsafe { ptr::write (p, element) }; +// SAFETY: Index `len` contains a valid element due to the above copy and write. +unsafe { vec.set_len (len +1 ) }; + } +/// Removes the last element from a vector and returns it, or `None` if it is empty. /// /// # Examples
Signature · 1 line
2.49.0.395.g12beb8f557-goog
Danilo Krummrich
maintainerQuoted 6 lines · Alice Ryhl
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
I'm not sure what we concluded on the
set_len/dec_lenchanges, so I don't depend on that series for now.
So far I see no reason to assume otherwise, so it probably makes sense to rebase. Unless Tamir is fine to rebase his changes onto this series.
Quoted 9 lines
This series is based on top of
Vec::truncatefrom
https://lore.kernel.org/rust-for-linux/[email protected]/Signed-off-by Alice Ryhl <[email protected]>---
Changes in v2:
- Add two more methods that I needed.
- Introduce some uses ofset_len.
I think the added Vec::remove() modifies self.len directly.
Quoted 25 lines
- Add example to retain.
- Simplify pop.
- Adjust 11 to 10 inpush_within_capacityexample.
- Link to v1: https://lore.kernel.org/r/[email protected]---
Alice Ryhl (7):
rust: alloc: addVec::clear
rust: alloc: addVec::pop
rust: alloc: addVec::push_within_capacity
rust: alloc: addVec::drain_all
rust: alloc: addVec::retain
rust: alloc: addVec::remove
rust: alloc: addVec::insert_within_capacityrust/kernel/alloc/kvec.rs | 202 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+)---
base-commit:a337a03281efc4553191b432d757d4c04884bf4c
change-id: 20250320-vec-methods-adfa41e55311Best regards,
Signature · 1 line
Alice Ryhl <[email protected]>
Alice Ryhl
maintainerQuoted 11 lines · Alice Ryhl
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
I'm not sure what we concluded on the
set_len/dec_lenchanges, so I don't depend on that series for now.This series is based on top of
Vec::truncatefrom
https://lore.kernel.org/rust-for-linux/[email protected]/Signed-off-by Alice Ryhl <[email protected]>
Oops, this doesn't compile. Looks like I've already gone on vacation mentally. Sorry guys!
Alice
Quoted 10 lines · Danilo Krummrich
Quoted 6 lines · Alice Ryhl
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
I'm not sure what we concluded on the
set_len/dec_lenchanges, so I don't depend on that series for now.So far I see no reason to assume otherwise, so it probably makes sense to rebase. Unless Tamir is fine to rebase his changes onto this series.
I haven't yet taken a look at the reworked version of dec_len, so I'd wait until we have finished discussion on that.
---
Cheers,
Benno
Quoted 31 lines · Alice Ryhl
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
I'm not sure what we concluded on the
set_len/dec_lenchanges, so I don't depend on that series for now.This series is based on top of
Vec::truncatefrom
https://lore.kernel.org/rust-for-linux/[email protected]/Signed-off-by Alice Ryhl <[email protected]>---
Changes in v2:
- Add two more methods that I needed.
- Introduce some uses ofset_len.
- Add example to retain.
- Simplify pop.
- Adjust 11 to 10 inpush_within_capacityexample.
- Link to v1: https://lore.kernel.org/r/[email protected]---
Alice Ryhl (7):
rust: alloc: addVec::clear
rust: alloc: addVec::pop
rust: alloc: addVec::push_within_capacity
rust: alloc: addVec::drain_all
rust: alloc: addVec::retain
rust: alloc: addVec::remove
rust: alloc: addVec::insert_within_capacity
Quoted 5 lines
rust/kernel/alloc/kvec.rs | 202 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+)---
base-commit:a337a03281efc4553191b432d757d4c04884bf4c
change-id: 20250320-vec-methods-adfa41e55311
I think this doesn't specify the dependencies properly. The base-commit looks to be
https://lore.kernel.org/all/[email protected]/
locally applied. This prevents b4 shazam from working with this series.
Danilo Krummrich
maintainerQuoted 6 lines · Benno Lossin
Quoted 5 lines · Danilo Krummrich
Quoted 4 lines · Alice Ryhl
This adds various Vec methods. Some of them are needed by Rust Binder, and others are needed in other places. Each commit explains where it is needed.
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
I'm not sure what we concluded on the
set_len/dec_lenchanges, so I don't depend on that series for now.So far I see no reason to assume otherwise, so it probably makes sense to rebase. Unless Tamir is fine to rebase his changes onto this series.
I haven't yet taken a look at the reworked version of
dec_len, so I'd wait until we have finished discussion on that.
What I mean is, everything looks like I'll pick them up eventually, so it makes sense to base a subsequent version of this series onto Tramir's (even if the current one of dec_len() is not the final one).