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

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

[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.

Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>
---
 rust/kernel/alloc/kvec.rs | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index ac8d6f763ae8..fc4bf0a7934d 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -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) };
 
-- 
2.43.0

Re: [PATCH] rust: alloc: add doc test for `Vec::extend_with` and fix comment

[Alexandre Courbot]

Hello Hsiu,

On Sat Apr 25, 2026 at 3:08 PM JST, Hsiu Che Yu wrote:
> 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

Re: [PATCH] rust: alloc: add doc test for `Vec::extend_with` and fix comment

[Hsiu Che Yu]

Hi Alexandre,

On Sat, Apr 25, 2026 at 03:32:57PM +0900, Alexandre Courbot wrote:
>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

Re: [PATCH] rust: alloc: add doc test for `Vec::extend_with` and fix comment

[Alexandre Courbot]

On Sat Apr 25, 2026 at 3:53 PM JST, Hsiu Che Yu wrote:
> Hi Alexandre,
>
> On Sat, Apr 25, 2026 at 03:32:57PM +0900, Alexandre Courbot wrote:
>>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.

Re: [PATCH] rust: alloc: add doc test for `Vec::extend_with` and fix comment

[Hsiu Che Yu]

On Sat, Apr 25, 2026 at 04:20:22PM +0900, Alexandre Courbot wrote:
>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

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

[Hsiu Che Yu]

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

Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>
---
 rust/kernel/alloc/kvec.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index ac8d6f763ae8..408a51ad3623 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -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(());
-- 
2.43.0

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

[Alexandre Courbot]

On Sat Apr 25, 2026 at 7:16 PM JST, Hsiu Che Yu wrote:
> Add a doc test for `Vec::extend_with` demonstrating basic usage and the
> zero-length case.
>
> Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Tested-by: Alexandre Courbot <acourbot@nvidia.com>

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

[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.

Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>
---
 rust/kernel/alloc/kvec.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/kernel/alloc/kvec.rs b/rust/kernel/alloc/kvec.rs
index 408a51ad3623..fc4bf0a7934d 100644
--- a/rust/kernel/alloc/kvec.rs
+++ b/rust/kernel/alloc/kvec.rs
@@ -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) };
 
-- 
2.43.0

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

[Alexandre Courbot]

On Sat Apr 25, 2026 at 7:16 PM JST, Hsiu Che Yu wrote:
> 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.
>
> Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>

Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>

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

[Miguel Ojeda]

On Sat, Apr 25, 2026 at 12:18 PM Hsiu Che Yu
<yu.whisper.personal@gmail.com> wrote:
>
> 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.
>
> Signed-off-by: Hsiu Che Yu <yu.whisper.personal@gmail.com>

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

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

[Hsiu Che Yu]

On Sun, Apr 26, 2026 at 03:10:12PM +0200, Miguel Ojeda wrote:
>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)!

On Sun, Apr 26, 2026 at 03:10:12PM +0200, Miguel Ojeda wrote:
>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

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

[Miguel Ojeda]

On Mon, Apr 27, 2026 at 5:58 AM Hsiu Che Yu
<yu.whisper.personal@gmail.com> wrote:
>
> 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

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

[Hsiu Che Yu]

On Mon, Apr 27, 2026 at 03:22:18PM +0200, Miguel Ojeda wrote:
>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).

Thanks, that's very helpful!

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

Thanks,
Hsiu