Skip to contentSkip to conversation

rust: alloc: add doc test for `Vec::extend_with` and fix comment

PATCH Superseded Hsiu Che Yu 4 participants 16 messages Apr 25 – May 12

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 rust: alloc: add doc test for `Vec::extend_with` and fix comment

Add a doc test for Vec::extend_with demonstrating basic usage and the zero-length case.

Also fix an incorrect operator in the SAFETY comment, changing < to <=, since Vec::reserve guarantees capacity for exactly n additional elements, so the equal case should be included.

---
 rust/kernel/alloc/kvec.rs | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)
rust/kernel/alloc/kvec.rs +19 -1
index ac8d6f763ae8..fc4bf0a7934d 100644
@@ -737,6 +737,24 @@ pub fn retain(&mut self, mut f: impl FnMut(&mut T) -> bool) {
 
 impl<T: Clone, A: Allocator> Vec<T, A> {
     /// Extend the vector by `n` clones of `value`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut v = KVec::new();
+    /// v.push(1, GFP_KERNEL)?;
+    ///
+    /// v.extend_with(3, 5, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5]);
+    ///
+    /// v.extend_with(2, 8, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5, 8, 8]);
+    ///
+    /// v.extend_with(0, 3, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5, 8, 8]);
+    ///
+    /// # Ok::<(), Error>(())
+    /// ```
     pub fn extend_with(&mut self, n: usize, value: T, flags: Flags) -> Result<(), AllocError> {
         if n == 0 {
             return Ok(());
@@ -754,7 +772,7 @@ pub fn extend_with(&mut self, n: usize, value: T, flags: Flags) -> Result<(), Al
         spare[n - 1].write(value);
 
         // SAFETY:
-        // - `self.len() + n < self.capacity()` due to the call to reserve above,
+        // - `self.len() + n <= self.capacity()` due to the call to reserve above,
         // - the loop and the line above initialized the next `n` elements.
         unsafe { self.inc_len(n) };
 
Signature · 1 line
2.43.0
#1 lore raw

Hello Hsiu,

Quoted 6 lines · Hsiu Che Yu

Add a doc test for Vec::extend_with demonstrating basic usage and the zero-length case.

Also fix an incorrect operator in the SAFETY comment, changing < to <=, since Vec::reserve guarantees capacity for exactly n additional elements, so the equal case should be included.

As per the guidelines [1], "A patch should do one thing and one thing only".

These should be two separate patches.

[1] https://kernelnewbies.org/PatchSeries

#2 lore raw

Hi Alexandre,

Quoted 4 lines · Alexandre Courbot

As per the guidelines [1], "A patch should do one thing and one thing only".

These should be two separate patches.

You're right, my apologies for bundling two unrelated changes together.

Should I send these as two separate v2 patches, or start fresh with two new patch series?

Thanks,
Hsiu

#3 lore raw
Quoted 11 lines · Hsiu Che Yu

Hi Alexandre,

Quoted 4 lines · Alexandre Courbot

As per the guidelines [1], "A patch should do one thing and one thing only".

These should be two separate patches.

You're right, my apologies for bundling two unrelated changes together.

Should I send these as two separate v2 patches, or start fresh with two new patch series?

A v2 sounds appropriate since this it is the same work, only rearranged a bit.

#4 lore raw
Quoted 1 line · Alexandre Courbot

A v2 sounds appropriate since this it is the same work, only rearranged a bit.

Got it. I will send out v2 shortly.

thanks,
Hsiu

#5 lore raw

v2 cover rust: alloc: fix and test `Vec::extend_with`

In reply to Hsiu Che Yu

Fix an incorrect SAFETY comment and add a doc test for Vec::extend_with.

---
Changes in v2:
- Split into two separate patches per maintainer feedback

Hsiu Che Yu (2):
rust: alloc: add doc test for Vec::extend_with
rust: alloc: fix Vec::extend_with SAFETY comment

 rust/kernel/alloc/kvec.rs | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)
Signature · 1 line
2.43.0
#6 lore raw

PATCH v2 1/2 rust: alloc: add doc test for `Vec::extend_with`

Add a doc test for Vec::extend_with demonstrating basic usage and the zero-length case.

---
 rust/kernel/alloc/kvec.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
rust/kernel/alloc/kvec.rs +18 -0
index ac8d6f763ae8..408a51ad3623 100644
@@ -737,6 +737,24 @@ pub fn retain(&mut self, mut f: impl FnMut(&mut T) -> bool) {
 
 impl<T: Clone, A: Allocator> Vec<T, A> {
     /// Extend the vector by `n` clones of `value`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut v = KVec::new();
+    /// v.push(1, GFP_KERNEL)?;
+    ///
+    /// v.extend_with(3, 5, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5]);
+    ///
+    /// v.extend_with(2, 8, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5, 8, 8]);
+    ///
+    /// v.extend_with(0, 3, GFP_KERNEL)?;
+    /// assert_eq!(&v, &[1, 5, 5, 5, 8, 8]);
+    ///
+    /// # Ok::<(), Error>(())
+    /// ```
     pub fn extend_with(&mut self, n: usize, value: T, flags: Flags) -> Result<(), AllocError> {
         if n == 0 {
             return Ok(());
Signature · 1 line
2.43.0
#8 lore raw

PATCH v2 2/2 rust: alloc: fix `Vec::extend_with` SAFETY comment

In reply to Hsiu Che Yu

Fix an incorrect operator in the SAFETY comment, changing < to <=, since Vec::reserve guarantees capacity for exactly n additional elements, so the equal case should be included.

---
 rust/kernel/alloc/kvec.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/alloc/kvec.rs +1 -1
index 408a51ad3623..fc4bf0a7934d 100644
@@ -772,7 +772,7 @@ pub fn extend_with(&mut self, n: usize, value: T, flags: Flags) -> Result<(), Al
         spare[n - 1].write(value);
 
         // SAFETY:
-        // - `self.len() + n < self.capacity()` due to the call to reserve above,
+        // - `self.len() + n <= self.capacity()` due to the call to reserve above,
         // - the loop and the line above initialized the next `n` elements.
         unsafe { self.inc_len(n) };
 
Signature · 1 line
2.43.0
#10 lore raw

Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment

In reply to Hsiu Che Yu
Quoted 6 lines · Hsiu Che Yu

Fix an incorrect operator in the SAFETY comment, changing < to <=, since Vec::reserve guarantees capacity for exactly n additional elements, so the equal case should be included.

Thanks!

For this case it doesn't matter too much, but in general, when something is a fix, we add a Fixes: tag (and in most cases Cc: stable@ to accompany it). That helps backporting (when needed), adds context e.g. for reviewing (at times), etc.

By the way, now that I was looking at reserve(), the assert in the example there should probably use >= 11 since there is already an element, instead of >= 10. That could be another similar patch.

Cheers,
Miguel

#11 lore raw

Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment

Quoted 4 lines · Miguel Ojeda

For this case it doesn't matter too much, but in general, when something is a fix, we add a Fixes: tag (and in most cases Cc: stable@ to accompany it). That helps backporting (when needed), adds context e.g. for reviewing (at times), etc.

I did miss the Fixes: tag — and what I hadn't thought about was that these tags feed into the underlying tooling and workflows. I'll make sure to include a Fixes: tag in fix-related commits going forward (and will likely use one in the assert! patch coming up shortly)!

Quoted 3 lines · Miguel Ojeda

By the way, now that I was looking at reserve(), the assert in the example there should probably use >= 11 since there is already an element, instead of >= 10. That could be another similar patch.

I'll go ahead and work on that. I was thinking of changing it to >= v.len() + 10, which might make the intent clearer. For this patch, should I include the Suggested-by:, Reported-by:, and Fixes: tags?

Thanks,
Hsiu

#12 lore raw

Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment

Quoted 3 lines · Hsiu Che Yu

For this patch, should I include the Suggested-by:, Reported-by:, and Fixes: tags?

If you only need to resend just for that, then what is usually done instead is to reply with the tags here -- then they can be picked up by maintainers or in the next version by the author, e.g.

Fixes ...

(ideally without the indentation so that tools may pick it up automatically)

By the way, an easy rule of thumb is using, for fixes, Reported-by: +
Closes: + Fixes:, while Suggested-by: + Link: for features (but there are of course exceptions, e.g. someone may have suggested something important in a fix etc., i.e. it depends -- please see Documentation/process/submitting-patches.rst for the actual meaning).

I hope that helps!

Cheers,
Miguel

#13 lore raw

Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment

Quoted 6 lines · Miguel Ojeda

If you only need to resend just for that, then what is usually done instead is to reply with the tags here -- then they can be picked up by maintainers or in the next version by the author, e.g.

Fixes ...
Quoted 7 lines

(ideally without the indentation so that tools may pick it up automatically)

By the way, an easy rule of thumb is using, for fixes, Reported-by: +
Closes: + Fixes:, while Suggested-by: + Link: for features (but there are of course exceptions, e.g. someone may have suggested something important in a fix etc., i.e. it depends -- please see Documentation/process/submitting-patches.rst for the actual meaning).

Thanks, that's very helpful!

Fixes 2aac4cd7dae3d ("rust: alloc: implement kernel `Vec` type")

Thanks,
Hsiu

#14 lore raw

Re: [PATCH v2 0/2] rust: alloc: fix and test `Vec::extend_with`

In reply to Hsiu Che Yu
Quoted 5 lines · Hsiu Che Yu

Fix an incorrect SAFETY comment and add a doc test for Vec::extend_with.

---
Changes in v2:
- Split into two separate patches per maintainer feedback

Looking good - just one thing, when sending a new revision of a patchset, please start a new thread instead of replying to the previous one. Otherwise things can get pretty hard to follow once we arrive at, say, v10. :)

maintainer Applied
#15 lore raw

Re: [PATCH v2 0/2] rust: alloc: fix and test `Vec::extend_with`

In reply to Hsiu Che Yu
Quoted 1 line · Hsiu Che Yu

[PATCH v2 0/2] rust: alloc: fix and test Vec::extend_with

Applied, thanks!

Branch: alloc-next
Tree: [email protected]:Rust-for-Linux/linux.git

[1/2] rust: alloc: add doc test for Vec::extend_with

      commit: 802ca0008bba
[2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment
      commit: f497aae6ded4

The patches will appear in the next linux-next integration (typically within 24 hours on weekdays).

The patches are queued up for the upcoming merge window for the next major kernel release.