Skip to contentSkip to conversation

rust: impl_flags: add method to return underlying integer

PATCH Superseded Andreas Hindborg 3 participants 4 messages Jun 5 – Jun 7 Rust

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Andreas Hindborg

author reviewer
#0 lore raw

PATCH v2 1/1 rust: impl_flags: add method to return underlying integer

Add a bits method to return a copy of the underlying integer used to represent the flags. This is useful when passing flag values to C APIs.

The visibility of the generated bits method is controlled by an optional visibility specifier in the inner-field position of the bitmask struct declaration. Write pub there (e.g., pub struct Foo(pub u32)) to make bits callable from outside the defining module; omit it to keep the bit pattern hidden.

---
@Daniel, I dropped your tag since the patch changed a bit.

Changes in v2:
- Rename the accessor from into_inner to bits, matching the
name used by the bitflags crate (Gary).
- Tie the visibility of bits to the visibility of the inner
field of the bitmask struct, so callers must explicitly write
pub to expose the bit pattern outside the defining module (Gary).
- Extend the macro's doctest to declare the inner field pub
and exercise the bits accessor.
- Link to v1: https://msgid.link/[email protected]

To: Miguel Ojeda <[email protected]>
To: Boqun Feng <[email protected]>
To: Gary Guo <[email protected]>
To: Björn Roy Baron <[email protected]>
To: Benno Lossin <[email protected]>
To: Andreas Hindborg <[email protected]>
To: Alice Ryhl <[email protected]>
To: Trevor Gross <[email protected]>
To: Danilo Krummrich <[email protected]>
Cc: [email protected]
Cc: [email protected]

---
 rust/kernel/impl_flags.rs | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)
rust/kernel/impl_flags.rs +25 -2
index e2bd7639da12..1d39d54540dc 100644
@@ -16,6 +16,12 @@
 ///   ([`::core::ops::BitOr`], [`::core::ops::BitAnd`], etc.).
 /// - Utility methods such as `.contains()` to check flags.
 ///
+/// An optional visibility specifier in the inner-field position of the
+/// bitmask struct controls the visibility of the generated `bits`
+/// accessor. Declare it `pub` (e.g., `pub struct Permissions(pub u32)`)
+/// to expose the raw integer outside the defining module — useful when
+/// passing the value to C APIs. Omit it to keep `bits` private.
+///
 /// # Examples
 ///
 /// ```
@@ -24,7 +30,7 @@
 /// impl_flags!(
 ///     /// Represents multiple permissions.
 ///     #[derive(Debug, Clone, Default, Copy, PartialEq, Eq)]
-///     pub struct Permissions(u32);
+///     pub struct Permissions(pub u32);
 ///
 ///     /// Represents a single permission.
 ///     #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -65,12 +71,18 @@
 /// let negated = !read_only;
 /// assert!(negated.contains(Permission::Write));
 /// assert!(!negated.contains(Permission::Read));
+///
+/// // The `pub` in `pub struct Permissions(pub u32)` makes `bits` callable
+/// // from outside the defining module, returning the raw integer
+/// // representation — useful for passing the value to a C API.
+/// let raw: u32 = read_only.bits();
+/// assert_eq!(raw, Permission::Read as u32);
 /// ```
 #[macro_export]
 macro_rules! impl_flags {
     (
         $(#[$outer_flags:meta])*
-        $vis_flags:vis struct $flags:ident($ty:ty);
+        $vis_flags:vis struct $flags:ident($inner_vis:vis $ty:ty);
 
         $(#[$outer_flag:meta])*
         $vis_flag:vis enum $flag:ident {
@@ -267,6 +279,17 @@ pub fn contains_any(self, flags: $flags) -> bool {
             pub fn contains_all(self, flags: $flags) -> bool {
                 (self.0 & flags.0) == flags.0
             }
+
+            /// Return a copy of the inner representation of the flags.
+            ///
+            /// The visibility of this method is controlled by the optional
+            /// visibility specifier in the inner-field position of the
+            /// bitmask struct declaration.
+            #[inline]
+            #[allow(dead_code)]
+            $inner_vis fn bits(self) -> $ty {
+                self.0
+            }
         }
     };
 }

---
base-commit: 7fd2df204f342fc17d1a0bfcd474b24232fb0f32
change-id: 20260212-impl-flags-inner-c61974b27b18

Best regards,

Signature · 1 line
Andreas Hindborg <[email protected]>
#1 lore raw

rust/kernel/impl_flags.rs line 23

Quoted 6 lines · Andreas Hindborg
rust/kernel/impl_flags.rs +5 -0
+/// An optional visibility specifier in the inner-field position of the
+/// bitmask struct controls the visibility of the generated `bits`
+/// accessor. Declare it `pub` (e.g., `pub struct Permissions(pub u32)`)
+/// to expose the raw integer outside the defining module — useful when
+/// passing the value to C APIs. Omit it to keep `bits` private.

Hmm... It is clever, but it can be quite confusing. Could we use some other way of "tagging" it?

I would also put () in bits, and make it a intra-doc links, to make it extra clear it is the method we are talking about here.

And why do we call this "private", given the From as Sashiko points out?

i.e. your example works if you do (without the patch):

    /// let raw: u32 = read_only.into();
    /// assert_eq!(raw, Permission::Read as u32);

rust/kernel/impl_flags.rs line 33

Quoted 4 lines

/// /// Represents multiple permissions.
/// #[derive(Debug, Clone, Default, Copy, PartialEq, Eq)]

rust/kernel/impl_flags.rs +1 -1
-///     pub struct Permissions(u32);
+///     pub struct Permissions(pub u32);

I would prefer if we had separate examples for "optional features" like this; otherwise, people may think this is the "common" way of doing it -- and I assume in cases like this we want users to avoid exposing if not needed, no?

rust/kernel/impl_flags.rs pub fn contains_any(self, flags: $flags) -> bool { · line 287

Quoted 3 lines
rust/kernel/impl_flags.rs +3 -0
+            /// The visibility of this method is controlled by the optional
+            /// visibility specifier in the inner-field position of the
+            /// bitmask struct declaration.

I would make this paragraph a comment as Sashiko points out.

Cheers,
Miguel

reviewer
#2 lore raw
Quoted 11 lines · Miguel Ojeda

rust/kernel/impl_flags.rs line 23

Quoted 6 lines · Andreas Hindborg
rust/kernel/impl_flags.rs +5 -0
+/// An optional visibility specifier in the inner-field position of the
+/// bitmask struct controls the visibility of the generated `bits`
+/// accessor. Declare it `pub` (e.g., `pub struct Permissions(pub u32)`)
+/// to expose the raw integer outside the defining module — useful when
+/// passing the value to C APIs. Omit it to keep `bits` private.

Hmm... It is clever, but it can be quite confusing. Could we use some other way of "tagging" it?

Quoted 4 lines

I would also put () in bits, and make it a intra-doc links, to make it extra clear it is the method we are talking about here.

And why do we call this "private", given the From as Sashiko points out?

I think I suggested this approach because I don't want people to be able to easily be able to get integers while enums could be used. But I didn't know that the From impl already exists for flags.

Given the case we could probably just unconditionally expose the bits method (and whatever mechanism we use to avoid exposing bits would also remove the From/TryFrom/bits/all_bits/...)

Best,
Gary

Quoted 24 lines

i.e. your example works if you do (without the patch):

    /// let raw: u32 = read_only.into();
    /// assert_eq!(raw, Permission::Read as u32);

rust/kernel/impl_flags.rs line 33

Quoted 4 lines

/// /// Represents multiple permissions.
/// #[derive(Debug, Clone, Default, Copy, PartialEq, Eq)]

rust/kernel/impl_flags.rs +1 -1
-///     pub struct Permissions(u32);
+///     pub struct Permissions(pub u32);

I would prefer if we had separate examples for "optional features" like this; otherwise, people may think this is the "common" way of doing it -- and I assume in cases like this we want users to avoid exposing if not needed, no?

rust/kernel/impl_flags.rs pub fn contains_any(self, flags: $flags) -> bool { · line 287

Quoted 3 lines
rust/kernel/impl_flags.rs +3 -0
+            /// The visibility of this method is controlled by the optional
+            /// visibility specifier in the inner-field position of the
+            /// bitmask struct declaration.

I would make this paragraph a comment as Sashiko points out.

Cheers,
Miguel

#3 lore raw
Quoted 8 lines · Gary Guo

I think I suggested this approach because I don't want people to be able to easily be able to get integers while enums could be used. But I didn't know that the From impl already exists for flags.

Given the case we could probably just unconditionally expose the bits method (and whatever mechanism we use to avoid exposing bits would also remove the From/TryFrom/bits/all_bits/...)

I see, so having it really private. That makes more sense, including the pub word. Someone may still expect the field to be actually public, but at least it makes sense, and using enums and guiding users to avoid exposing things they don't need to expose is usually good a good principle.

Maybe another word (like your flavors in the other series :) could also work... But I don't mind pub too much if the other option is truly private.

Cheers,
Miguel