ordering.rs

  1// SPDX-License-Identifier: GPL-2.0
  2
  3//! Memory orderings.
  4//!
  5//! The semantics of these orderings follows the [`LKMM`] definitions and rules.
  6//!
  7//! - [`Acquire`] provides ordering between the load part of the annotated operation and all the
  8//!   following memory accesses, and if there is a store part, the store part has the [`Relaxed`]
  9//!   ordering.
 10//! - [`Release`] provides ordering between all the preceding memory accesses and the store part of
 11//!   the annotated operation, and if there is a load part, the load part has the [`Relaxed`]
 12//!   ordering.
 13//! - [`Full`] means "fully-ordered", that is:
 14//!   - It provides ordering between all the preceding memory accesses and the annotated operation.
 15//!   - It provides ordering between the annotated operation and all the following memory accesses.
 16//!   - It provides ordering between all the preceding memory accesses and all the following memory
 17//!     accesses.
 18//!   - All the orderings are the same strength as a full memory barrier (i.e. `smp_mb()`).
 19//! - [`Relaxed`] provides no ordering except the dependency orderings. Dependency orderings are
 20//!   described in "DEPENDENCY RELATIONS" in [`LKMM`]'s [`explanation`].
 21//!
 22//! [`LKMM`]: srctree/tools/memory-model/
 23//! [`explanation`]: srctree/tools/memory-model/Documentation/explanation.txt
 24
 25/// The annotation type for relaxed memory ordering, for the description of relaxed memory
 26/// ordering, see [module-level documentation].
 27///
 28/// [module-level documentation]: crate::sync::atomic::ordering
 29pub struct Relaxed;
 30
 31/// The annotation type for acquire memory ordering, for the description of acquire memory
 32/// ordering, see [module-level documentation].
 33///
 34/// [module-level documentation]: crate::sync::atomic::ordering
 35pub struct Acquire;
 36
 37/// The annotation type for release memory ordering, for the description of release memory
 38/// ordering, see [module-level documentation].
 39///
 40/// [module-level documentation]: crate::sync::atomic::ordering
 41pub struct Release;
 42
 43/// The annotation type for fully-ordered memory ordering, for the description fully-ordered memory
 44/// ordering, see [module-level documentation].
 45///
 46/// [module-level documentation]: crate::sync::atomic::ordering
 47pub struct Full;
 48
 49/// Describes the exact memory ordering.
 50#[doc(hidden)]
 51pub enum OrderingType {
 52    /// Relaxed ordering.
 53    Relaxed,
 54    /// Acquire ordering.
 55    Acquire,
 56    /// Release ordering.
 57    Release,
 58    /// Fully-ordered.
 59    Full,
 60}
 61
 62mod internal {
 63    /// Sealed trait, can be only implemented inside atomic mod.
 64    pub trait Sealed {}
 65
 66    impl Sealed for super::Relaxed {}
 67    impl Sealed for super::Acquire {}
 68    impl Sealed for super::Release {}
 69    impl Sealed for super::Full {}
 70}
 71
 72/// The trait bound for annotating operations that support any ordering.
 73pub trait Ordering: internal::Sealed {
 74    /// Describes the exact memory ordering.
 75    const TYPE: OrderingType;
 76}
 77
 78impl Ordering for Relaxed {
 79    const TYPE: OrderingType = OrderingType::Relaxed;
 80}
 81
 82impl Ordering for Acquire {
 83    const TYPE: OrderingType = OrderingType::Acquire;
 84}
 85
 86impl Ordering for Release {
 87    const TYPE: OrderingType = OrderingType::Release;
 88}
 89
 90impl Ordering for Full {
 91    const TYPE: OrderingType = OrderingType::Full;
 92}
 93
 94/// The trait bound for operations that only support acquire or relaxed ordering.
 95pub trait AcquireOrRelaxed: Ordering {}
 96
 97impl AcquireOrRelaxed for Acquire {}
 98impl AcquireOrRelaxed for Relaxed {}
 99
100/// The trait bound for operations that only support release or relaxed ordering.
101pub trait ReleaseOrRelaxed: Ordering {}
102
103impl ReleaseOrRelaxed for Release {}
104impl ReleaseOrRelaxed for Relaxed {}