1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 //! Atomic types provide primitive shared-memory communication between
14 //! threads, and are the building blocks of other concurrent
17 //! This module defines atomic versions of a select number of primitive
18 //! types, including `AtomicBool`, `AtomicIsize`, and `AtomicUsize`.
19 //! Atomic types present operations that, when used correctly, synchronize
20 //! updates between threads.
22 //! Each method takes an `Ordering` which represents the strength of
23 //! the memory barrier for that operation. These orderings are the
24 //! same as [LLVM atomic orderings][1].
26 //! [1]: http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations
28 //! Atomic variables are safe to share between threads (they implement `Sync`)
29 //! but they do not themselves provide the mechanism for sharing and follow the
30 //! [threading model](../../../std/thread/index.html#the-threading-model) of rust.
31 //! The most common way to share an atomic variable is to put it into an `Arc` (an
32 //! atomically-reference-counted shared pointer).
34 //! Most atomic types may be stored in static variables, initialized using
35 //! the provided static initializers like `ATOMIC_BOOL_INIT`. Atomic statics
36 //! are often used for lazy global initialization.
41 //! A simple spinlock:
44 //! use std::sync::Arc;
45 //! use std::sync::atomic::{AtomicUsize, Ordering};
49 //! let spinlock = Arc::new(AtomicUsize::new(1));
51 //! let spinlock_clone = spinlock.clone();
52 //! let thread = thread::spawn(move|| {
53 //! spinlock_clone.store(0, Ordering::SeqCst);
56 //! // Wait for the other thread to release the lock
57 //! while spinlock.load(Ordering::SeqCst) != 0 {}
59 //! if let Err(panic) = thread.join() {
60 //! println!("Thread had an error: {:?}", panic);
65 //! Keep a global count of live threads:
68 //! use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT};
70 //! static GLOBAL_THREAD_COUNT: AtomicUsize = ATOMIC_USIZE_INIT;
72 //! let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::SeqCst);
73 //! println!("live threads: {}", old_thread_count + 1);
76 #![stable(feature = "rust1", since = "1.0.0")]
77 #![cfg_attr(not(target_has_atomic = "8"), allow(dead_code))]
78 #![cfg_attr(not(target_has_atomic = "8"), allow(unused_imports))]
80 use self::Ordering::*;
86 /// A boolean type which can be safely shared between threads.
88 /// This type has the same in-memory representation as a `bool`.
89 #[cfg(target_has_atomic = "8")]
90 #[stable(feature = "rust1", since = "1.0.0")]
91 pub struct AtomicBool {
95 #[cfg(target_has_atomic = "8")]
96 #[stable(feature = "rust1", since = "1.0.0")]
97 impl Default for AtomicBool {
98 fn default() -> Self {
103 // Send is implicitly implemented for AtomicBool.
104 #[cfg(target_has_atomic = "8")]
105 #[stable(feature = "rust1", since = "1.0.0")]
106 unsafe impl Sync for AtomicBool {}
108 /// A raw pointer type which can be safely shared between threads.
110 /// This type has the same in-memory representation as a `*mut T`.
111 #[cfg(target_has_atomic = "ptr")]
112 #[stable(feature = "rust1", since = "1.0.0")]
113 pub struct AtomicPtr<T> {
114 p: UnsafeCell<*mut T>,
117 #[cfg(target_has_atomic = "ptr")]
118 #[stable(feature = "rust1", since = "1.0.0")]
119 impl<T> Default for AtomicPtr<T> {
120 fn default() -> AtomicPtr<T> {
121 AtomicPtr::new(::ptr::null_mut())
125 #[cfg(target_has_atomic = "ptr")]
126 #[stable(feature = "rust1", since = "1.0.0")]
127 unsafe impl<T> Send for AtomicPtr<T> {}
128 #[cfg(target_has_atomic = "ptr")]
129 #[stable(feature = "rust1", since = "1.0.0")]
130 unsafe impl<T> Sync for AtomicPtr<T> {}
132 /// Atomic memory orderings
134 /// Memory orderings limit the ways that both the compiler and CPU may reorder
135 /// instructions around atomic operations. At its most restrictive,
136 /// "sequentially consistent" atomics allow neither reads nor writes
137 /// to be moved either before or after the atomic operation; on the other end
138 /// "relaxed" atomics allow all reorderings.
140 /// Rust's memory orderings are [the same as
141 /// LLVM's](http://llvm.org/docs/LangRef.html#memory-model-for-concurrent-operations).
142 #[stable(feature = "rust1", since = "1.0.0")]
143 #[derive(Copy, Clone, Debug)]
145 /// No ordering constraints, only atomic operations. Corresponds to LLVM's
146 /// `Monotonic` ordering.
147 #[stable(feature = "rust1", since = "1.0.0")]
149 /// When coupled with a store, all previous writes become visible
150 /// to the other threads that perform a load with `Acquire` ordering
151 /// on the same value.
152 #[stable(feature = "rust1", since = "1.0.0")]
154 /// When coupled with a load, all subsequent loads will see data
155 /// written before a store with `Release` ordering on the same value
156 /// in other threads.
157 #[stable(feature = "rust1", since = "1.0.0")]
159 /// When coupled with a load, uses `Acquire` ordering, and with a store
160 /// `Release` ordering.
161 #[stable(feature = "rust1", since = "1.0.0")]
163 /// Like `AcqRel` with the additional guarantee that all threads see all
164 /// sequentially consistent operations in the same order.
165 #[stable(feature = "rust1", since = "1.0.0")]
169 /// An `AtomicBool` initialized to `false`.
170 #[cfg(target_has_atomic = "8")]
171 #[stable(feature = "rust1", since = "1.0.0")]
172 pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false);
174 #[cfg(target_has_atomic = "8")]
176 /// Creates a new `AtomicBool`.
181 /// use std::sync::atomic::AtomicBool;
183 /// let atomic_true = AtomicBool::new(true);
184 /// let atomic_false = AtomicBool::new(false);
187 #[stable(feature = "rust1", since = "1.0.0")]
188 pub const fn new(v: bool) -> AtomicBool {
189 AtomicBool { v: UnsafeCell::new(v as u8) }
192 /// Returns a mutable reference to the underlying `bool`.
194 /// This is safe because the mutable reference guarantees that no other threads are
195 /// concurrently accessing the atomic data.
200 /// #![feature(atomic_access)]
201 /// use std::sync::atomic::{AtomicBool, Ordering};
203 /// let mut some_bool = AtomicBool::new(true);
204 /// assert_eq!(*some_bool.get_mut(), true);
205 /// *some_bool.get_mut() = false;
206 /// assert_eq!(some_bool.load(Ordering::SeqCst), false);
209 #[unstable(feature = "atomic_access", issue = "35603")]
210 pub fn get_mut(&mut self) -> &mut bool {
211 unsafe { &mut *(self.v.get() as *mut bool) }
214 /// Consumes the atomic and returns the contained value.
216 /// This is safe because passing `self` by value guarantees that no other threads are
217 /// concurrently accessing the atomic data.
222 /// #![feature(atomic_access)]
223 /// use std::sync::atomic::AtomicBool;
225 /// let some_bool = AtomicBool::new(true);
226 /// assert_eq!(some_bool.into_inner(), true);
229 #[unstable(feature = "atomic_access", issue = "35603")]
230 pub fn into_inner(self) -> bool {
231 unsafe { self.v.into_inner() != 0 }
234 /// Loads a value from the bool.
236 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
240 /// Panics if `order` is `Release` or `AcqRel`.
245 /// use std::sync::atomic::{AtomicBool, Ordering};
247 /// let some_bool = AtomicBool::new(true);
249 /// assert_eq!(some_bool.load(Ordering::Relaxed), true);
252 #[stable(feature = "rust1", since = "1.0.0")]
253 pub fn load(&self, order: Ordering) -> bool {
254 unsafe { atomic_load(self.v.get(), order) != 0 }
257 /// Stores a value into the bool.
259 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
264 /// use std::sync::atomic::{AtomicBool, Ordering};
266 /// let some_bool = AtomicBool::new(true);
268 /// some_bool.store(false, Ordering::Relaxed);
269 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
274 /// Panics if `order` is `Acquire` or `AcqRel`.
276 #[stable(feature = "rust1", since = "1.0.0")]
277 pub fn store(&self, val: bool, order: Ordering) {
278 unsafe { atomic_store(self.v.get(), val as u8, order); }
281 /// Stores a value into the bool, returning the old value.
283 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
288 /// use std::sync::atomic::{AtomicBool, Ordering};
290 /// let some_bool = AtomicBool::new(true);
292 /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true);
293 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
296 #[stable(feature = "rust1", since = "1.0.0")]
297 pub fn swap(&self, val: bool, order: Ordering) -> bool {
298 unsafe { atomic_swap(self.v.get(), val as u8, order) != 0 }
301 /// Stores a value into the `bool` if the current value is the same as the `current` value.
303 /// The return value is always the previous value. If it is equal to `current`, then the value
306 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory ordering of
312 /// use std::sync::atomic::{AtomicBool, Ordering};
314 /// let some_bool = AtomicBool::new(true);
316 /// assert_eq!(some_bool.compare_and_swap(true, false, Ordering::Relaxed), true);
317 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
319 /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false);
320 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
323 #[stable(feature = "rust1", since = "1.0.0")]
324 pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> bool {
325 match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
331 /// Stores a value into the `bool` if the current value is the same as the `current` value.
333 /// The return value is a result indicating whether the new value was written and containing
334 /// the previous value. On success this value is guaranteed to be equal to `current`.
336 /// `compare_exchange` takes two `Ordering` arguments to describe the memory ordering of this
337 /// operation. The first describes the required ordering if the operation succeeds while the
338 /// second describes the required ordering when the operation fails. The failure ordering can't
339 /// be `Release` or `AcqRel` and must be equivalent or weaker than the success ordering.
344 /// use std::sync::atomic::{AtomicBool, Ordering};
346 /// let some_bool = AtomicBool::new(true);
348 /// assert_eq!(some_bool.compare_exchange(true,
350 /// Ordering::Acquire,
351 /// Ordering::Relaxed),
353 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
355 /// assert_eq!(some_bool.compare_exchange(true, true,
356 /// Ordering::SeqCst,
357 /// Ordering::Acquire),
359 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
362 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
363 pub fn compare_exchange(&self,
367 failure: Ordering) -> Result<bool, bool> {
368 match unsafe { atomic_compare_exchange(self.v.get(), current as u8, new as u8,
369 success, failure) } {
371 Err(x) => Err(x != 0),
375 /// Stores a value into the `bool` if the current value is the same as the `current` value.
377 /// Unlike `compare_exchange`, this function is allowed to spuriously fail even when the
378 /// comparison succeeds, which can result in more efficient code on some platforms. The
379 /// return value is a result indicating whether the new value was written and containing the
382 /// `compare_exchange_weak` takes two `Ordering` arguments to describe the memory
383 /// ordering of this operation. The first describes the required ordering if the operation
384 /// succeeds while the second describes the required ordering when the operation fails. The
385 /// failure ordering can't be `Release` or `AcqRel` and must be equivalent or weaker than the
386 /// success ordering.
391 /// use std::sync::atomic::{AtomicBool, Ordering};
393 /// let val = AtomicBool::new(false);
396 /// let mut old = val.load(Ordering::Relaxed);
398 /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
400 /// Err(x) => old = x,
405 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
406 pub fn compare_exchange_weak(&self,
410 failure: Ordering) -> Result<bool, bool> {
411 match unsafe { atomic_compare_exchange_weak(self.v.get(), current as u8, new as u8,
412 success, failure) } {
414 Err(x) => Err(x != 0),
418 /// Logical "and" with a boolean value.
420 /// Performs a logical "and" operation on the current value and the argument `val`, and sets
421 /// the new value to the result.
423 /// Returns the previous value.
428 /// use std::sync::atomic::{AtomicBool, Ordering};
430 /// let foo = AtomicBool::new(true);
431 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), true);
432 /// assert_eq!(foo.load(Ordering::SeqCst), false);
434 /// let foo = AtomicBool::new(true);
435 /// assert_eq!(foo.fetch_and(true, Ordering::SeqCst), true);
436 /// assert_eq!(foo.load(Ordering::SeqCst), true);
438 /// let foo = AtomicBool::new(false);
439 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false);
440 /// assert_eq!(foo.load(Ordering::SeqCst), false);
443 #[stable(feature = "rust1", since = "1.0.0")]
444 pub fn fetch_and(&self, val: bool, order: Ordering) -> bool {
445 unsafe { atomic_and(self.v.get(), val as u8, order) != 0 }
448 /// Logical "nand" with a boolean value.
450 /// Performs a logical "nand" operation on the current value and the argument `val`, and sets
451 /// the new value to the result.
453 /// Returns the previous value.
458 /// use std::sync::atomic::{AtomicBool, Ordering};
460 /// let foo = AtomicBool::new(true);
461 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), true);
462 /// assert_eq!(foo.load(Ordering::SeqCst), true);
464 /// let foo = AtomicBool::new(true);
465 /// assert_eq!(foo.fetch_nand(true, Ordering::SeqCst), true);
466 /// assert_eq!(foo.load(Ordering::SeqCst) as usize, 0);
467 /// assert_eq!(foo.load(Ordering::SeqCst), false);
469 /// let foo = AtomicBool::new(false);
470 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false);
471 /// assert_eq!(foo.load(Ordering::SeqCst), true);
474 #[stable(feature = "rust1", since = "1.0.0")]
475 pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool {
476 // We can't use atomic_nand here because it can result in a bool with
477 // an invalid value. This happens because the atomic operation is done
478 // with an 8-bit integer internally, which would set the upper 7 bits.
479 // So we just use a compare-exchange loop instead, which is what the
480 // intrinsic actually expands to anyways on many platforms.
481 let mut old = self.load(Relaxed);
483 let new = !(old && val);
484 match self.compare_exchange_weak(old, new, order, Relaxed) {
492 /// Logical "or" with a boolean value.
494 /// Performs a logical "or" operation on the current value and the argument `val`, and sets the
495 /// new value to the result.
497 /// Returns the previous value.
502 /// use std::sync::atomic::{AtomicBool, Ordering};
504 /// let foo = AtomicBool::new(true);
505 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), true);
506 /// assert_eq!(foo.load(Ordering::SeqCst), true);
508 /// let foo = AtomicBool::new(true);
509 /// assert_eq!(foo.fetch_or(true, Ordering::SeqCst), true);
510 /// assert_eq!(foo.load(Ordering::SeqCst), true);
512 /// let foo = AtomicBool::new(false);
513 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false);
514 /// assert_eq!(foo.load(Ordering::SeqCst), false);
517 #[stable(feature = "rust1", since = "1.0.0")]
518 pub fn fetch_or(&self, val: bool, order: Ordering) -> bool {
519 unsafe { atomic_or(self.v.get(), val as u8, order) != 0 }
522 /// Logical "xor" with a boolean value.
524 /// Performs a logical "xor" operation on the current value and the argument `val`, and sets
525 /// the new value to the result.
527 /// Returns the previous value.
532 /// use std::sync::atomic::{AtomicBool, Ordering};
534 /// let foo = AtomicBool::new(true);
535 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), true);
536 /// assert_eq!(foo.load(Ordering::SeqCst), true);
538 /// let foo = AtomicBool::new(true);
539 /// assert_eq!(foo.fetch_xor(true, Ordering::SeqCst), true);
540 /// assert_eq!(foo.load(Ordering::SeqCst), false);
542 /// let foo = AtomicBool::new(false);
543 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false);
544 /// assert_eq!(foo.load(Ordering::SeqCst), false);
547 #[stable(feature = "rust1", since = "1.0.0")]
548 pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool {
549 unsafe { atomic_xor(self.v.get(), val as u8, order) != 0 }
553 #[cfg(target_has_atomic = "ptr")]
554 impl<T> AtomicPtr<T> {
555 /// Creates a new `AtomicPtr`.
560 /// use std::sync::atomic::AtomicPtr;
562 /// let ptr = &mut 5;
563 /// let atomic_ptr = AtomicPtr::new(ptr);
566 #[stable(feature = "rust1", since = "1.0.0")]
567 pub const fn new(p: *mut T) -> AtomicPtr<T> {
568 AtomicPtr { p: UnsafeCell::new(p) }
571 /// Returns a mutable reference to the underlying pointer.
573 /// This is safe because the mutable reference guarantees that no other threads are
574 /// concurrently accessing the atomic data.
579 /// #![feature(atomic_access)]
580 /// use std::sync::atomic::{AtomicPtr, Ordering};
582 /// let mut atomic_ptr = AtomicPtr::new(&mut 10);
583 /// *atomic_ptr.get_mut() = &mut 5;
584 /// assert_eq!(unsafe { *atomic_ptr.load(Ordering::SeqCst) }, 5);
587 #[unstable(feature = "atomic_access", issue = "35603")]
588 pub fn get_mut(&mut self) -> &mut *mut T {
589 unsafe { &mut *self.p.get() }
592 /// Consumes the atomic and returns the contained value.
594 /// This is safe because passing `self` by value guarantees that no other threads are
595 /// concurrently accessing the atomic data.
600 /// #![feature(atomic_access)]
601 /// use std::sync::atomic::AtomicPtr;
603 /// let atomic_ptr = AtomicPtr::new(&mut 5);
604 /// assert_eq!(unsafe { *atomic_ptr.into_inner() }, 5);
607 #[unstable(feature = "atomic_access", issue = "35603")]
608 pub fn into_inner(self) -> *mut T {
609 unsafe { self.p.into_inner() }
612 /// Loads a value from the pointer.
614 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
618 /// Panics if `order` is `Release` or `AcqRel`.
623 /// use std::sync::atomic::{AtomicPtr, Ordering};
625 /// let ptr = &mut 5;
626 /// let some_ptr = AtomicPtr::new(ptr);
628 /// let value = some_ptr.load(Ordering::Relaxed);
631 #[stable(feature = "rust1", since = "1.0.0")]
632 pub fn load(&self, order: Ordering) -> *mut T {
634 atomic_load(self.p.get() as *mut usize, order) as *mut T
638 /// Stores a value into the pointer.
640 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
645 /// use std::sync::atomic::{AtomicPtr, Ordering};
647 /// let ptr = &mut 5;
648 /// let some_ptr = AtomicPtr::new(ptr);
650 /// let other_ptr = &mut 10;
652 /// some_ptr.store(other_ptr, Ordering::Relaxed);
657 /// Panics if `order` is `Acquire` or `AcqRel`.
659 #[stable(feature = "rust1", since = "1.0.0")]
660 pub fn store(&self, ptr: *mut T, order: Ordering) {
661 unsafe { atomic_store(self.p.get() as *mut usize, ptr as usize, order); }
664 /// Stores a value into the pointer, returning the old value.
666 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
671 /// use std::sync::atomic::{AtomicPtr, Ordering};
673 /// let ptr = &mut 5;
674 /// let some_ptr = AtomicPtr::new(ptr);
676 /// let other_ptr = &mut 10;
678 /// let value = some_ptr.swap(other_ptr, Ordering::Relaxed);
681 #[stable(feature = "rust1", since = "1.0.0")]
682 pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T {
683 unsafe { atomic_swap(self.p.get() as *mut usize, ptr as usize, order) as *mut T }
686 /// Stores a value into the pointer if the current value is the same as the `current` value.
688 /// The return value is always the previous value. If it is equal to `current`, then the value
691 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory ordering of
697 /// use std::sync::atomic::{AtomicPtr, Ordering};
699 /// let ptr = &mut 5;
700 /// let some_ptr = AtomicPtr::new(ptr);
702 /// let other_ptr = &mut 10;
703 /// let another_ptr = &mut 10;
705 /// let value = some_ptr.compare_and_swap(other_ptr, another_ptr, Ordering::Relaxed);
708 #[stable(feature = "rust1", since = "1.0.0")]
709 pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> *mut T {
710 match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) {
716 /// Stores a value into the pointer if the current value is the same as the `current` value.
718 /// The return value is a result indicating whether the new value was written and containing
719 /// the previous value. On success this value is guaranteed to be equal to `current`.
721 /// `compare_exchange` takes two `Ordering` arguments to describe the memory ordering of this
722 /// operation. The first describes the required ordering if the operation succeeds while the
723 /// second describes the required ordering when the operation fails. The failure ordering can't
724 /// be `Release` or `AcqRel` and must be equivalent or weaker than the success ordering.
729 /// use std::sync::atomic::{AtomicPtr, Ordering};
731 /// let ptr = &mut 5;
732 /// let some_ptr = AtomicPtr::new(ptr);
734 /// let other_ptr = &mut 10;
735 /// let another_ptr = &mut 10;
737 /// let value = some_ptr.compare_exchange(other_ptr, another_ptr,
738 /// Ordering::SeqCst, Ordering::Relaxed);
741 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
742 pub fn compare_exchange(&self,
746 failure: Ordering) -> Result<*mut T, *mut T> {
748 let res = atomic_compare_exchange(self.p.get() as *mut usize,
754 Ok(x) => Ok(x as *mut T),
755 Err(x) => Err(x as *mut T),
760 /// Stores a value into the pointer if the current value is the same as the `current` value.
762 /// Unlike `compare_exchange`, this function is allowed to spuriously fail even when the
763 /// comparison succeeds, which can result in more efficient code on some platforms. The
764 /// return value is a result indicating whether the new value was written and containing the
767 /// `compare_exchange_weak` takes two `Ordering` arguments to describe the memory
768 /// ordering of this operation. The first describes the required ordering if the operation
769 /// succeeds while the second describes the required ordering when the operation fails. The
770 /// failure ordering can't be `Release` or `AcqRel` and must be equivalent or weaker than the
771 /// success ordering.
776 /// use std::sync::atomic::{AtomicPtr, Ordering};
778 /// let some_ptr = AtomicPtr::new(&mut 5);
780 /// let new = &mut 10;
781 /// let mut old = some_ptr.load(Ordering::Relaxed);
783 /// match some_ptr.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
785 /// Err(x) => old = x,
790 #[stable(feature = "extended_compare_and_swap", since = "1.10.0")]
791 pub fn compare_exchange_weak(&self,
795 failure: Ordering) -> Result<*mut T, *mut T> {
797 let res = atomic_compare_exchange_weak(self.p.get() as *mut usize,
803 Ok(x) => Ok(x as *mut T),
804 Err(x) => Err(x as *mut T),
810 macro_rules! atomic_int {
815 $int_type:ident $atomic_type:ident $atomic_init:ident) => {
816 /// An integer type which can be safely shared between threads.
818 /// This type has the same in-memory representation as the underlying integer type.
820 pub struct $atomic_type {
821 v: UnsafeCell<$int_type>,
824 /// An atomic integer initialized to `0`.
826 pub const $atomic_init: $atomic_type = $atomic_type::new(0);
829 impl Default for $atomic_type {
830 fn default() -> Self {
831 Self::new(Default::default())
836 impl fmt::Debug for $atomic_type {
837 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
838 f.debug_tuple(stringify!($atomic_type))
839 .field(&self.load(Ordering::SeqCst))
844 // Send is implicitly implemented.
846 unsafe impl Sync for $atomic_type {}
849 /// Creates a new atomic integer.
854 /// use std::sync::atomic::AtomicIsize;
856 /// let atomic_forty_two = AtomicIsize::new(42);
860 pub const fn new(v: $int_type) -> Self {
861 $atomic_type {v: UnsafeCell::new(v)}
864 /// Returns a mutable reference to the underlying integer.
866 /// This is safe because the mutable reference guarantees that no other threads are
867 /// concurrently accessing the atomic data.
872 /// #![feature(atomic_access)]
873 /// use std::sync::atomic::{AtomicIsize, Ordering};
875 /// let mut some_isize = AtomicIsize::new(10);
876 /// assert_eq!(*some_isize.get_mut(), 10);
877 /// *some_isize.get_mut() = 5;
878 /// assert_eq!(some_isize.load(Ordering::SeqCst), 5);
882 pub fn get_mut(&mut self) -> &mut $int_type {
883 unsafe { &mut *self.v.get() }
886 /// Consumes the atomic and returns the contained value.
888 /// This is safe because passing `self` by value guarantees that no other threads are
889 /// concurrently accessing the atomic data.
894 /// #![feature(atomic_access)]
895 /// use std::sync::atomic::AtomicIsize;
897 /// let some_isize = AtomicIsize::new(5);
898 /// assert_eq!(some_isize.into_inner(), 5);
902 pub fn into_inner(self) -> $int_type {
903 unsafe { self.v.into_inner() }
906 /// Loads a value from the atomic integer.
908 /// `load` takes an `Ordering` argument which describes the memory ordering of this
913 /// Panics if `order` is `Release` or `AcqRel`.
918 /// use std::sync::atomic::{AtomicIsize, Ordering};
920 /// let some_isize = AtomicIsize::new(5);
922 /// assert_eq!(some_isize.load(Ordering::Relaxed), 5);
926 pub fn load(&self, order: Ordering) -> $int_type {
927 unsafe { atomic_load(self.v.get(), order) }
930 /// Stores a value into the atomic integer.
932 /// `store` takes an `Ordering` argument which describes the memory ordering of this
938 /// use std::sync::atomic::{AtomicIsize, Ordering};
940 /// let some_isize = AtomicIsize::new(5);
942 /// some_isize.store(10, Ordering::Relaxed);
943 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
948 /// Panics if `order` is `Acquire` or `AcqRel`.
951 pub fn store(&self, val: $int_type, order: Ordering) {
952 unsafe { atomic_store(self.v.get(), val, order); }
955 /// Stores a value into the atomic integer, returning the old value.
957 /// `swap` takes an `Ordering` argument which describes the memory ordering of this
963 /// use std::sync::atomic::{AtomicIsize, Ordering};
965 /// let some_isize = AtomicIsize::new(5);
967 /// assert_eq!(some_isize.swap(10, Ordering::Relaxed), 5);
971 pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type {
972 unsafe { atomic_swap(self.v.get(), val, order) }
975 /// Stores a value into the atomic integer if the current value is the same as the
978 /// The return value is always the previous value. If it is equal to `current`, then the
979 /// value was updated.
981 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory
982 /// ordering of this operation.
987 /// use std::sync::atomic::{AtomicIsize, Ordering};
989 /// let some_isize = AtomicIsize::new(5);
991 /// assert_eq!(some_isize.compare_and_swap(5, 10, Ordering::Relaxed), 5);
992 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
994 /// assert_eq!(some_isize.compare_and_swap(6, 12, Ordering::Relaxed), 10);
995 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
999 pub fn compare_and_swap(&self,
1002 order: Ordering) -> $int_type {
1003 match self.compare_exchange(current,
1006 strongest_failure_ordering(order)) {
1012 /// Stores a value into the atomic integer if the current value is the same as the
1013 /// `current` value.
1015 /// The return value is a result indicating whether the new value was written and
1016 /// containing the previous value. On success this value is guaranteed to be equal to
1019 /// `compare_exchange` takes two `Ordering` arguments to describe the memory ordering of
1020 /// this operation. The first describes the required ordering if the operation succeeds
1021 /// while the second describes the required ordering when the operation fails. The
1022 /// failure ordering can't be `Release` or `AcqRel` and must be equivalent or weaker
1023 /// than the success ordering.
1028 /// use std::sync::atomic::{AtomicIsize, Ordering};
1030 /// let some_isize = AtomicIsize::new(5);
1032 /// assert_eq!(some_isize.compare_exchange(5, 10,
1033 /// Ordering::Acquire,
1034 /// Ordering::Relaxed),
1036 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
1038 /// assert_eq!(some_isize.compare_exchange(6, 12,
1039 /// Ordering::SeqCst,
1040 /// Ordering::Acquire),
1042 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
1046 pub fn compare_exchange(&self,
1050 failure: Ordering) -> Result<$int_type, $int_type> {
1051 unsafe { atomic_compare_exchange(self.v.get(), current, new, success, failure) }
1054 /// Stores a value into the atomic integer if the current value is the same as the
1055 /// `current` value.
1057 /// Unlike `compare_exchange`, this function is allowed to spuriously fail even when the
1058 /// comparison succeeds, which can result in more efficient code on some platforms. The
1059 /// return value is a result indicating whether the new value was written and containing
1060 /// the previous value.
1062 /// `compare_exchange_weak` takes two `Ordering` arguments to describe the memory
1063 /// ordering of this operation. The first describes the required ordering if the
1064 /// operation succeeds while the second describes the required ordering when the
1065 /// operation fails. The failure ordering can't be `Release` or `AcqRel` and must be
1066 /// equivalent or weaker than the success ordering.
1071 /// use std::sync::atomic::{AtomicIsize, Ordering};
1073 /// let val = AtomicIsize::new(4);
1075 /// let mut old = val.load(Ordering::Relaxed);
1077 /// let new = old * 2;
1078 /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
1080 /// Err(x) => old = x,
1086 pub fn compare_exchange_weak(&self,
1090 failure: Ordering) -> Result<$int_type, $int_type> {
1092 atomic_compare_exchange_weak(self.v.get(), current, new, success, failure)
1096 /// Add to the current value, returning the previous value.
1101 /// use std::sync::atomic::{AtomicIsize, Ordering};
1103 /// let foo = AtomicIsize::new(0);
1104 /// assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0);
1105 /// assert_eq!(foo.load(Ordering::SeqCst), 10);
1109 pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type {
1110 unsafe { atomic_add(self.v.get(), val, order) }
1113 /// Subtract from the current value, returning the previous value.
1118 /// use std::sync::atomic::{AtomicIsize, Ordering};
1120 /// let foo = AtomicIsize::new(0);
1121 /// assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 0);
1122 /// assert_eq!(foo.load(Ordering::SeqCst), -10);
1126 pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type {
1127 unsafe { atomic_sub(self.v.get(), val, order) }
1130 /// Bitwise and with the current value, returning the previous value.
1135 /// use std::sync::atomic::{AtomicIsize, Ordering};
1137 /// let foo = AtomicIsize::new(0b101101);
1138 /// assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101);
1139 /// assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
1142 pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type {
1143 unsafe { atomic_and(self.v.get(), val, order) }
1146 /// Bitwise or with the current value, returning the previous value.
1151 /// use std::sync::atomic::{AtomicIsize, Ordering};
1153 /// let foo = AtomicIsize::new(0b101101);
1154 /// assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101);
1155 /// assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
1158 pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type {
1159 unsafe { atomic_or(self.v.get(), val, order) }
1162 /// Bitwise xor with the current value, returning the previous value.
1167 /// use std::sync::atomic::{AtomicIsize, Ordering};
1169 /// let foo = AtomicIsize::new(0b101101);
1170 /// assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101);
1171 /// assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
1174 pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type {
1175 unsafe { atomic_xor(self.v.get(), val, order) }
1181 #[cfg(target_has_atomic = "8")]
1183 unstable(feature = "integer_atomics", issue = "32976"),
1184 unstable(feature = "integer_atomics", issue = "32976"),
1185 unstable(feature = "integer_atomics", issue = "32976"),
1186 unstable(feature = "integer_atomics", issue = "32976"),
1187 i8 AtomicI8 ATOMIC_I8_INIT
1189 #[cfg(target_has_atomic = "8")]
1191 unstable(feature = "integer_atomics", issue = "32976"),
1192 unstable(feature = "integer_atomics", issue = "32976"),
1193 unstable(feature = "integer_atomics", issue = "32976"),
1194 unstable(feature = "integer_atomics", issue = "32976"),
1195 u8 AtomicU8 ATOMIC_U8_INIT
1197 #[cfg(target_has_atomic = "16")]
1199 unstable(feature = "integer_atomics", issue = "32976"),
1200 unstable(feature = "integer_atomics", issue = "32976"),
1201 unstable(feature = "integer_atomics", issue = "32976"),
1202 unstable(feature = "integer_atomics", issue = "32976"),
1203 i16 AtomicI16 ATOMIC_I16_INIT
1205 #[cfg(target_has_atomic = "16")]
1207 unstable(feature = "integer_atomics", issue = "32976"),
1208 unstable(feature = "integer_atomics", issue = "32976"),
1209 unstable(feature = "integer_atomics", issue = "32976"),
1210 unstable(feature = "integer_atomics", issue = "32976"),
1211 u16 AtomicU16 ATOMIC_U16_INIT
1213 #[cfg(target_has_atomic = "32")]
1215 unstable(feature = "integer_atomics", issue = "32976"),
1216 unstable(feature = "integer_atomics", issue = "32976"),
1217 unstable(feature = "integer_atomics", issue = "32976"),
1218 unstable(feature = "integer_atomics", issue = "32976"),
1219 i32 AtomicI32 ATOMIC_I32_INIT
1221 #[cfg(target_has_atomic = "32")]
1223 unstable(feature = "integer_atomics", issue = "32976"),
1224 unstable(feature = "integer_atomics", issue = "32976"),
1225 unstable(feature = "integer_atomics", issue = "32976"),
1226 unstable(feature = "integer_atomics", issue = "32976"),
1227 u32 AtomicU32 ATOMIC_U32_INIT
1229 #[cfg(target_has_atomic = "64")]
1231 unstable(feature = "integer_atomics", issue = "32976"),
1232 unstable(feature = "integer_atomics", issue = "32976"),
1233 unstable(feature = "integer_atomics", issue = "32976"),
1234 unstable(feature = "integer_atomics", issue = "32976"),
1235 i64 AtomicI64 ATOMIC_I64_INIT
1237 #[cfg(target_has_atomic = "64")]
1239 unstable(feature = "integer_atomics", issue = "32976"),
1240 unstable(feature = "integer_atomics", issue = "32976"),
1241 unstable(feature = "integer_atomics", issue = "32976"),
1242 unstable(feature = "integer_atomics", issue = "32976"),
1243 u64 AtomicU64 ATOMIC_U64_INIT
1245 #[cfg(target_has_atomic = "ptr")]
1247 stable(feature = "rust1", since = "1.0.0"),
1248 stable(feature = "extended_compare_and_swap", since = "1.10.0"),
1249 stable(feature = "atomic_debug", since = "1.3.0"),
1250 unstable(feature = "atomic_access", issue = "35603"),
1251 isize AtomicIsize ATOMIC_ISIZE_INIT
1253 #[cfg(target_has_atomic = "ptr")]
1255 stable(feature = "rust1", since = "1.0.0"),
1256 stable(feature = "extended_compare_and_swap", since = "1.10.0"),
1257 stable(feature = "atomic_debug", since = "1.3.0"),
1258 unstable(feature = "atomic_access", issue = "35603"),
1259 usize AtomicUsize ATOMIC_USIZE_INIT
1263 fn strongest_failure_ordering(order: Ordering) -> Ordering {
1274 unsafe fn atomic_store<T>(dst: *mut T, val: T, order: Ordering) {
1276 Release => intrinsics::atomic_store_rel(dst, val),
1277 Relaxed => intrinsics::atomic_store_relaxed(dst, val),
1278 SeqCst => intrinsics::atomic_store(dst, val),
1279 Acquire => panic!("there is no such thing as an acquire store"),
1280 AcqRel => panic!("there is no such thing as an acquire/release store"),
1285 unsafe fn atomic_load<T>(dst: *const T, order: Ordering) -> T {
1287 Acquire => intrinsics::atomic_load_acq(dst),
1288 Relaxed => intrinsics::atomic_load_relaxed(dst),
1289 SeqCst => intrinsics::atomic_load(dst),
1290 Release => panic!("there is no such thing as a release load"),
1291 AcqRel => panic!("there is no such thing as an acquire/release load"),
1296 unsafe fn atomic_swap<T>(dst: *mut T, val: T, order: Ordering) -> T {
1298 Acquire => intrinsics::atomic_xchg_acq(dst, val),
1299 Release => intrinsics::atomic_xchg_rel(dst, val),
1300 AcqRel => intrinsics::atomic_xchg_acqrel(dst, val),
1301 Relaxed => intrinsics::atomic_xchg_relaxed(dst, val),
1302 SeqCst => intrinsics::atomic_xchg(dst, val)
1306 /// Returns the old value (like __sync_fetch_and_add).
1308 unsafe fn atomic_add<T>(dst: *mut T, val: T, order: Ordering) -> T {
1310 Acquire => intrinsics::atomic_xadd_acq(dst, val),
1311 Release => intrinsics::atomic_xadd_rel(dst, val),
1312 AcqRel => intrinsics::atomic_xadd_acqrel(dst, val),
1313 Relaxed => intrinsics::atomic_xadd_relaxed(dst, val),
1314 SeqCst => intrinsics::atomic_xadd(dst, val)
1318 /// Returns the old value (like __sync_fetch_and_sub).
1320 unsafe fn atomic_sub<T>(dst: *mut T, val: T, order: Ordering) -> T {
1322 Acquire => intrinsics::atomic_xsub_acq(dst, val),
1323 Release => intrinsics::atomic_xsub_rel(dst, val),
1324 AcqRel => intrinsics::atomic_xsub_acqrel(dst, val),
1325 Relaxed => intrinsics::atomic_xsub_relaxed(dst, val),
1326 SeqCst => intrinsics::atomic_xsub(dst, val)
1331 unsafe fn atomic_compare_exchange<T>(dst: *mut T,
1335 failure: Ordering) -> Result<T, T> {
1336 let (val, ok) = match (success, failure) {
1337 (Acquire, Acquire) => intrinsics::atomic_cxchg_acq(dst, old, new),
1338 (Release, Relaxed) => intrinsics::atomic_cxchg_rel(dst, old, new),
1339 (AcqRel, Acquire) => intrinsics::atomic_cxchg_acqrel(dst, old, new),
1340 (Relaxed, Relaxed) => intrinsics::atomic_cxchg_relaxed(dst, old, new),
1341 (SeqCst, SeqCst) => intrinsics::atomic_cxchg(dst, old, new),
1342 (Acquire, Relaxed) => intrinsics::atomic_cxchg_acq_failrelaxed(dst, old, new),
1343 (AcqRel, Relaxed) => intrinsics::atomic_cxchg_acqrel_failrelaxed(dst, old, new),
1344 (SeqCst, Relaxed) => intrinsics::atomic_cxchg_failrelaxed(dst, old, new),
1345 (SeqCst, Acquire) => intrinsics::atomic_cxchg_failacq(dst, old, new),
1346 (_, AcqRel) => panic!("there is no such thing as an acquire/release failure ordering"),
1347 (_, Release) => panic!("there is no such thing as a release failure ordering"),
1348 _ => panic!("a failure ordering can't be stronger than a success ordering"),
1358 unsafe fn atomic_compare_exchange_weak<T>(dst: *mut T,
1362 failure: Ordering) -> Result<T, T> {
1363 let (val, ok) = match (success, failure) {
1364 (Acquire, Acquire) => intrinsics::atomic_cxchgweak_acq(dst, old, new),
1365 (Release, Relaxed) => intrinsics::atomic_cxchgweak_rel(dst, old, new),
1366 (AcqRel, Acquire) => intrinsics::atomic_cxchgweak_acqrel(dst, old, new),
1367 (Relaxed, Relaxed) => intrinsics::atomic_cxchgweak_relaxed(dst, old, new),
1368 (SeqCst, SeqCst) => intrinsics::atomic_cxchgweak(dst, old, new),
1369 (Acquire, Relaxed) => intrinsics::atomic_cxchgweak_acq_failrelaxed(dst, old, new),
1370 (AcqRel, Relaxed) => intrinsics::atomic_cxchgweak_acqrel_failrelaxed(dst, old, new),
1371 (SeqCst, Relaxed) => intrinsics::atomic_cxchgweak_failrelaxed(dst, old, new),
1372 (SeqCst, Acquire) => intrinsics::atomic_cxchgweak_failacq(dst, old, new),
1373 (_, AcqRel) => panic!("there is no such thing as an acquire/release failure ordering"),
1374 (_, Release) => panic!("there is no such thing as a release failure ordering"),
1375 _ => panic!("a failure ordering can't be stronger than a success ordering"),
1385 unsafe fn atomic_and<T>(dst: *mut T, val: T, order: Ordering) -> T {
1387 Acquire => intrinsics::atomic_and_acq(dst, val),
1388 Release => intrinsics::atomic_and_rel(dst, val),
1389 AcqRel => intrinsics::atomic_and_acqrel(dst, val),
1390 Relaxed => intrinsics::atomic_and_relaxed(dst, val),
1391 SeqCst => intrinsics::atomic_and(dst, val)
1396 unsafe fn atomic_or<T>(dst: *mut T, val: T, order: Ordering) -> T {
1398 Acquire => intrinsics::atomic_or_acq(dst, val),
1399 Release => intrinsics::atomic_or_rel(dst, val),
1400 AcqRel => intrinsics::atomic_or_acqrel(dst, val),
1401 Relaxed => intrinsics::atomic_or_relaxed(dst, val),
1402 SeqCst => intrinsics::atomic_or(dst, val)
1407 unsafe fn atomic_xor<T>(dst: *mut T, val: T, order: Ordering) -> T {
1409 Acquire => intrinsics::atomic_xor_acq(dst, val),
1410 Release => intrinsics::atomic_xor_rel(dst, val),
1411 AcqRel => intrinsics::atomic_xor_acqrel(dst, val),
1412 Relaxed => intrinsics::atomic_xor_relaxed(dst, val),
1413 SeqCst => intrinsics::atomic_xor(dst, val)
1417 /// An atomic fence.
1419 /// A fence 'A' which has `Release` ordering semantics, synchronizes with a
1420 /// fence 'B' with (at least) `Acquire` semantics, if and only if there exists
1421 /// atomic operations X and Y, both operating on some atomic object 'M' such
1422 /// that A is sequenced before X, Y is synchronized before B and Y observes
1423 /// the change to M. This provides a happens-before dependence between A and B.
1425 /// Atomic operations with `Release` or `Acquire` semantics can also synchronize
1428 /// A fence which has `SeqCst` ordering, in addition to having both `Acquire`
1429 /// and `Release` semantics, participates in the global program order of the
1430 /// other `SeqCst` operations and/or fences.
1432 /// Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings.
1436 /// Panics if `order` is `Relaxed`.
1438 #[stable(feature = "rust1", since = "1.0.0")]
1439 pub fn fence(order: Ordering) {
1442 Acquire => intrinsics::atomic_fence_acq(),
1443 Release => intrinsics::atomic_fence_rel(),
1444 AcqRel => intrinsics::atomic_fence_acqrel(),
1445 SeqCst => intrinsics::atomic_fence(),
1446 Relaxed => panic!("there is no such thing as a relaxed fence")
1452 #[cfg(target_has_atomic = "8")]
1453 #[stable(feature = "atomic_debug", since = "1.3.0")]
1454 impl fmt::Debug for AtomicBool {
1455 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1456 f.debug_tuple("AtomicBool").field(&self.load(Ordering::SeqCst)).finish()
1460 #[cfg(target_has_atomic = "ptr")]
1461 #[stable(feature = "atomic_debug", since = "1.3.0")]
1462 impl<T> fmt::Debug for AtomicPtr<T> {
1463 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1464 f.debug_tuple("AtomicPtr").field(&self.load(Ordering::SeqCst)).finish()