Re: [PATCH v4 03/10] rust: sync: atomic: Add ordering annotation types

[Boqun Feng <boqun.feng@gmail.com>]

On Tue, Jun 10, 2025 at 10:58:30AM -0700, Boqun Feng wrote:
> On Tue, Jun 10, 2025 at 10:30:55AM -0700, Boqun Feng wrote:
> [...]
> > > > +/// Describes the exact memory ordering of an `impl` [`All`].
> > > > +pub enum OrderingDesc {
> > > 
> > > Why not name this `Ordering`?
> > > 
> > 
> > I was trying to avoid having an `Ordering` enum in a `ordering` mod.
> > Also I want to save the name "Ordering" for the generic type parameter
> > of an atomic operation, e.g.
> > 
> >     pub fn xchg<Ordering: ALL>(..)
> > 
> > this enum is more of an internal implementation detail, and users should
> > not use this enum directly, so I would like to avoid potential
> > confusion.
> > 
> > I have played a few sealed trait tricks on my end, but seems I cannot
> > achieve:
> > 
> > 1) `OrderingDesc` is only accessible in the atomic mod.
> > 2) `All` is only impl-able in the atomic mod, while it can be used as a
> > trait bound outside kernel crate.
> > 
> > Maybe there is a trick I'm missing?
> > 
> 
> Something like this seems to work:
> 
>     pub(super) mod private {
>         /// Describes the exact memory ordering of an `impl` [`All`].
>         pub enum Ordering {
>             /// Relaxed ordering.
>             Relaxed,
>             /// Acquire ordering.
>             Acquire,
>             /// Release ordering.
>             Release,
>             /// Fully-ordered.
>             Full,
>         }
>     
>         pub trait HasOrderingDesc {
>             /// Describes the exact memory ordering.
>             const ORDERING: Ordering;
>         }
>     }
> 
>     /// The trait bound for annotating operations that should support all orderings.
>     pub trait All: private::HasOrderingDesc { }
> 
>     impl private::HasOrderingDesc for Relaxed {
>         const ORDERING: private::Ordering = private::Ordering::Relaxed;
>     }
> 
> the trick is to seal the enum and the trait together.
> 
> Regards,
> Boqun
> 
> > > > +    /// Relaxed ordering.
> > > > +    Relaxed,
> > > > +    /// Acquire ordering.
> > > > +    Acquire,
> > > > +    /// Release ordering.
> > > > +    Release,
> > > > +    /// Fully-ordered.
> > > > +    Full,
> > > > +}
> > > > +
> > > > +/// The trait bound for annotating operations that should support all orderings.
> > > > +pub trait All {
> > > > +    /// Describes the exact memory ordering.
> > > > +    const ORDER: OrderingDesc;
> > > 
> > > And then here: `ORDERING`.
> > 

After a second thought, the following is probably what I will go for:

    /// The annotation type for relaxed memory ordering.
    pub struct Relaxed;
    
    /// The annotation type for acquire memory ordering.
    pub struct Acquire;
    
    /// The annotation type for release memory ordering.
    pub struct Release;
    
    /// The annotation type for fully-order memory ordering.
    pub struct Full;

    /// Describes the exact memory ordering.
    pub enum OrderingType {
        /// Relaxed ordering.
        Relaxed,
        /// Acquire ordering.
        Acquire,
        /// Release ordering.
        Release,
        /// Fully-ordered.
        Full,
    }
    
    mod internal {
        /// Unit types for ordering annotation.
        ///
        /// Sealed trait, can be only implemented inside atomic mod.
        pub trait OrderingUnit {
            /// Describes the exact memory ordering.
            const TYPE: super::OrderingType;
        }
    }
    
    impl internal::OrderingUnit for Relaxed {
        const TYPE: OrderingType = OrderingType::Relaxed;
    }
    
    impl internal::OrderingUnit for Acquire {
        const TYPE: OrderingType = OrderingType::Acquire;
    }
    
    impl internal::OrderingUnit for Release {
        const TYPE: OrderingType = OrderingType::Release;
    }
    
    impl internal::OrderingUnit for Full {
        const TYPE: OrderingType = OrderingType::Full;
    }

That is:

1) Rename "OrderingDesc" into "OrderingType", and make it public.
2) Provide a sealed trait (`OrderingUnit`) for all the unit types
   that describe ordering.
3) Instead of "ORDER" or "ORDERING", name the enum constant "TYPE".


An example shows why is probably an xchg() implementation, if I was to
follow the previous naming suggestion, it will be:

    match Ordering::ORDERING {
        <some mode path>::Ordering::Relaxed => atomic_xchg_relaxed(...),
	...
    }

with the current one, it will be:

    match Ordering::TYPE {
        // assume we "use ordering::OrderingType"
        OrderingType::Relaxed => atomic_xchg_relaxed(...),
	...
    }

I think this version is much better.

Regards,
Boqun

> [..]