Replace unwraps in doctests with graceful handling
Subsystems (2)
cover Replace unwraps in doctests with graceful handling
There are multiple occurrences where we use unwraps (or other panickable behavior) within documentation tests. In the following patches, I try to replace at least some of the occurrences with graceful handling. I haven't touched the rest (yet), since I am unsure whether we will all agree on this. If we agree on the handling I can submit them in v2 or as a follow patches.
Daniel Sedlak (2):
rust: kernel: init: replace unwraps with the question mark operators
rust: kernel: rbtree: replace unwraps with functional programming
paradigms
rust/kernel/init.rs | 6 ++-- rust/kernel/rbtree.rs | 78 ++++++++++++++++++++++--------------------- 2 files changed, 44 insertions(+), 40 deletions(-)
Signature · 1 line
2.47.0
PATCH 1/2 rust: kernel: init: replace unwraps with the question mark operators
--- rust/kernel/init.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
rust/kernel/init.rs +4 -2
@@ -1076,8 +1076,9 @@ pub fn uninit<T, E>() -> impl Init<MaybeUninit<T>, E> {/// ```rust /// use kernel::{alloc::KBox, error::Error, init::init_array_from_fn}; /// let array: KBox<[usize; 1_000]> = -/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL).unwrap(); +/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,
@@ -1120,8 +1121,9 @@ pub fn init_array_from_fn<I, const N: usize, T, E>(/// ```rust /// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex}; /// let array: Arc<[Mutex<usize>; 1_000]> = -/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL).unwrap(); +/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn pin_init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,
Signature · 1 line
2.47.0
Re: [PATCH 1/2] rust: kernel: init: replace unwraps with the question mark operators
Hi Daniel,
Quoted 1 line · Daniel Sedlak
While talking about that thread, do you like to cover the dox() replacement
https://lore.kernel.org/rust-for-linux/[email protected]/
as well?
Thanks for working on this! :)
Dirk
Quoted 32 lines
Suggested-by Miguel Ojeda <[email protected]>Signed-off-by Daniel Sedlak <[email protected]>--- rust/kernel/init.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)rust/kernel/init.rs +4
-2@@ -1076,8 +1076,9 @@ pub fn uninit<T, E>() -> impl Init<MaybeUninit<T>, E> {/// ```rust /// use kernel::{alloc::KBox, error::Error, init::init_array_from_fn}; /// let array: KBox<[usize; 1_000]> = -/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL).unwrap(); +/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,@@ -1120,8 +1121,9 @@ pub fn init_array_from_fn<I, const N: usize, T, E>(/// ```rust /// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex}; /// let array: Arc<[Mutex<usize>; 1_000]> = -/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL).unwrap(); +/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn pin_init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,
Re: [PATCH 1/2] rust: kernel: init: replace unwraps with the question mark operators
Quoted 7 lines · Dirk Behme
Hi Daniel,
Quoted 1 line · Daniel Sedlak
Quoted 6 lines
While talking about that thread, do you like to cover the
dox()replacementhttps://lore.kernel.org/rust-for-linux/[email protected]/
as well?
Thank you for the reminder! Yes, I will incorporate it.
Quoted 30 lines
Thanks for working on this! :)
Dirk
Quoted 24 lines
Suggested-by Miguel Ojeda <[email protected]>Signed-off-by Daniel Sedlak <[email protected]>--- rust/kernel/init.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)rust/kernel/init.rs +2
-1@@ -1076,8 +1076,9 @@ pub fn uninit<T, E>() -> impl Init<MaybeUninit<T>, E> {/// ```rust /// use kernel::{alloc::KBox, error::Error, init::init_array_from_fn}; /// let array: KBox<[usize; 1_000]> = -/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL).unwrap(); +/// KBox::init::<Error>(init_array_from_fn(|i| i), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,@@ -1120,8 +1121,9 @@ pub fn init_array_from_fn<I, const N: usize, T, E>(/// ```rust /// use kernel::{sync::{Arc, Mutex}, init::pin_init_array_from_fn, new_mutex};
Quoted 9 lines
rust/kernel/init.rs pub fn init_array_from_fn<I, const N: usize, T, E>( · line 1129
Quoted 8 lines
rust/kernel/init.rs +2
-1/// let array: Arc<[Mutex<usize>; 1_000]> = -/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL).unwrap(); +/// Arc::pin_init(pin_init_array_from_fn(|i| new_mutex!(i)), GFP_KERNEL)?; /// assert_eq!(array.len(), 1_000); +/// # Ok::<(), Error>(()) /// ``` pub fn pin_init_array_from_fn <I ,const N :usize ,T ,E >( mut make_init: impl FnMut(usize) -> I,
Daniel
PATCH 2/2 rust: kernel: rbtree: replace unwraps with functional programming paradigms
In reply to Daniel Sedlak--- rust/kernel/rbtree.rs | 78 ++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 38 deletions(-)
rust/kernel/rbtree.rs +40 -38
@@ -36,17 +36,17 @@/// /// // Check the nodes we just inserted. /// { -/// assert_eq!(tree.get(&10).unwrap(), &100); -/// assert_eq!(tree.get(&20).unwrap(), &200); -/// assert_eq!(tree.get(&30).unwrap(), &300); +/// assert_eq!(tree.get(&10), Some(&100)); +/// assert_eq!(tree.get(&20), Some(&200)); +/// assert_eq!(tree.get(&30), Some(&300)); /// } /// /// // Iterate over the nodes we just inserted. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &100)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); -/// assert_eq!(iter.next().unwrap(), (&30, &300)); +/// assert_eq!(iter.next(), Some((&10, &100))); +/// assert_eq!(iter.next(), Some((&20, &200))); +/// assert_eq!(iter.next(), Some((&30, &300))); /// assert!(iter.next().is_none()); /// } ///
@@ -61,21 +61,23 @@/// // Check that the tree reflects the replacement. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &1000)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); -/// assert_eq!(iter.next().unwrap(), (&30, &300)); +/// assert_eq!(iter.next(), Some((&10, &1000))); +/// assert_eq!(iter.next(), Some((&20, &200))); +/// assert_eq!(iter.next(), Some((&30, &300))); /// assert!(iter.next().is_none()); /// } /// /// // Change the value of one of the elements. -/// *tree.get_mut(&30).unwrap() = 3000; +/// if let Some(element) = tree.get_mut(&30) { +/// *element = 3000; +/// } /// /// // Check that the tree reflects the update. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &1000)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); -/// assert_eq!(iter.next().unwrap(), (&30, &3000)); +/// assert_eq!(iter.next(), Some((&10, &1000))); +/// assert_eq!(iter.next(), Some((&20, &200))); +/// assert_eq!(iter.next(), Some((&30, &3000))); /// assert!(iter.next().is_none()); /// } ///
@@ -85,8 +87,8 @@/// // Check that the tree reflects the removal. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); -/// assert_eq!(iter.next().unwrap(), (&30, &3000)); +/// assert_eq!(iter.next(), Some((&20, &200))); +/// assert_eq!(iter.next(), Some((&30, &3000))); /// assert!(iter.next().is_none()); /// } ///
@@ -128,20 +130,20 @@/// // Check the nodes we just inserted. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &100)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); -/// assert_eq!(iter.next().unwrap(), (&30, &300)); +/// assert_eq!(iter.next(), Some((&10, &100))); +/// assert_eq!(iter.next(), Some((&20, &200))); +/// assert_eq!(iter.next(), Some((&30, &300))); /// assert!(iter.next().is_none()); /// } /// /// // Remove a node, getting back ownership of it. -/// let existing = tree.remove(&30).unwrap(); +/// let existing = tree.remove(&30); /// /// // Check that the tree reflects the removal. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &100)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); +/// assert_eq!(iter.next(), Some((&10, &100))); +/// assert_eq!(iter.next(), Some((&20, &200))); /// assert!(iter.next().is_none()); /// } ///
@@ -155,9 +157,9 @@/// // Check that the tree reflect the new insertion. /// { /// let mut iter = tree.iter(); -/// assert_eq!(iter.next().unwrap(), (&10, &100)); -/// assert_eq!(iter.next().unwrap(), (&15, &150)); -/// assert_eq!(iter.next().unwrap(), (&20, &200)); +/// assert_eq!(iter.next(), Some((&10, &100))); +/// assert_eq!(iter.next(), Some((&15, &150))); +/// assert_eq!(iter.next(), Some((&20, &200))); /// assert!(iter.next().is_none()); /// } ///
@@ -677,7 +679,7 @@ fn drop(&mut self) {/// Nodes adjacent to the current node can also be removed. /// /// ``` -/// use kernel::{alloc::flags, rbtree::RBTree}; +/// use kernel::{alloc::flags, rbtree::{RBTree, RBTreeNode, Cursor}}; /// /// // Create a new tree. /// let mut tree = RBTree::new();
@@ -688,31 +690,31 @@ fn drop(&mut self) {/// tree.try_create_and_insert(30, 300, flags::GFP_KERNEL)?; /// /// // Get a cursor to the first element. -/// let mut cursor = tree.cursor_front().unwrap(); -/// let mut current = cursor.current(); -/// assert_eq!(current, (&10, &100)); +/// let mut cursor = tree.cursor_front(); +/// let mut current = cursor.as_ref().map(Cursor::current); +/// assert_eq!(current, Some((&10, &100))); /// /// // Calling `remove_prev` from the first element returns [`None`]. -/// assert!(cursor.remove_prev().is_none()); +/// assert!(cursor.as_mut().map(Cursor::remove_prev).flatten().is_none()); /// /// // Get a cursor to the last element. -/// cursor = tree.cursor_back().unwrap(); -/// current = cursor.current(); -/// assert_eq!(current, (&30, &300)); +/// cursor = tree.cursor_back(); +/// current = cursor.as_ref().map(Cursor::current); +/// assert_eq!(current, Some((&30, &300))); /// /// // Calling `remove_prev` removes and returns the middle element. -/// assert_eq!(cursor.remove_prev().unwrap().to_key_value(), (20, 200)); +/// assert_eq!(cursor.as_mut().map(Cursor::remove_prev).flatten().map(RBTreeNode::to_key_value), Some((20, 200))); /// /// // Calling `remove_next` from the last element returns [`None`]. -/// assert!(cursor.remove_next().is_none()); +/// assert!(cursor.as_mut().map(Cursor::remove_next).flatten().is_none()); /// /// // Move to the first element -/// cursor = cursor.move_prev().unwrap(); -/// current = cursor.current(); -/// assert_eq!(current, (&10, &100)); +/// cursor = cursor.map(Cursor::move_prev).flatten(); +/// current = cursor.as_ref().map(Cursor::current); +/// assert_eq!(current, Some((&10, &100))); /// /// // Calling `remove_next` removes and returns the last element. -/// assert_eq!(cursor.remove_next().unwrap().to_key_value(), (30, 300)); +/// assert_eq!(cursor.as_mut().map(Cursor::remove_next).flatten().map(RBTreeNode::to_key_value), Some((30, 300))); /// /// # Ok::<(), Error>(()) ///
Signature · 1 line
2.47.0
Re: [PATCH 2/2] rust: kernel: rbtree: replace unwraps with functional programming paradigms
rust/kernel/rbtree.rs line 41
Quoted 7 lines · Daniel Sedlak
rust/kernel/rbtree.rs +3
-3-/// assert_eq!(tree.get(&10).unwrap(), &100); -/// assert_eq!(tree.get(&20).unwrap(), &200); -/// assert_eq!(tree.get(&30).unwrap(), &300); +/// assert_eq!(tree.get(&10), Some(&100)); +/// assert_eq!(tree.get(&20), Some(&200)); +/// assert_eq!(tree.get(&30), Some(&300));
This looks fine, in the sense that it is simpler (less characters), more explicit for the reader (on what get() returns) and avoids the unwrap(). Plus some examples of the standard library examples do it this way too.
However, I am not sure we would necessarily want to do it in all cases inside assert!s. After all, assert!s are already panics themselves (in normal code, and diverging in doctests anyway), i.e. it is something one would normally not do anyway.
When I suggested this, I was mainly thinking about other places that we may have unwrap()s in example code that could be easily misunderstood for "normal code", i.e. places that should probably use ? or handle the error somehow, like the one in your other patch.
So I am ambivalent about some of the other cases. On one hand, it makes some tests noisier. On the other hand, it may help to show how one could do things without unwrap().
Thoughts?
rust/kernel/rbtree.rs line 73
Quoted 4 lines
rust/kernel/rbtree.rs +3
-1-/// *tree.get_mut(&30).unwrap() = 3000; +/// if let Some(element) = tree.get_mut(&30) { +/// *element = 3000; +/// }
This change looks wrong to me (not equivalent), because it is changing the semantics -- this one continues if it couldn't get it, rather than stopping.
Shouldn't it be .ok_or(E...)? or similar (or EBUG if we had it, like Rasmus suggested) if we really wanted to avoid the .unwrap()?
By the way, please double check with CLIPPY=1 (it warns); and if there is a new version, please Cc also e.g. the author, in this case Matt (typically one would see what scripts/get_maintainers.pl returns).
Thanks!
Cheers,
Miguel
Re: [PATCH 2/2] rust: kernel: rbtree: replace unwraps with functional programming paradigms
Quoted 25 lines · Miguel Ojeda
rust/kernel/rbtree.rs line 41
Quoted 7 lines · Daniel Sedlak
rust/kernel/rbtree.rs +3
-3-/// assert_eq!(tree.get(&10).unwrap(), &100); -/// assert_eq!(tree.get(&20).unwrap(), &200); -/// assert_eq!(tree.get(&30).unwrap(), &300); +/// assert_eq!(tree.get(&10), Some(&100)); +/// assert_eq!(tree.get(&20), Some(&200)); +/// assert_eq!(tree.get(&30), Some(&300)); This looks fine, in the sense that it is simpler (less characters), more explicit for the reader (on what
get()returns) and avoids theunwrap(). Plus some examples of the standard library examples do it this way too.However, I am not sure we would necessarily want to do it in all cases inside
assert!s. After all,assert!s are already panics themselves (in normal code, and diverging in doctests anyway), i.e. it is something one would normally not do anyway.When I suggested this, I was mainly thinking about other places that we may have
unwrap()s in example code that could be easily misunderstood for "normal code", i.e. places that should probably use?or handle the error somehow, like the one in your other patch.
Quoted 5 lines
So I am ambivalent about some of the other cases. On one hand, it makes some tests noisier. On the other hand, it may help to show how one could do things without
unwrap().Thoughts?
My reasoning for doing it this way is that people typically tend to copy & paste code from the examples (citation needed). If we leave the unwraps there, I think we can convey the wrong impression, that it is OK to use unwraps and this may be opinionated, but I think™ that examples should also tell that code should not use unwraps unless the programmer has a really good reason to use them. Furthermore, unwrap & expect can be used on both Option and Result, and since there are calls to tree.get(…).unwrap() I wanted to disambiguate it a little.
But if you think that it is unnecessary, then I will only tackle the previous scope
of this issue as you mentioned.
Quoted 10 lines
rust/kernel/rbtree.rs line 73
Quoted 5 lines
rust/kernel/rbtree.rs +3
-1-/// *tree.get_mut(&30).unwrap() = 3000; +/// if let Some(element) = tree.get_mut(&30) { +/// *element = 3000; +/// } This change looks wrong to me (not equivalent), because it is changing the semantics -- this one continues if it couldn't get it, rather than stopping.
Quoted 2 lines
Shouldn't it be
.ok_or(E...)?or similar (orEBUGif we had it, like Rasmus suggested) if we really wanted to avoid the.unwrap()?
You are right, it probably should, I will check that and try to incorporate it.
Quoted 5 lines
By the way, please double check with
CLIPPY=1(it warns); and if there is a new version, please Cc also e.g. the author, in this case Matt (typically one would see whatscripts/get_maintainers.plreturns).
I am not sure, whether I am using the clippy right, I am compiling with make LLVM=1 CLIPPY=1, however, no clippy warnings are triggered.
```text clippy-driver -V clippy 0.1.82 (f6e511e 2024-10-15) ```
Also sorry for my question, but which new version of what do you mean? Clippy?
Quoted 5 lines
Thanks!
Cheers,
Miguel
Thank you for your valuable insights!
Daniel
Re: [PATCH 2/2] rust: kernel: rbtree: replace unwraps with functional programming paradigms
Quoted 4 lines · Daniel Sedlak
But if you think that it is unnecessary, then I will only tackle the previous scope
of this issue as you mentioned.
Let's see what others think.
(To clarify, I am happy with the change I quoted for instance)
Quoted 2 lines
I am not sure, whether I am using the clippy right, I am compiling with
make LLVM=1 CLIPPY=1, however, no clippy warnings are triggered.
That should work -- are you building the doctests? (i.e. CONFIG_RUST_KERNEL_DOCTESTS).
The warnings I am getting are clippy::map_flatten ones.
Quoted 1 line
Also sorry for my question, but which new version of what do you mean? Clippy?
I meant the future version of this patch, i.e. v2.
Quoted 1 line
Thank you for your valuable insights!
You're welcome :)
By the way, for v2, the patches need to have some description in the commit message (apart from the title and the tags, I mean). Thanks!
Cheers,
Miguel
Re: [PATCH 2/2] rust: kernel: rbtree: replace unwraps with functional programming paradigms
Quoted 9 lines · Miguel Ojeda
Quoted 4 lines · Daniel Sedlak
But if you think that it is unnecessary, then I will only tackle the previous scope
of this issue as you mentioned.Let's see what others think.
Quoted 7 lines
(To clarify, I am happy with the change I quoted for instance)
Quoted 2 lines
I am not sure, whether I am using the clippy right, I am compiling with
make LLVM=1 CLIPPY=1, however, no clippy warnings are triggered.That should work -- are you building the doctests? (i.e.
CONFIG_RUST_KERNEL_DOCTESTS).
Yes, that did the trick. I somewhat assumed that it was turned on by default. Thank you for helping with that.
Quoted 9 lines
The warnings I am getting are
clippy::map_flattenones.Quoted 1 line
Also sorry for my question, but which new version of what do you mean? Clippy?
I meant the future version of this patch, i.e. v2.
Quoted 1 line
Thank you for your valuable insights!
Quoted 7 lines
You're welcome :)
By the way, for v2, the patches need to have some description in the commit message (apart from the title and the tags, I mean). Thanks!
Cheers,
Miguel
Daniel
Quoted 6 lines · Daniel Sedlak
There are multiple occurrences where we use unwraps (or other panickable behavior) within documentation tests. In the following patches, I try to replace at least some of the occurrences with graceful handling. I haven't touched the rest (yet), since I am unsure whether we will all agree on this. If we agree on the handling I can submit them in v2 or as a follow patches.
Thanks!
Tip for next time: when you are posting patches for comments only, i.e. when a patch is not meant to be applied as-is because it needs some discussion first, like in this case, you would typically send it as an RFC instead -- use --rfc in git format-patch.
Moreover, ideally you would also add the rationale in the cover letter (and commit messages), i.e. why you think this should be done (the Link you had in the other messages is good, but normally you want to say something rather than just link).
Cheers,
Miguel
Quoted 9 lines · Miguel Ojeda
Quoted 6 lines · Daniel Sedlak
There are multiple occurrences where we use unwraps (or other panickable behavior) within documentation tests. In the following patches, I try to replace at least some of the occurrences with graceful handling. I haven't touched the rest (yet), since I am unsure whether we will all agree on this. If we agree on the handling I can submit them in v2 or as a follow patches.
Quoted 6 lines
Thanks!
Tip for next time: when you are posting patches for comments only, i.e. when a patch is not meant to be applied as-is because it needs some discussion first, like in this case, you would typically send it as an RFC instead -- use
--rfcingit format-patch.
Thank you for the tip, I didn't know about this.
Quoted 5 lines
Moreover, ideally you would also add the rationale in the cover letter (and commit messages), i.e. why you think this should be done (the Link you had in the other messages is good, but normally you want to say something rather than just link).
Sure, I will add comments to the individual commits. Also, since all patches try to remove unwraps, I am wondering whether it should be one large patch or multiple small patches?
Quoted 3 lines
Cheers,
Miguel
Daniel
Quoted 4 lines · Daniel Sedlak
Sure, I will add comments to the individual commits. Also, since all patches try to remove unwraps, I am wondering whether it should be one large patch or multiple small patches?
It depends, e.g. sometimes it is split by subsystem, so that you can address different sets of people and so that they can take the patches independently within their own schedules and through their trees.
You can search for some big/tree-wide series to see examples on how it is usually done, or read e.g. https://lwn.net/Articles/585782/
I hope that helps!
Cheers,
Miguel