rust: alloc: add doc test for `Vec::extend_with` and fix comment
Subsystems (2)
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
@@ -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
Alexandre Courbot
reviewerHello Hsiu,
Quoted 6 lines · Hsiu Che Yu
Add a doc test for
Vec::extend_withdemonstrating basic usage and the zero-length case.Also fix an incorrect operator in the SAFETY comment, changing
<to<=, sinceVec::reserveguarantees 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.
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
Alexandre Courbot
reviewerQuoted 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.
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
v2 cover rust: alloc: fix and test `Vec::extend_with`
In reply to Hsiu Che YuFix 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
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
@@ -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
Re: [PATCH v2 1/2] rust: alloc: add doc test for `Vec::extend_with`
Quoted 4 lines · Hsiu Che Yu
Add a doc test for
Vec::extend_withdemonstrating basic usage and the zero-length case.Signed-off-by Hsiu Che Yu <[email protected]>
PATCH v2 2/2 rust: alloc: fix `Vec::extend_with` SAFETY comment
In reply to Hsiu Che YuFix 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
@@ -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
Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment
Quoted 5 lines · Hsiu Che Yu
Fix an incorrect operator in the SAFETY comment, changing
<to<=, sinceVec::reserveguarantees capacity for exactly n additional elements, so the equal case should be included.Signed-off-by Hsiu Che Yu <[email protected]>
Re: [PATCH v2 2/2] rust: alloc: fix `Vec::extend_with` SAFETY comment
In reply to Hsiu Che YuQuoted 6 lines · Hsiu Che Yu
Fix an incorrect operator in the SAFETY comment, changing
<to<=, sinceVec::reserveguarantees capacity for exactly n additional elements, so the equal case should be included.Signed-off-by Hsiu Che Yu <[email protected]>
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
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>= 11since 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
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.
(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
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 seeDocumentation/process/submitting-patches.rstfor the actual meaning).
Thanks, that's very helpful!
Thanks,
Hsiu
Alexandre Courbot
reviewerRe: [PATCH v2 0/2] rust: alloc: fix and test `Vec::extend_with`
In reply to Hsiu Che YuQuoted 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. :)
Re: [PATCH v2 0/2] rust: alloc: fix and test `Vec::extend_with`
In reply to Hsiu Che YuQuoted 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: f497aae6ded4The 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.