Struct RelaxedAtomic 

pub struct RelaxedAtomic<T: AtomicRepr> { /* private fields */ }

Provides inner mutability for Copy types via relaxed atomic operations.

On x86_64 and ARM, relaxed loads and stores compile to the same instructions as regular memory accesses — no LOCK prefix is emitted. This makes RelaxedAtomic a zero-overhead way to achieve interior mutability without the bus-lock cost of fetch_* or CAS operations.

Deliberately exposes only load and store. The fetch_* methods are omitted because they emit LOCK-prefixed instructions with measurable overhead. Instead, use the load–mutate–store pattern:

let counter = RelaxedAtomic::new(0u32);
let val = counter.load();
counter.store(val + 1);

When to use

Use when a field needs interior mutability and is accessed without contention (same pattern as the original C code using plain loads/stores). If you need multi-step atomic operations (CAS, fetch_add), use the underlying std::sync::atomic types directly.

When not to use

Do not use when the operation must be atomic relative to other threads. The load–mutate–store pattern is not atomic as a whole — it can race with concurrent stores. Use only where the C code would have used a non-atomic access that happens to be race-free by design.

Implementations

impl<T: AtomicRepr> RelaxedAtomic<T>

pub fn new(val: T) -> Self

Create a new RelaxedAtomic with the given initial value.

pub fn load(&self) -> T

Load the current value with relaxed ordering.

pub fn store(&self, val: T)

Store a new value with relaxed ordering.

pub fn into_inner(self) -> T

Consume the atomic and return the inner value.

impl RelaxedAtomic<u32>

pub fn fetch_add(&self, val: u32) -> u32

Atomic add with relaxed ordering.

Returns the previous value. This is an atomic read-modify-write operation that compiles to a LOCK XADD instruction on x86_64. While it does emit a LOCK prefix, it avoids the stronger ordering fence overhead of SeqCst.

Use this for atomic increments where the load-mutate-store pattern would cause race conditions.

impl RelaxedAtomic<u32>

pub fn fetch_sub(&self, val: u32) -> u32

Atomic subtract with relaxed ordering.

Returns the previous value. This is an atomic read-modify-write operation that compiles to a LOCK XSUB instruction on x86_64.

Trait Implementations

impl<T: AtomicRepr> Clone for RelaxedAtomic<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + AtomicRepr> Debug for RelaxedAtomic<T>

where T::Atomic: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: AtomicRepr + Default> Default for RelaxedAtomic<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: AtomicRepr + Display> Display for RelaxedAtomic<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: AtomicRepr + Eq> Eq for RelaxedAtomic<T>

impl<T: AtomicRepr + PartialEq> PartialEq for RelaxedAtomic<T>

WARNING: This performs two separate relaxed loads. Under concurrent writes the two values may come from different points in time. This is a race condition (not a data race) — Rust does not prevent it.

Use this ONLY for diagnostic assertions, debug checks, or logging. NEVER use this for correctness-critical decisions like:

• Deciding whether to proceed with an operation
• Checking if a resource is available
• Validating state transitions

For correctness-critical comparisons, load both values atomically first:

let a = atomic_a.load(Ordering::SeqCst);
let b = atomic_b.load(Ordering::SeqCst);
if a == b { /* safe to proceed */ }

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.