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

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

[FUJITA Tomonori]

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

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>
---
 rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
index 4aebeacb961a..d98ab51ae4fc 100644
--- a/rust/kernel/sync/atomic.rs
+++ b/rust/kernel/sync/atomic.rs
@@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
         unsafe { from_repr(ret) }
     }
 }
+
+/// An atomic flag type backed by `i32`.
+///
+/// `Atomic<Flag>` is generally preferable when you need an atomic boolean and you may use
+/// read-modify-write operations (e.g. `xchg()`/`cmpxchg()`), and when minimizing memory usage is
+/// not the top priority.
+///
+/// `Atomic<bool>` is backed by `u8`. On some architectures that do not support byte-sized RMW
+/// instructions, this can make RMW operations slower.
+///
+/// If you only use `load()`/`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` has the same size and alignment, and it's round-trip
+// transmutable to `i32`.
+unsafe impl AtomicType for Flag {
+    type Repr = i32;
+}

base-commit: dafb6d4cabd044ccd7e49cea29363e8526edc071
-- 
2.43.0

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

[Gary Guo]

On Thu,  1 Jan 2026 19:27:18 +0900
FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:

> Add a new Flag enum (Clear/Set) with #[repr(i32)] and implement
> AtomicType for it, so users can use Atomic<Flag> for boolean flags.
> 
> 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>
> ---
>  rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 
> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> index 4aebeacb961a..d98ab51ae4fc 100644
> --- a/rust/kernel/sync/atomic.rs
> +++ b/rust/kernel/sync/atomic.rs
> @@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>          unsafe { from_repr(ret) }
>      }
>  }
> +
> +/// An atomic flag type backed by `i32`.

I would recommend that we document that the backing type is the
(perf-)optimal type on the target architecure, so arch can decide to use
i8 as backing type if they prefer.

> +///
> +/// `Atomic<Flag>` is generally preferable when you need an atomic boolean and you may use
> +/// read-modify-write operations (e.g. `xchg()`/`cmpxchg()`), and when minimizing memory usage is
> +/// not the top priority.
> +///
> +/// `Atomic<bool>` is backed by `u8`. On some architectures that do not support byte-sized RMW
> +/// instructions, this can make RMW operations slower.
> +///
> +/// If you only use `load()`/`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,
> +}

Maybe add `From` impls that convert this type to boolean?

Best,
Gary

> +
> +// SAFETY: `Flag` and `i32` has the same size and alignment, and it's round-trip
> +// transmutable to `i32`.
> +unsafe impl AtomicType for Flag {
> +    type Repr = i32;
> +}
> 
> base-commit: dafb6d4cabd044ccd7e49cea29363e8526edc071

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

[FUJITA Tomonori]

On Thu, 1 Jan 2026 21:04:30 +0000
Gary Guo <gary@garyguo.net> wrote:

> On Thu,  1 Jan 2026 19:27:18 +0900
> FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:
> 
>> Add a new Flag enum (Clear/Set) with #[repr(i32)] and implement
>> AtomicType for it, so users can use Atomic<Flag> for boolean flags.
>> 
>> 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>
>> ---
>>  rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
>>  1 file changed, 35 insertions(+)
>> 
>> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> index 4aebeacb961a..d98ab51ae4fc 100644
>> --- a/rust/kernel/sync/atomic.rs
>> +++ b/rust/kernel/sync/atomic.rs
>> @@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>>          unsafe { from_repr(ret) }
>>      }
>>  }
>> +
>> +/// An atomic flag type backed by `i32`.
> 
> I would recommend that we document that the backing type is the
> (perf-)optimal type on the target architecure, so arch can decide to use
> i8 as backing type if they prefer.

I'm not sure I fully understand the intent yet.

Do you mean we should document Flag as being backed by the
(perf-)optimal integer type for the target architecture, so that the
backing type can remain an implementation detail and potentially be
selected per-arch (e.g. i8 on x86) via cfg?


>> +/// `Atomic<Flag>` is generally preferable when you need an atomic boolean and you may use
>> +/// read-modify-write operations (e.g. `xchg()`/`cmpxchg()`), and when minimizing memory usage is
>> +/// not the top priority.
>> +///
>> +/// `Atomic<bool>` is backed by `u8`. On some architectures that do not support byte-sized RMW
>> +/// instructions, this can make RMW operations slower.
>> +///
>> +/// If you only use `load()`/`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,
>> +}
> 
> Maybe add `From` impls that convert this type to boolean?

Yeah, that sounds like a good addition.

+
+impl From<Flag> for bool {
+    fn from(f: Flag) -> Self {
+        f == Flag::Set
+    }
+}

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

[Gary Guo]

On Sat, 03 Jan 2026 19:44:48 +0900 (JST)
FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:

> On Thu, 1 Jan 2026 21:04:30 +0000
> Gary Guo <gary@garyguo.net> wrote:
> 
> > On Thu,  1 Jan 2026 19:27:18 +0900
> > FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:
> >   
> >> Add a new Flag enum (Clear/Set) with #[repr(i32)] and implement
> >> AtomicType for it, so users can use Atomic<Flag> for boolean flags.
> >> 
> >> 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>
> >> ---
> >>  rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
> >>  1 file changed, 35 insertions(+)
> >> 
> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> >> index 4aebeacb961a..d98ab51ae4fc 100644
> >> --- a/rust/kernel/sync/atomic.rs
> >> +++ b/rust/kernel/sync/atomic.rs
> >> @@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
> >>          unsafe { from_repr(ret) }
> >>      }
> >>  }
> >> +
> >> +/// An atomic flag type backed by `i32`.  
> > 
> > I would recommend that we document that the backing type is the
> > (perf-)optimal type on the target architecure, so arch can decide to use
> > i8 as backing type if they prefer.  
> 
> I'm not sure I fully understand the intent yet.
> 
> Do you mean we should document Flag as being backed by the
> (perf-)optimal integer type for the target architecture, so that the
> backing type can remain an implementation detail and potentially be
> selected per-arch (e.g. i8 on x86) via cfg?

Yes, I don't want anyone to rely on it being i32 (at least for now, before
a concrete use case of doing so appears).

> 
> Yeah, that sounds like a good addition.
> 
> +
> +impl From<Flag> for bool {
> +    fn from(f: Flag) -> Self {
> +        f == Flag::Set
> +    }
> +}

A `#[inline]` is warranted here. Also, it'll be good to have the
conversion for the other direction too.

Best,
Gary

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

[FUJITA Tomonori]

On Sat, 3 Jan 2026 19:05:10 +0000
Gary Guo <gary@garyguo.net> wrote:

> On Sat, 03 Jan 2026 19:44:48 +0900 (JST)
> FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:
> 
>> On Thu, 1 Jan 2026 21:04:30 +0000
>> Gary Guo <gary@garyguo.net> wrote:
>> 
>> > On Thu,  1 Jan 2026 19:27:18 +0900
>> > FUJITA Tomonori <fujita.tomonori@gmail.com> wrote:
>> >   
>> >> Add a new Flag enum (Clear/Set) with #[repr(i32)] and implement
>> >> AtomicType for it, so users can use Atomic<Flag> for boolean flags.
>> >> 
>> >> 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>
>> >> ---
>> >>  rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
>> >>  1 file changed, 35 insertions(+)
>> >> 
>> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
>> >> index 4aebeacb961a..d98ab51ae4fc 100644
>> >> --- a/rust/kernel/sync/atomic.rs
>> >> +++ b/rust/kernel/sync/atomic.rs
>> >> @@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
>> >>          unsafe { from_repr(ret) }
>> >>      }
>> >>  }
>> >> +
>> >> +/// An atomic flag type backed by `i32`.  
>> > 
>> > I would recommend that we document that the backing type is the
>> > (perf-)optimal type on the target architecure, so arch can decide to use
>> > i8 as backing type if they prefer.  
>> 
>> I'm not sure I fully understand the intent yet.
>> 
>> Do you mean we should document Flag as being backed by the
>> (perf-)optimal integer type for the target architecture, so that the
>> backing type can remain an implementation detail and potentially be
>> selected per-arch (e.g. i8 on x86) via cfg?
> 
> Yes, I don't want anyone to rely on it being i32 (at least for now, before
> a concrete use case of doing so appears).

I see, the following comment works for you?

I thought Boqun had Revocable in mind as the intended use case.

/// An atomic flag type.
///
/// This type is a performance-oriented boolean for atomic operations.
/// The integer type used as the backing representation is an implementation detail, selected to
/// be (perf-)optimal for the target architecture.
///
/// Currently, [`Flag`] uses an `i32` representation. This is because, on some architectures that
/// do not support byte-sized atomic read-modify-write operations, RMW operations (e.g.
/// `xchg()`/`cmpxchg()`) on `Atomic<bool>` can be slower than those on `Atomic<Flag>`.
///
/// If you only use `load()`/`store()`, either `Atomic<bool>` or `Atomic<Flag>` is fine.

>> Yeah, that sounds like a good addition.
>> 
>> +
>> +impl From<Flag> for bool {
>> +    fn from(f: Flag) -> Self {
>> +        f == Flag::Set
>> +    }
>> +}
> 
> A `#[inline]` is warranted here. Also, it'll be good to have the
> conversion for the other direction too.

Of course.

+
+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
+        }
+    }
+}

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

[Boqun Feng]

On Sun, Jan 04, 2026 at 06:53:11AM +0900, FUJITA Tomonori wrote:
[...]
> >> >   
> >> >> Add a new Flag enum (Clear/Set) with #[repr(i32)] and implement
> >> >> AtomicType for it, so users can use Atomic<Flag> for boolean flags.
> >> >> 
> >> >> 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>
> >> >> ---
> >> >>  rust/kernel/sync/atomic.rs | 35 +++++++++++++++++++++++++++++++++++
> >> >>  1 file changed, 35 insertions(+)
> >> >> 
> >> >> diff --git a/rust/kernel/sync/atomic.rs b/rust/kernel/sync/atomic.rs
> >> >> index 4aebeacb961a..d98ab51ae4fc 100644
> >> >> --- a/rust/kernel/sync/atomic.rs
> >> >> +++ b/rust/kernel/sync/atomic.rs
> >> >> @@ -560,3 +560,38 @@ pub fn fetch_add<Rhs, Ordering: ordering::Ordering>(&self, v: Rhs, _: Ordering)
> >> >>          unsafe { from_repr(ret) }
> >> >>      }
> >> >>  }
> >> >> +
> >> >> +/// An atomic flag type backed by `i32`.  
> >> > 
> >> > I would recommend that we document that the backing type is the
> >> > (perf-)optimal type on the target architecure, so arch can decide to use
> >> > i8 as backing type if they prefer.  
> >> 
> >> I'm not sure I fully understand the intent yet.
> >> 
> >> Do you mean we should document Flag as being backed by the
> >> (perf-)optimal integer type for the target architecture, so that the
> >> backing type can remain an implementation detail and potentially be
> >> selected per-arch (e.g. i8 on x86) via cfg?
> > 
> > Yes, I don't want anyone to rely on it being i32 (at least for now, before
> > a concrete use case of doing so appears).
> 
> I see, the following comment works for you?
> 
> I thought Boqun had Revocable in mind as the intended use case.
> 

Right, but To me, the most important thing is avoiding the misuse of
Atomic<bool>. A few cases when using Atomic<bool> is not recommended:

* when RmW operations can happen
* when using Atomic<bool> doesn't save memory (because of padding), e.g.
  SomeData(Atomic<bool>, i32)

hence the need of Atomic<Flag>. Therefore Atomic<Flag> needs to be:

1. performing better in contented cases than Atomic<bool>
2. maybe costing more memory than Atomic<bool> because of 1

in that sense, I think Gary's suggestion is reasonable (of course,
whether the space optimization of Atomic<Flag> has any actual value
remains to see, but it won't hurt to start with the possiblity).

FWIW, another usage is for call_once() where you want to use bool for
x86 and i32 for riscv, because using bool on riscv can actually cost
more memory.

[1}: https://lore.kernel.org/rust-for-linux/Zy_oj_k-qUPLSVEr@tardis.local/

Regards,
Boqun

> /// An atomic flag type.
> ///
> /// This type is a performance-oriented boolean for atomic operations.
> /// The integer type used as the backing representation is an implementation detail, selected to
> /// be (perf-)optimal for the target architecture.
> ///
> /// Currently, [`Flag`] uses an `i32` representation. This is because, on some architectures that
> /// do not support byte-sized atomic read-modify-write operations, RMW operations (e.g.
> /// `xchg()`/`cmpxchg()`) on `Atomic<bool>` can be slower than those on `Atomic<Flag>`.
> ///
> /// If you only use `load()`/`store()`, either `Atomic<bool>` or `Atomic<Flag>` is fine.
> 
[...]

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

[Miguel Ojeda]

On Thu, Jan 1, 2026 at 11:27 AM FUJITA Tomonori
<fujita.tomonori@gmail.com> wrote:
>
> +/// An atomic flag type backed by `i32`.

A few nits I noticed while reading the thread: intra-doc links where
possible/simple, i.e. if some of them require something involved to
make them work, please ignore it!

> +/// ## Examples

First level header, i.e. `#`.

> +/// use kernel::sync::atomic::{Atomic, Flag, Relaxed};
> +/// let flag = Atomic::new(Flag::Clear);

Generally we leave a newline after the `use`s block in examples.

Thanks!

Cheers,
Miguel

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

[FUJITA Tomonori]

On Sun, 4 Jan 2026 13:07:26 +0100
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:

> On Thu, Jan 1, 2026 at 11:27 AM FUJITA Tomonori
> <fujita.tomonori@gmail.com> wrote:
>>
>> +/// An atomic flag type backed by `i32`.
> 
> A few nits I noticed while reading the thread: intra-doc links where
> possible/simple, i.e. if some of them require something involved to
> make them work, please ignore it!

Ah, good catch. I overlooked that. I'll fix.


>> +/// ## Examples
> 
> First level header, i.e. `#`.

Sorry, will fix.

>> +/// use kernel::sync::atomic::{Atomic, Flag, Relaxed};
>> +/// let flag = Atomic::new(Flag::Clear);
> 
> Generally we leave a newline after the `use`s block in examples.

Understood, will add a blank line.

Thanks for the review!