[PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
users can use Atomic<Flag> for boolean flags.

The backing integer type is an implementation detail; it is currently
i32 but may change in the future.

Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
particular, when RMW operations such as xchg()/cmpxchg() may be used
and minimizing memory usage is not the top priority. On some
architectures without byte-sized RMW instructions, Atomic<bool> can be
slower for RMW operations.

Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
---
v2:
- Update the description
- Add bidirectional From conversions between Flag and bool
- Use intra-doc links
- Fix level header for Examples
- Fix a typo
- Add a newline after the `use`s block in examples
v1: https://lore.kernel.org/rust-for-linux/20260101102718.2073674-1-fujita.tomonori@gmail.com/

rust/kernel/sync/atomic.rs | 56 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index ca9cab77abf0..473d3c07e234 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -566,3 +566,59 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
         unsafe { from_repr(ret) }
     }
 }
+
+/// An atomic flag type intended to be backed by a performance-optimal integer type.
+///
+/// The backing integer type is an implementation detail; it is currently [`i32`] but may change
+/// in the future.
+///
+/// [`Atomic<Flag>`] is generally preferable to [`Atomic<bool>`] when you need read-modify-write
+/// (RMW) operations (e.g. [`Atomic::xchg()`]/[`Atomic::cmpxchg()`]) or when [`Atomic<bool>`] does
+/// not save memory due to padding. On some architectures that do not support byte-sized atomic
+/// RMW operations, RMW operations on [`Atomic<bool>`] are slower.
+///
+/// If you only use [`Atomic::load()`]/[`Atomic::store()`], either [`Atomic<bool>`] or
+/// [`Atomic<Flag>`] is fine.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::sync::atomic::{Atomic, Flag, Relaxed};
+///
+/// let flag = Atomic::new(Flag::Clear);
+/// assert_eq!(Flag::Clear, flag.load(Relaxed));
+/// flag.store(Flag::Set, Relaxed);
+/// assert_eq!(Flag::Set, flag.load(Relaxed));
+/// ```
+#[derive(Clone, Copy, PartialEq, Eq)]
+#[repr(i32)]
+pub enum Flag {
+    /// The flag is clear.
+    Clear = 0,
+    /// The flag is set.
+    Set = 1,
+}
+
+// SAFETY: `Flag` and `i32` have the same size and alignment, and it is round-trip
+// transmutable to `i32`.
+unsafe impl AtomicType for Flag {
+    type Repr = i32;
+}
+
+impl From<Flag> for bool {
+    #[inline(always)]
+    fn from(f: Flag) -> Self {
+        f == Flag::Set
+    }
+}
+
+impl From<bool> for Flag {
+    #[inline(always)]
+    fn from(b: bool) -> Self {
+        if b {
+            Flag::Set
+        } else {
+            Flag::Clear
+        }
+    }
+}

base-commit: ae14778fbe11e7d36a616485e3148a1ca8fdc893
-- 
2.43.0

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[Alice Ryhl]

On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
<fujita.tomonori@gmail.com> wrote:
>
> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
> users can use Atomic<Flag> for boolean flags.
>
> The backing integer type is an implementation detail; it is currently
> i32 but may change in the future.
>
> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
> particular, when RMW operations such as xchg()/cmpxchg() may be used
> and minimizing memory usage is not the top priority. On some
> architectures without byte-sized RMW instructions, Atomic<bool> can be
> slower for RMW operations.
>
> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>

Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
store() methods use real booleans? Otherwise this seems inconvenient
to use.

Alice

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Thu, 8 Jan 2026 13:54:58 +0100
Alice Ryhl <aliceryhl@google.com> wrote:

> On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
> <fujita.tomonori@gmail.com> wrote:
>>
>> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>> users can use Atomic<Flag> for boolean flags.
>>
>> The backing integer type is an implementation detail; it is currently
>> i32 but may change in the future.
>>
>> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>> particular, when RMW operations such as xchg()/cmpxchg() may be used
>> and minimizing memory usage is not the top priority. On some
>> architectures without byte-sized RMW instructions, Atomic<bool> can be
>> slower for RMW operations.
>>
>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> 
> Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
> store() methods use real booleans? Otherwise this seems inconvenient
> to use.

Do you mean something along these lines?

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 473d3c07e234..19750be1a239 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
         }
     }
 }
+
+/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
+pub struct AtomicFlag(Atomic<Flag>);
+
+impl AtomicFlag {
+    /// Creates a new atomic flag.
+    pub const fn new(b: bool) -> Self {
+        if b {
+            AtomicFlag(Atomic::new(Flag::Set))
+        } else {
+            AtomicFlag(Atomic::new(Flag::Clear))
+        }
+    }
+
+    /// Loads the value from the atomic flag.
+    #[inline(always)]
+    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
+        self.0.load(o).into()
+    }
+
+    /// Stores a value to the atomic flag.
+    #[inline(always)]
+    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
+        self.0.store(b.into(), o)
+    }
+}

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Fri, 09 Jan 2026 09:36:41 +0900 (JST)
FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:

> On Thu, 8 Jan 2026 13:54:58 +0100
> Alice Ryhl <aliceryhl@google.com> wrote:
> 
>> On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
>> <fujita.tomonori@gmail.com> wrote:
>>>
>>> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>>> users can use Atomic<Flag> for boolean flags.
>>>
>>> The backing integer type is an implementation detail; it is currently
>>> i32 but may change in the future.
>>>
>>> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>>> particular, when RMW operations such as xchg()/cmpxchg() may be used
>>> and minimizing memory usage is not the top priority. On some
>>> architectures without byte-sized RMW instructions, Atomic<bool> can be
>>> slower for RMW operations.
>>>
>>> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>> 
>> Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
>> store() methods use real booleans? Otherwise this seems inconvenient
>> to use.
> 
> Do you mean something along these lines?
> 
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index 473d3c07e234..19750be1a239 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
>          }
>      }
>  }
> +
> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
> +pub struct AtomicFlag(Atomic<Flag>);
> +
> +impl AtomicFlag {
> +    /// Creates a new atomic flag.
> +    pub const fn new(b: bool) -> Self {
> +        if b {
> +            AtomicFlag(Atomic::new(Flag::Set))
> +        } else {
> +            AtomicFlag(Atomic::new(Flag::Clear))
> +        }
> +    }
> +
> +    /// Loads the value from the atomic flag.
> +    #[inline(always)]
> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
> +        self.0.load(o).into()
> +    }
> +
> +    /// Stores a value to the atomic flag.
> +    #[inline(always)]
> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
> +        self.0.store(b.into(), o)
> +    }
> +}

If you only need load/store, Atomic<bool> is fine, so if we add
`AtomicFlag`, it would be good to expose RMW operations (xchg at
least).

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[Alice Ryhl]

On Fri, Jan 09, 2026 at 09:36:41AM +0900, FUJITA Tomonori wrote:
> On Thu, 8 Jan 2026 13:54:58 +0100
> Alice Ryhl <aliceryhl@google.com> wrote:
> 
> > On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
> > <fujita.tomonori@gmail.com> wrote:
> >>
> >> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
> >> users can use Atomic<Flag> for boolean flags.
> >>
> >> The backing integer type is an implementation detail; it is currently
> >> i32 but may change in the future.
> >>
> >> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
> >> particular, when RMW operations such as xchg()/cmpxchg() may be used
> >> and minimizing memory usage is not the top priority. On some
> >> architectures without byte-sized RMW instructions, Atomic<bool> can be
> >> slower for RMW operations.
> >>
> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> > 
> > Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
> > store() methods use real booleans? Otherwise this seems inconvenient
> > to use.
> 
> Do you mean something along these lines?
> 
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index 473d3c07e234..19750be1a239 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
>          }
>      }
>  }
> +
> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
> +pub struct AtomicFlag(Atomic<Flag>);
> +
> +impl AtomicFlag {
> +    /// Creates a new atomic flag.
> +    pub const fn new(b: bool) -> Self {
> +        if b {
> +            AtomicFlag(Atomic::new(Flag::Set))
> +        } else {
> +            AtomicFlag(Atomic::new(Flag::Clear))
> +        }
> +    }
> +
> +    /// Loads the value from the atomic flag.
> +    #[inline(always)]
> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
> +        self.0.load(o).into()
> +    }
> +
> +    /// Stores a value to the atomic flag.
> +    #[inline(always)]
> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
> +        self.0.store(b.into(), o)
> +    }
> +}

Yes, that's what I meant.

Alice

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Fri, 9 Jan 2026 08:23:04 +0000
Alice Ryhl <aliceryhl@google.com> wrote:

> On Fri, Jan 09, 2026 at 09:36:41AM +0900, FUJITA Tomonori wrote:
>> On Thu, 8 Jan 2026 13:54:58 +0100
>> Alice Ryhl <aliceryhl@google.com> wrote:
>> 
>> > On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
>> > <fujita.tomonori@gmail.com> wrote:
>> >>
>> >> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>> >> users can use Atomic<Flag> for boolean flags.
>> >>
>> >> The backing integer type is an implementation detail; it is currently
>> >> i32 but may change in the future.
>> >>
>> >> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>> >> particular, when RMW operations such as xchg()/cmpxchg() may be used
>> >> and minimizing memory usage is not the top priority. On some
>> >> architectures without byte-sized RMW instructions, Atomic<bool> can be
>> >> slower for RMW operations.
>> >>
>> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>> > 
>> > Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
>> > store() methods use real booleans? Otherwise this seems inconvenient
>> > to use.
>> 
>> Do you mean something along these lines?
>> 
>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> index 473d3c07e234..19750be1a239 100644
>> --- a/rust/kernel/sync/atomic.rs
>> +++ b/rust/kernel/sync/atomic.rs
>> @@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
>>          }
>>      }
>>  }
>> +
>> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
>> +pub struct AtomicFlag(Atomic<Flag>);
>> +
>> +impl AtomicFlag {
>> +    /// Creates a new atomic flag.
>> +    pub const fn new(b: bool) -> Self {
>> +        if b {
>> +            AtomicFlag(Atomic::new(Flag::Set))
>> +        } else {
>> +            AtomicFlag(Atomic::new(Flag::Clear))
>> +        }
>> +    }
>> +
>> +    /// Loads the value from the atomic flag.
>> +    #[inline(always)]
>> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
>> +        self.0.load(o).into()
>> +    }
>> +
>> +    /// Stores a value to the atomic flag.
>> +    #[inline(always)]
>> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
>> +        self.0.store(b.into(), o)
>> +    }
>> +}
> 
> Yes, that's what I meant.

Thanks for confirming. I'll add in v3.

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[Alice Ryhl]

On Sat, Jan 10, 2026 at 1:48 PM FUJITA Tomonori
<fujita.tomonori@gmail.com> wrote:
>
> On Fri, 9 Jan 2026 08:23:04 +0000
> Alice Ryhl <aliceryhl@google.com> wrote:
>
> > On Fri, Jan 09, 2026 at 09:36:41AM +0900, FUJITA Tomonori wrote:
> >> On Thu, 8 Jan 2026 13:54:58 +0100
> >> Alice Ryhl <aliceryhl@google.com> wrote:
> >>
> >> > On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
> >> > <fujita.tomonori@gmail.com> wrote:
> >> >>
> >> >> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
> >> >> users can use Atomic<Flag> for boolean flags.
> >> >>
> >> >> The backing integer type is an implementation detail; it is currently
> >> >> i32 but may change in the future.
> >> >>
> >> >> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
> >> >> particular, when RMW operations such as xchg()/cmpxchg() may be used
> >> >> and minimizing memory usage is not the top priority. On some
> >> >> architectures without byte-sized RMW instructions, Atomic<bool> can be
> >> >> slower for RMW operations.
> >> >>
> >> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
> >> >
> >> > Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
> >> > store() methods use real booleans? Otherwise this seems inconvenient
> >> > to use.
> >>
> >> Do you mean something along these lines?
> >>
> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> >> index 473d3c07e234..19750be1a239 100644
> >> --- a/rust/kernel/sync/atomic.rs
> >> +++ b/rust/kernel/sync/atomic.rs
> >> @@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
> >>          }
> >>      }
> >>  }
> >> +
> >> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
> >> +pub struct AtomicFlag(Atomic<Flag>);
> >> +
> >> +impl AtomicFlag {
> >> +    /// Creates a new atomic flag.
> >> +    pub const fn new(b: bool) -> Self {
> >> +        if b {
> >> +            AtomicFlag(Atomic::new(Flag::Set))
> >> +        } else {
> >> +            AtomicFlag(Atomic::new(Flag::Clear))
> >> +        }
> >> +    }
> >> +
> >> +    /// Loads the value from the atomic flag.
> >> +    #[inline(always)]
> >> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
> >> +        self.0.load(o).into()
> >> +    }
> >> +
> >> +    /// Stores a value to the atomic flag.
> >> +    #[inline(always)]
> >> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
> >> +        self.0.store(b.into(), o)
> >> +    }
> >> +}
> >
> > Yes, that's what I meant.
>
> Thanks for confirming. I'll add in v3.

I guess another good use-case could be `AtomicTracker` in
rust/kernel/list/arc.rs

Re: [PATCH v2] rust: sync: atomic: Add i32-backed Flag for atomic booleans

[FUJITA Tomonori]

On Sat, 10 Jan 2026 15:18:41 +0100
Alice Ryhl <aliceryhl@google.com> wrote:

> On Sat, Jan 10, 2026 at 1:48 PM FUJITA Tomonori
> <fujita.tomonori@gmail.com> wrote:
>>
>> On Fri, 9 Jan 2026 08:23:04 +0000
>> Alice Ryhl <aliceryhl@google.com> wrote:
>>
>> > On Fri, Jan 09, 2026 at 09:36:41AM +0900, FUJITA Tomonori wrote:
>> >> On Thu, 8 Jan 2026 13:54:58 +0100
>> >> Alice Ryhl <aliceryhl@google.com> wrote:
>> >>
>> >> > On Thu, Jan 8, 2026 at 1:50 PM FUJITA Tomonori
>> >> > <fujita.tomonori@gmail.com> wrote:
>> >> >>
>> >> >> Add a new Flag enum (Clear/Set) and implement AtomicType for it, so
>> >> >> users can use Atomic<Flag> for boolean flags.
>> >> >>
>> >> >> The backing integer type is an implementation detail; it is currently
>> >> >> i32 but may change in the future.
>> >> >>
>> >> >> Document when Atomic<Flag> is generally preferable to Atomic<bool>: in
>> >> >> particular, when RMW operations such as xchg()/cmpxchg() may be used
>> >> >> and minimizing memory usage is not the top priority. On some
>> >> >> architectures without byte-sized RMW instructions, Atomic<bool> can be
>> >> >> slower for RMW operations.
>> >> >>
>> >> >> Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
>> >> >
>> >> > Can we have a `struct AtomicFlag(Atomic<Flag>)` here whose load() /
>> >> > store() methods use real booleans? Otherwise this seems inconvenient
>> >> > to use.
>> >>
>> >> Do you mean something along these lines?
>> >>
>> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> >> index 473d3c07e234..19750be1a239 100644
>> >> --- a/rust/kernel/sync/atomic.rs
>> >> +++ b/rust/kernel/sync/atomic.rs
>> >> @@ -622,3 +622,29 @@ fn from(b: bool) -> Self {
>> >>          }
>> >>      }
>> >>  }
>> >> +
>> >> +/// A convenience wrapper around [`Atomic<Flag>`] that exposes a `bool` API.
>> >> +pub struct AtomicFlag(Atomic<Flag>);
>> >> +
>> >> +impl AtomicFlag {
>> >> +    /// Creates a new atomic flag.
>> >> +    pub const fn new(b: bool) -> Self {
>> >> +        if b {
>> >> +            AtomicFlag(Atomic::new(Flag::Set))
>> >> +        } else {
>> >> +            AtomicFlag(Atomic::new(Flag::Clear))
>> >> +        }
>> >> +    }
>> >> +
>> >> +    /// Loads the value from the atomic flag.
>> >> +    #[inline(always)]
>> >> +    pub fn load<Ordering: ordering::AcquireOrRelaxed>(&self, o: Ordering) -> bool {
>> >> +        self.0.load(o).into()
>> >> +    }
>> >> +
>> >> +    /// Stores a value to the atomic flag.
>> >> +    #[inline(always)]
>> >> +    pub fn store<Ordering: ordering::ReleaseOrRelaxed>(&self, b: bool, o: Ordering) {
>> >> +        self.0.store(b.into(), o)
>> >> +    }
>> >> +}
>> >
>> > Yes, that's what I meant.
>>
>> Thanks for confirming. I'll add in v3.
> 
> I guess another good use-case could be `AtomicTracker` in
> rust/kernel/list/arc.rs

Boqun, maybe we should drop the already-merged patch below from the
rust-sync branch to keep the history clean?

commit 323e4bfcbe2dc6c6cac6e007dded0ba4f89a6458
Author: FUJITA Tomonori <fujita.tomonori@gmail.com>
Date:   Tue Dec 30 18:37:17 2025 +0900

    rust: list: Switch to kernel::sync atomic primitives

    Convert uses of `AtomicBool` to `Atomic<bool>`.