From: "Vincenzo Palazzo" <vincenzopalazzodev@gmail.com>
To: "Wedson Almeida Filho" <wedsonaf@gmail.com>,
<rust-for-linux@vger.kernel.org>
Cc: "Miguel Ojeda" <ojeda@kernel.org>,
"Alex Gaynor" <alex.gaynor@gmail.com>,
"Boqun Feng" <boqun.feng@gmail.com>,
"Gary Guo" <gary@garyguo.net>,
"Björn Roy Baron" <bjorn3_gh@protonmail.com>,
linux-kernel@vger.kernel.org
Subject: Re: [PATCH 1/5] rust: types: introduce `ScopeGuard`
Date: Sat, 28 Jan 2023 11:38:36 +0100 [thread overview]
Message-ID: <CQ3RBI3EBELP.206VKZ8X6P301@vincent> (raw)
In-Reply-To: <20230119174036.64046-1-wedsonaf@gmail.com>
On Thu Jan 19, 2023 at 6:40 PM CET, Wedson Almeida Filho wrote:
> This allows us to run some code when the guard is dropped (e.g.,
> implicitly when it goes out of scope). We can also prevent the
> guard from running by calling its `dismiss()` method.
>
> Signed-off-by: Wedson Almeida Filho <wedsonaf@gmail.com>
> ---
Reviewed-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
> rust/kernel/types.rs | 127 ++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 126 insertions(+), 1 deletion(-)
>
> diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
> index e84e51ec9716..f0ad4472292d 100644
> --- a/rust/kernel/types.rs
> +++ b/rust/kernel/types.rs
> @@ -2,7 +2,132 @@
>
> //! Kernel types.
>
> -use core::{cell::UnsafeCell, mem::MaybeUninit};
> +use alloc::boxed::Box;
> +use core::{
> + cell::UnsafeCell,
> + mem::MaybeUninit,
> + ops::{Deref, DerefMut},
> +};
> +
> +/// Runs a cleanup function/closure when dropped.
> +///
> +/// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
> +///
> +/// # Examples
> +///
> +/// In the example below, we have multiple exit paths and we want to log regardless of which one is
> +/// taken:
> +/// ```
> +/// # use kernel::ScopeGuard;
> +/// fn example1(arg: bool) {
> +/// let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
> +///
> +/// if arg {
> +/// return;
> +/// }
> +///
> +/// pr_info!("Do something...\n");
> +/// }
> +///
> +/// # example1(false);
> +/// # example1(true);
> +/// ```
> +///
> +/// In the example below, we want to log the same message on all early exits but a different one on
> +/// the main exit path:
> +/// ```
> +/// # use kernel::ScopeGuard;
> +/// fn example2(arg: bool) {
> +/// let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
> +///
> +/// if arg {
> +/// return;
> +/// }
> +///
> +/// // (Other early returns...)
> +///
> +/// log.dismiss();
> +/// pr_info!("example2 no early return\n");
> +/// }
> +///
> +/// # example2(false);
> +/// # example2(true);
> +/// ```
> +///
> +/// In the example below, we need a mutable object (the vector) to be accessible within the log
> +/// function, so we wrap it in the [`ScopeGuard`]:
> +/// ```
> +/// # use kernel::ScopeGuard;
> +/// fn example3(arg: bool) -> Result {
> +/// let mut vec =
> +/// ScopeGuard::new_with_data(Vec::new(), |v| pr_info!("vec had {} elements\n", v.len()));
> +///
> +/// vec.try_push(10u8)?;
> +/// if arg {
> +/// return Ok(());
> +/// }
> +/// vec.try_push(20u8)?;
> +/// Ok(())
> +/// }
> +///
> +/// # assert_eq!(example3(false), Ok(()));
> +/// # assert_eq!(example3(true), Ok(()));
> +/// ```
> +///
> +/// # Invariants
> +///
> +/// The value stored in the struct is nearly always `Some(_)`, except between
> +/// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value
> +/// will have been returned to the caller. Since [`ScopeGuard::dismiss`] consumes the guard,
> +/// callers won't be able to use it anymore.
> +pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
> +
> +impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
> + /// Creates a new guarded object wrapping the given data and with the given cleanup function.
> + pub fn new_with_data(data: T, cleanup_func: F) -> Self {
> + // INVARIANT: The struct is being initialised with `Some(_)`.
> + Self(Some((data, cleanup_func)))
> + }
> +
> + /// Prevents the cleanup function from running and returns the guarded data.
> + pub fn dismiss(mut self) -> T {
> + // INVARIANT: This is the exception case in the invariant; it is not visible to callers
> + // because this function consumes `self`.
> + self.0.take().unwrap().0
> + }
> +}
> +
> +impl ScopeGuard<(), Box<dyn FnOnce(())>> {
> + /// Creates a new guarded object with the given cleanup function.
> + pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
> + ScopeGuard::new_with_data((), move |_| cleanup())
> + }
> +}
> +
> +impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
> + type Target = T;
> +
> + fn deref(&self) -> &T {
> + // The type invariants guarantee that `unwrap` will succeed.
> + &self.0.as_ref().unwrap().0
> + }
> +}
> +
> +impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
> + fn deref_mut(&mut self) -> &mut T {
> + // The type invariants guarantee that `unwrap` will succeed.
> + &mut self.0.as_mut().unwrap().0
> + }
> +}
> +
> +impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
> + fn drop(&mut self) {
> + // Run the cleanup function if one is still present.
> + if let Some((data, cleanup)) = self.0.take() {
> + cleanup(data)
> + }
> + }
> +}
>
> /// Stores an opaque value.
> ///
> --
> 2.34.1
prev parent reply other threads:[~2023-01-28 10:38 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-19 17:40 [PATCH 1/5] rust: types: introduce `ScopeGuard` Wedson Almeida Filho
2023-01-19 17:40 ` [PATCH 2/5] rust: types: introduce `ForeignOwnable` Wedson Almeida Filho
2023-01-20 19:59 ` Boqun Feng
2023-01-22 6:34 ` Wedson Almeida Filho
2023-01-27 13:55 ` Gary Guo
2023-01-30 5:59 ` Wedson Almeida Filho
2023-01-28 10:42 ` Vincenzo Palazzo
2023-01-28 14:53 ` Martin Rodriguez Reboredo
2023-01-28 17:05 ` Boqun Feng
2023-01-28 20:46 ` Martin Rodriguez Reboredo
2023-01-28 22:07 ` Boqun Feng
2023-01-29 3:52 ` Martin Rodriguez Reboredo
2023-01-19 17:40 ` [PATCH 3/5] rust: types: implement `ForeignOwnable` for `Box<T>` Wedson Almeida Filho
2023-01-27 13:56 ` Gary Guo
2023-01-28 10:50 ` Vincenzo Palazzo
2023-01-30 5:33 ` Alice Ferrazzi
2023-01-19 17:40 ` [PATCH 4/5] rust: types: implement `ForeignOwnable` for the unit type Wedson Almeida Filho
2023-01-27 14:03 ` Gary Guo
2023-01-27 14:11 ` Miguel Ojeda
2023-01-28 11:13 ` Vincenzo Palazzo
2023-01-30 17:21 ` Miguel Ojeda
2023-01-30 5:55 ` Wedson Almeida Filho
2023-01-28 11:14 ` Vincenzo Palazzo
2023-01-19 17:40 ` [PATCH 5/5] rust: types: implement `ForeignOwnable` for `Arc<T>` Wedson Almeida Filho
2023-01-27 14:04 ` Gary Guo
2023-01-28 11:15 ` Vincenzo Palazzo
2023-01-30 5:35 ` Alice Ferrazzi
2023-01-20 6:23 ` [PATCH 1/5] rust: types: introduce `ScopeGuard` Boqun Feng
2023-01-22 6:31 ` Wedson Almeida Filho
2023-01-28 10:38 ` Vincenzo Palazzo [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CQ3RBI3EBELP.206VKZ8X6P301@vincent \
--to=vincenzopalazzodev@gmail.com \
--cc=alex.gaynor@gmail.com \
--cc=bjorn3_gh@protonmail.com \
--cc=boqun.feng@gmail.com \
--cc=gary@garyguo.net \
--cc=linux-kernel@vger.kernel.org \
--cc=ojeda@kernel.org \
--cc=rust-for-linux@vger.kernel.org \
--cc=wedsonaf@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).