rust/revocable: add try_access_with() convenience method
Alexandre Courbot
reviewerv3 cover rust/revocable: add try_access_with() convenience method
This is a feature I found useful to have while writing Nova driver code that accessed registers alongside other operations. I would find myself quite confused about whether the guard was held or dropped at a given point of the code, and it felt like walking through a minefield; this pattern makes things safer and easier to read according to my experience writing nova-core code.
---
Changes in v3:
- Add Acked-by from v2.
Changes in v2:
- Use FnOnce for the callback type.
- Rename to try_access_with.
- Don't assume that users will want to map failure to ENXIO and return an option.
- Use a single method and let users adapt the behavior using their own wrappers/macros.
---
Alexandre Courbot (2):
rust/revocable: add try_access_with() convenience method
samples: rust: convert PCI rust sample driver to use try_access_with()
rust/kernel/revocable.rs | 16 ++++++++++++++++ samples/rust/rust_driver_pci.rs | 11 +++++------ 2 files changed, 21 insertions(+), 6 deletions(-)
---
base-commit: 7eb172143d5508b4da468ed59ee857c6e5e01da6
change-id: 20250313-try_with-cc9f91dd3b60
Best regards,
Signature · 1 line
Alexandre Courbot <[email protected]>
Alexandre Courbot
reviewerPATCH v3 1/2 rust/revocable: add try_access_with() convenience method
Revocable::try_access() returns a guard through which the wrapped object can be accessed. Code that can sleep is not allowed while the guard is held; thus, it is common for the caller to explicitly drop it before running sleepable code, e.g:
let b = bar.try_access()?;
let reg = b.readl(...);
// Don't forget this or things could go wrong!
drop(b);
something_that_might_sleep();
let b = bar.try_access()?;
let reg2 = b.readl(...);This is arguably error-prone. try_access_with() provides an arguably safer alternative, by taking a closure that is run while the guard is held, and by dropping the guard automatically after the closure completes. This way, code can be organized more clearly around the critical sections and the risk of forgetting to release the guard when needed is considerably reduced:
let reg = bar.try_access_with(|b| b.readl(...))?;
something_that_might_sleep();
let reg2 = bar.try_access_with(|b| b.readl(...))?;The closure can return nothing, or any value including a Result which is then wrapped inside the Option returned by try_access_with. Error management is driver-specific, so users are encouraged to create their own macros that map and flatten the returned values to something appropriate for the code they are working on.
--- rust/kernel/revocable.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)
rust/kernel/revocable.rs +16 -0
@@ -123,6 +123,22 @@ pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a } } +/// Tries to access the wrapped object and run a closure on it while the guard is held. +/// +/// This is a convenience method to run short non-sleepable code blocks while ensuring the +/// guard is dropped afterwards. [`Self::try_access`] carries the risk that the caller will +/// forget to explicitly drop that returned guard before calling sleepable code; this method +/// adds an extra safety to make sure it doesn't happen. +/// +/// Returns `None` if the object has been revoked and is therefore no longer accessible, or the +/// result of the closure wrapped in `Some`. If the closure returns a [`Result`] then the +/// return type becomes `Option<Result<>>`, which can be inconvenient. Users are encouraged to +/// define their own macro that turns the `Option` into a proper error code and flattens the +/// inner result into it if it makes sense within their subsystem. +pub fn try_access_with <R ,F :FnOnce (&T ) ->R >(&self, f:F ) ->Option <R > { + self.try_access ().map (|t|f (&*t)) + } +/// # Safety /// /// Callers must ensure that there are no more concurrent users of the revocable object.
Signature · 1 line
2.49.0
Quoted 35 lines · Alexandre Courbot
Revocable::try_access()returns a guard through which the wrapped object can be accessed. Code that can sleep is not allowed while the guard is held; thus, it is common for the caller to explicitly drop it before running sleepable code, e.g:let b = bar.try_access()?; let reg = b.readl(...); // Don't forget this or things could go wrong! drop(b); something_that_might_sleep(); let b = bar.try_access()?; let reg2 = b.readl(...);This is arguably error-prone.
try_access_with()provides an arguably safer alternative, by taking a closure that is run while the guard is held, and by dropping the guard automatically after the closure completes. This way, code can be organized more clearly around the critical sections and the risk of forgetting to release the guard when needed is considerably reduced:let reg = bar.try_access_with(|b| b.readl(...))?; something_that_might_sleep(); let reg2 = bar.try_access_with(|b| b.readl(...))?;The closure can return nothing, or any value including a Result which is then wrapped inside the Option returned by
try_access_with. Error management is driver-specific, so users are encouraged to create their own macros that map and flatten the returned values to something appropriate for the code they are working on.
Quoted 3 lines
Acked-by Danilo Krummrich <[email protected]>Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Alexandre Courbot <[email protected]>
Quoted 14 lines
--- rust/kernel/revocable.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)rust/kernel/revocable.rs +2
-0@@ -123,6 +123,22 @@ pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a } } +/// Tries to access the wrapped object and run a closure on it while the guard is held. +///
rust/kernel/revocable.rs pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a · line 137
Quoted 10 lines
rust/kernel/revocable.rs +10
-0+/// This is a convenience method to run short non-sleepable code blocks while ensuring the +/// guard is dropped afterwards. [`Self::try_access`] carries the risk that the caller will +/// forget to explicitly drop that returned guard before calling sleepable code; this method +/// adds an extra safety to make sure it doesn't happen. +/// +/// Returns `None` if the object has been revoked and is therefore no longer accessible, or the +/// result of the closure wrapped in `Some`. If the closure returns a [`Result`] then the +/// return type becomes `Option<Result<>>`, which can be inconvenient. Users are encouraged to +/// define their own macro that turns the `Option` into a proper error code and flattens the +/// inner result into it if it makes sense within their subsystem.
I personally wouldn't have mentioned this in the docs, since to me such a helper would be obvious, but I don't mind it either.
---
Cheers,
Benno
Quoted 7 lines
rust/kernel/revocable.rs +4
-0+pub fn try_access_with <R ,F :FnOnce (&T ) ->R >(&self, f:F ) ->Option <R > { + self.try_access ().map (|t|f (&*t)) + } +/// # Safety /// /// Callers must ensure that there are no more concurrent users of the revocable object.
Alexandre Courbot
reviewerQuoted 54 lines · Benno Lossin
Quoted 35 lines · Alexandre Courbot
Revocable::try_access()returns a guard through which the wrapped object can be accessed. Code that can sleep is not allowed while the guard is held; thus, it is common for the caller to explicitly drop it before running sleepable code, e.g:let b = bar.try_access()?; let reg = b.readl(...); // Don't forget this or things could go wrong! drop(b); something_that_might_sleep(); let b = bar.try_access()?; let reg2 = b.readl(...);This is arguably error-prone.
try_access_with()provides an arguably safer alternative, by taking a closure that is run while the guard is held, and by dropping the guard automatically after the closure completes. This way, code can be organized more clearly around the critical sections and the risk of forgetting to release the guard when needed is considerably reduced:let reg = bar.try_access_with(|b| b.readl(...))?; something_that_might_sleep(); let reg2 = bar.try_access_with(|b| b.readl(...))?;The closure can return nothing, or any value including a Result which is then wrapped inside the Option returned by
try_access_with. Error management is driver-specific, so users are encouraged to create their own macros that map and flatten the returned values to something appropriate for the code they are working on.Quoted 3 lines
Acked-by Danilo Krummrich <[email protected]>Suggested-by Danilo Krummrich <[email protected]>Signed-off-by Alexandre Courbot <[email protected]>Reviewed-by Benno Lossin <[email protected]>Quoted 12 lines
--- rust/kernel/revocable.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+)rust/kernel/revocable.rs +0
-0@@ -123,6 +123,22 @@ pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a } }
Quoted 15 lines
rust/kernel/revocable.rs pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a · line 137
Quoted 12 lines
rust/kernel/revocable.rs +12
-0+/// Tries to access the wrapped object and run a closure on it while the guard is held. +/// +/// This is a convenience method to run short non-sleepable code blocks while ensuring the +/// guard is dropped afterwards. [`Self::try_access`] carries the risk that the caller will +/// forget to explicitly drop that returned guard before calling sleepable code; this method +/// adds an extra safety to make sure it doesn't happen. +/// +/// Returns `None` if the object has been revoked and is therefore no longer accessible, or the +/// result of the closure wrapped in `Some`. If the closure returns a [`Result`] then the +/// return type becomes `Option<Result<>>`, which can be inconvenient. Users are encouraged to +/// define their own macro that turns the `Option` into a proper error code and flattens the +/// inner result into it if it makes sense within their subsystem. I personally wouldn't have mentioned this in the docs, since to me such a helper would be obvious, but I don't mind it either.
Using a helper did not immediately occur to me, which is why I came with two different methods initially. I'm fine with removing this part of the doc if it sounds like it is overstepping the purpose of documentation tough.
Alexandre Courbot
reviewerPATCH v3 2/2 samples: rust: convert PCI rust sample driver to use try_access_with()
In reply to Alexandre CourbotThis method limits the scope of the revocable guard and is considered safer to use for most cases, so let's showcase it here.
--- samples/rust/rust_driver_pci.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-)
samples/rust/rust_driver_pci.rs +5 -6
@@ -83,13 +83,12 @@ fn probe(pdev: &mut pci::Device, info: &Self::IdInfo) -> Result<Pin<KBox<Self>>> GFP_KERNEL, )?; -let bar = drvdata.bar.try_access ().ok_or (ENXIO )?; +let res = drvdata + .bar + .try_access_with (|b|Self ::testdev (info, b)) + .ok_or (ENXIO )??; -dev_info! ( - pdev.as_ref (), -"pci-testdev data-match count: {}\n" , -Self ::testdev (info, &bar)? - ); +dev_info! (pdev.as_ref (),"pci-testdev data-match count: {}\n" , res);Ok (drvdata.into ()) }
Signature · 1 line
2.49.0
Re: [PATCH v3 2/2] samples: rust: convert PCI rust sample driver to use try_access_with()
Quoted 5 lines · Alexandre Courbot
This method limits the scope of the revocable guard and is considered safer to use for most cases, so let's showcase it here.
Acked-by Danilo Krummrich <[email protected]>Signed-off-by Alexandre Courbot <[email protected]>
---
Cheers,
Benno
Quoted 27 lines
--- samples/rust/rust_driver_pci.rs | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-)samples/rust/rust_driver_pci.rs +5
-6@@ -83,13 +83,12 @@ fn probe(pdev: &mut pci::Device, info: &Self::IdInfo) -> Result<Pin<KBox<Self>>> GFP_KERNEL, )?; -let bar = drvdata.bar.try_access ().ok_or (ENXIO )?; +let res = drvdata + .bar + .try_access_with (|b|Self ::testdev (info, b)) + .ok_or (ENXIO )??; -dev_info! ( - pdev.as_ref (), -"pci-testdev data-match count: {}\n" , -Self ::testdev (info, &bar)? - ); +dev_info! (pdev.as_ref (),"pci-testdev data-match count: {}\n" , res);Ok (drvdata.into ()) }