Re: [PATCH v3 1/2] rust: Add support for calling a function exactly once

[Gary Guo <gary@garyguo.net>]

On Mon, 17 Nov 2025 09:24:51 +0900
FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:

> Add the Rust equivalent of the kernel's `DO_ONCE_LITE` macro. While it
> would be possible to implement the feature entirely as a Rust macro,
> the functionality that can be implemented as regular functions has
> been extracted and implemented as the `OnceLite` struct for better
> code maintainability.
> 
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> ---
>  rust/kernel/print.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 83 insertions(+)
> 
> diff --git a/rust/kernel/print.rs b/rust/kernel/print.rs
> index 2d743d78d220..af32054be5a2 100644
> --- a/rust/kernel/print.rs
> +++ b/rust/kernel/print.rs
> @@ -11,6 +11,11 @@
>      fmt,
>      prelude::*,
>      str::RawFormatter,
> +    sync::atomic::{
> +        Atomic,
> +        AtomicType,
> +        Relaxed, //
> +    },
>  };
>  
>  // Called from `vsprintf` with format specifier `%pA`.
> @@ -423,3 +428,81 @@ macro_rules! pr_cont (
>          $crate::print_macro!($crate::print::format_strings::CONT, true, $($arg)*)
>      )
>  );
> +
> +/// A lightweight `call_once` primitive.
> +///
> +/// This structure provides the Rust equivalent of the kernel's `DO_ONCE_LITE` macro.
> +/// While it would be possible to implement the feature entirely as a Rust macro,
> +/// the functionality that can be implemented as regular functions has been
> +/// extracted and implemented as the `OnceLite` struct for better code maintainability.
> +pub struct OnceLite(Atomic<State>);
> +
> +#[derive(Clone, Copy, PartialEq, Eq)]
> +#[repr(i32)]
> +enum State {
> +    Incomplete = 0,
> +    Complete = 1,
> +}
> +
> +// SAFETY: `State` and `i32` has the same size and alignment, and it's round-trip
> +// transmutable to `i32`.
> +unsafe impl AtomicType for State {
> +    type Repr = i32;
> +}
> +
> +impl OnceLite {
> +    /// Creates a new [`OnceLite`] in the incomplete state.
> +    #[inline(always)]
> +    #[allow(clippy::new_without_default)]

Maybe put the reason too? Otherwise a reader who hasn't been following
previous discussions closely might be out of context (like me).

> +    pub const fn new() -> Self {
> +        OnceLite(Atomic::new(State::Incomplete))
> +    }
> +
> +    /// Calls the provided function exactly once.
> +    ///
> +    /// There is no other synchronization between two `call_once()`s
> +    /// except that only one will execute `f`, in other words, callers
> +    /// should not use a failed `call_once()` as a proof that another
> +    /// `call_once()` has already finished and the effect is observable
> +    /// to this thread.

Nice! Thanks for putting this in. If this this insn't in this will
definitely be misused (I won't be surprised that it'll be misused anyway
even with this, though)

Reviewed-by: Gary Guo <gary@garyguo.net>

Best,
Gary

> +    pub fn call_once<F>(&self, f: F) -> bool
> +    where
> +        F: FnOnce(),
> +    {
> +        // Avoid expensive cmpxchg if already completed.
> +        // ORDERING: `Relaxed` is used here since no synchronization is required.
> +        let old = self.0.load(Relaxed);
> +        if old == State::Complete {
> +            return false;
> +        }
> +
> +        // ORDERING: `Relaxed` is used here since no synchronization is required.
> +        let old = self.0.xchg(State::Complete, Relaxed);
> +        if old == State::Complete {
> +            return false;
> +        }
> +
> +        f();
> +        true
> +    }
> +}