Text of rust.docs.kernel.org › next › kernel › sync › atomic › struct.Atomic.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Atomic in kernel::sync::atomic - Rust

Skip to main content Atomic kernel :: sync :: atomic Struct Atomic Source pub struct Atomic<T: AtomicType >( /* private fields */ ); Expand description A memory location which can be safely modified from multiple execution contexts. This has the same size, alignment and bit validity as the underlying type T . And it disables niche optimization for the same reason as UnsafeCell . The atomic operations are implemented in a way that is fully compatible with the Linux Kernel Memory (Consistency) Model , hence they should be modeled as the corresponding LKMM atomic primitives.

With the help of Atomic::from_ptr() and Atomic::as_ptr() , this provides a way to interact with C-side atomic operations (including those without the atomic prefix, e.g. READ_ONCE() , WRITE_ONCE() , smp_load_acquire() and smp_store_release() ). § Invariants self.0 is a valid T . Implementations § Source § impl<T: AtomicType > Atomic <T> Source pub const fn new (v: T) -> Self Creates a new atomic T . Source pub unsafe fn from_ptr <'a>(ptr: *mut T ) -> &'a Self Creates a reference to an atomic T from a pointer of T .

This usually is used when communicating with C side or manipulating a C struct, see examples below. § Safety ptr is aligned to align_of::<T>() . ptr is valid for reads and writes for 'a . For the duration of 'a , other accesses to *ptr must not cause data races (defined by LKMM ) against atomic operations on the returned reference. Note that if all other accesses are atomic, then this safety requirement is trivially fulfilled. § Examples Using Atomic::from_ptr() combined with Atomic::load() or Atomic::store() can achieve the same functionality as READ_ONCE() / smp_load_acquire() or WRITE_ONCE() / smp_store_release() in C side: use kernel::sync::atomic::{Atomic, Relaxed, Release}; // Assume there is a C struct `foo`. mod cbindings { #[repr(C)] pub ( crate ) struct foo { pub ( crate ) a: i32, pub ( crate ) b: i32 } } let tmp = Opaque::new(cbindings::foo { a: 1 , b: 2 }); // struct foo *foo_ptr = ..; let foo_ptr = tmp.get(); // SAFETY: `foo_ptr` is valid, and `.a` is in bounds. let foo_a_ptr = unsafe { & raw mut ( * foo_ptr).a }; // a = READ_ONCE(foo_ptr->a); // // SAFETY: `foo_a_ptr` is valid for read, and all other accesses on it is atomic, so no // data race. let a = unsafe { Atomic::from_ptr(foo_a_ptr) }.load(Relaxed); // smp_store_release(&foo_ptr->a, 2); // // SAFETY: `foo_a_ptr` is valid for writes, and all other accesses on it is atomic, so // no data race. unsafe { Atomic::from_ptr(foo_a_ptr) }.store( 2 , Release); Source pub const fn as_ptr (&self) -> *mut T Returns a pointer to the underlying atomic T .

Note that use of the return pointer must not cause data races defined by LKMM . § Guarantees The returned pointer is valid and properly aligned (i.e. aligned to align_of::<T>() ). Source pub fn get_mut (&mut self) -> &mut T Returns a mutable reference to the underlying atomic T . This is safe because the mutable reference of the atomic T guarantees exclusive access. § Examples use kernel::sync::atomic::{Atomic, Relaxed}; let mut atomic_val = Atomic::new( 0u32 ); let val_mut = atomic_val.get_mut(); * val_mut = 101 ; assert_eq! ( 101 , atomic_val.load(Relaxed)); Source § impl<T: AtomicType > Atomic <T> where T:: Repr : AtomicBasicOps, Source pub fn load <Ordering: AcquireOrRelaxed >(&self, _: Ordering) -> T Loads the value from the atomic T . § Examples use kernel::sync::atomic::{Atomic, Relaxed}; let x = Atomic::new( 42i32 ); assert_eq! ( 42 , x.load(Relaxed)); let x = Atomic::new( 42i64 ); assert_eq! ( 42 , x.load(Relaxed)); Source pub fn store <Ordering: ReleaseOrRelaxed >(&self, v: T, _: Ordering) Stores a value to the atomic T . § Examples use kernel::sync::atomic::{Atomic, Relaxed}; let x = Atomic::new( 42i32 ); assert_eq! ( 42 , x.load(Relaxed)); x.store( 43 , Relaxed); assert_eq! ( 43 , x.load(Relaxed)); Source § impl<T: AtomicType > Atomic <T> where T:: Repr : AtomicExchangeOps, Source pub fn xchg <Ordering: Ordering >(&self, v: T, _: Ordering) -> T Atomic exchange.

Atomically updates *self to v and returns the old value of *self . § Examples use kernel::sync::atomic::{Atomic, Acquire, Relaxed}; let x = Atomic::new( 42 ); assert_eq! ( 42 , x.xchg( 52 , Acquire)); assert_eq! ( 52 , x.load(Relaxed)); Source pub fn cmpxchg <Ordering: Ordering >( &self, old: T, new: T, o: Ordering, ) -> Result <T, T> Atomic compare and exchange. If *self == old , atomically updates *self to new . Otherwise, *self is not modified.

Compare: The comparison is done via the byte level comparison between *self and old . Ordering: When succeeds, provides the corresponding ordering as the Ordering type parameter indicates, and a failed one doesn’t provide any ordering, the load part of a failed cmpxchg is a Relaxed load. Returns Ok(value) if cmpxchg succeeds, and value is guaranteed to be equal to old , otherwise returns Err(value) , and value is the current value of *self . § Examples use kernel::sync::atomic::{Atomic, Full, Relaxed}; let x = Atomic::new( 42 ); // Checks whether cmpxchg succeeded. let success = x.cmpxchg( 52 , 64 , Relaxed).is_ok(); // Checks whether cmpxchg failed. let failure = x.cmpxchg( 52 , 64 , Relaxed).is_err(); // Uses the old value if failed, probably re-try cmpxchg. match x.cmpxchg( 52 , 64 , Relaxed) { Ok ( _ ) => { }, Err (old) => { // do something with `old`. } } // Uses the latest value regardlessly, same as atomic_cmpxchg() in C. let latest = x.cmpxchg( 42 , 64 , Full).unwrap_or_else(|old| old); assert_eq! ( 64 , x.load(Relaxed)); Source § impl<T: AtomicType > Atomic <T> where T:: Repr : AtomicArithmeticOps, Source pub fn add <Rhs>(&self, v: Rhs, _: Relaxed ) where T: AtomicAdd <Rhs>, Atomic add.

Atomically updates *self to (*self).wrapping_add(v) . § Examples use kernel::sync::atomic::{Atomic, Relaxed}; let x = Atomic::new( 42 ); assert_eq! ( 42 , x.load(Relaxed)); x.add( 12 , Relaxed); assert_eq! ( 54 , x.load(Relaxed)); Source pub fn fetch_add <Rhs, Ordering: Ordering >(&self, v: Rhs, _: Ordering) -> T where T: AtomicAdd <Rhs>, Atomic fetch and add. Atomically updates *self to (*self).wrapping_add(v) , and returns the value of *self before the update. § Examples use kernel::sync::atomic::{Atomic, Acquire, Full, Relaxed}; let x = Atomic::new( 42 ); assert_eq! ( 42 , x.load(Relaxed)); assert_eq! ( 42 , x.fetch_add( 12 , Acquire)); assert_eq! ( 54 , x.load(Relaxed)); let x = Atomic::new( 42 ); assert_eq! ( 42 , x.load(Relaxed)); assert_eq! ( 42 , x.fetch_add( 12 , Full)); assert_eq! ( 54 , x.load(Relaxed)); Source pub fn fetch_sub <Rhs, Ordering: Ordering >(&self, v: Rhs, _: Ordering) -> T where T: AtomicAdd <Rhs>, Atomic fetch and subtract.

Atomically updates *self to (*self).wrapping_sub(v) , and returns the value of *self before the update. § Examples use kernel::sync::atomic::{Atomic, Acquire, Full, Relaxed}; let x = Atomic::new( 42 ); assert_eq! ( 42 , x.load(Relaxed)); assert_eq! ( 42 , x.fetch_sub( 12 , Acquire)); assert_eq! ( 30 , x.load(Relaxed)); let x = Atomic::new( 42 ); assert_eq! ( 42 , x.load(Relaxed)); assert_eq! ( 42 , x.fetch_sub( 12 , Full)); assert_eq! ( 30 , x.load(Relaxed)); Trait Implementations § Source § impl<T: AtomicType + Debug > Debug for Atomic <T> where T:: Repr : AtomicBasicOps, Source § fn fmt (&self, f: &mut Formatter <'_>) -> Result Formats the value using the given formatter.

Read more Source § impl<T: AtomicType + FromStr > Reader for Atomic <T> where T:: Repr : AtomicBasicOps, Source § fn read_from_slice (&self, reader: &mut UserSliceReader ) -> Result Updates the value from the given user slice. Source § impl<T: AtomicType > Send for Atomic <T> Source § impl<T: AtomicType > Sync for Atomic <T> Auto Trait Implementations § § impl<T> ! Freeze for Atomic <T> § impl<T> ! RefUnwindSafe for Atomic <T> § impl<T> Forget for Atomic <T> § impl<T> Move for Atomic <T> § impl<T> Unpin for Atomic <T> where AtomicRepr<<T as AtomicType >:: Repr >: Unpin , § impl<T> UnsafeUnpin for Atomic <T> where

The rest of this page is on the live site.