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. The most
30 //! common way to share an atomic variable is to put it into an `Arc` (an
31 //! atomically-reference-counted shared pointer).
33 //! Most atomic types may be stored in static variables, initialized using
34 //! the provided static initializers like `INIT_ATOMIC_BOOL`. Atomic statics
35 //! are often used for lazy global initialization.
40 //! A simple spinlock:
43 //! use std::sync::Arc;
44 //! use std::sync::atomic::{AtomicUsize, Ordering};
48 //! let spinlock = Arc::new(AtomicUsize::new(1));
50 //! let spinlock_clone = spinlock.clone();
51 //! thread::spawn(move|| {
52 //! spinlock_clone.store(0, Ordering::SeqCst);
55 //! // Wait for the other thread to release the lock
56 //! while spinlock.load(Ordering::SeqCst) != 0 {}
60 //! Keep a global count of live threads:
63 //! use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT};
65 //! static GLOBAL_THREAD_COUNT: AtomicUsize = ATOMIC_USIZE_INIT;
67 //! let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::SeqCst);
68 //! println!("live threads: {}", old_thread_count + 1);
71 #![stable(feature = "rust1", since = "1.0.0")]
73 use self::Ordering
::*;
82 /// A boolean type which can be safely shared between threads.
83 #[stable(feature = "rust1", since = "1.0.0")]
84 pub struct AtomicBool
{
88 impl Default
for AtomicBool
{
89 fn default() -> Self {
90 Self::new(Default
::default())
94 unsafe impl Sync
for AtomicBool {}
96 /// A signed integer type which can be safely shared between threads.
97 #[stable(feature = "rust1", since = "1.0.0")]
98 pub struct AtomicIsize
{
102 impl Default
for AtomicIsize
{
103 fn default() -> Self {
104 Self::new(Default
::default())
108 unsafe impl Sync
for AtomicIsize {}
110 /// An unsigned integer type which can be safely shared between threads.
111 #[stable(feature = "rust1", since = "1.0.0")]
112 pub struct AtomicUsize
{
113 v
: UnsafeCell
<usize>,
116 impl Default
for AtomicUsize
{
117 fn default() -> Self {
118 Self::new(Default
::default())
122 unsafe impl Sync
for AtomicUsize {}
124 /// A raw pointer type which can be safely shared between threads.
125 #[stable(feature = "rust1", since = "1.0.0")]
126 pub struct AtomicPtr
<T
> {
127 p
: UnsafeCell
<*mut T
>,
130 impl<T
> Default
for AtomicPtr
<T
> {
131 fn default() -> AtomicPtr
<T
> {
132 AtomicPtr
::new(::ptr
::null_mut())
136 unsafe impl<T
> Sync
for AtomicPtr
<T
> {}
138 /// Atomic memory orderings
140 /// Memory orderings limit the ways that both the compiler and CPU may reorder
141 /// instructions around atomic operations. At its most restrictive,
142 /// "sequentially consistent" atomics allow neither reads nor writes
143 /// to be moved either before or after the atomic operation; on the other end
144 /// "relaxed" atomics allow all reorderings.
146 /// Rust's memory orderings are [the same as
147 /// C++'s](http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync).
148 #[stable(feature = "rust1", since = "1.0.0")]
149 #[derive(Copy, Clone)]
151 /// No ordering constraints, only atomic operations.
152 #[stable(feature = "rust1", since = "1.0.0")]
154 /// When coupled with a store, all previous writes become visible
155 /// to another thread that performs a load with `Acquire` ordering
156 /// on the same value.
157 #[stable(feature = "rust1", since = "1.0.0")]
159 /// When coupled with a load, all subsequent loads will see data
160 /// written before a store with `Release` ordering on the same value
161 /// in another thread.
162 #[stable(feature = "rust1", since = "1.0.0")]
164 /// When coupled with a load, uses `Acquire` ordering, and with a store
165 /// `Release` ordering.
166 #[stable(feature = "rust1", since = "1.0.0")]
168 /// Like `AcqRel` with the additional guarantee that all threads see all
169 /// sequentially consistent operations in the same order.
170 #[stable(feature = "rust1", since = "1.0.0")]
174 /// An `AtomicBool` initialized to `false`.
175 #[stable(feature = "rust1", since = "1.0.0")]
176 pub const ATOMIC_BOOL_INIT
: AtomicBool
= AtomicBool
::new(false);
177 /// An `AtomicIsize` initialized to `0`.
178 #[stable(feature = "rust1", since = "1.0.0")]
179 pub const ATOMIC_ISIZE_INIT
: AtomicIsize
= AtomicIsize
::new(0);
180 /// An `AtomicUsize` initialized to `0`.
181 #[stable(feature = "rust1", since = "1.0.0")]
182 pub const ATOMIC_USIZE_INIT
: AtomicUsize
= AtomicUsize
::new(0);
184 // NB: Needs to be -1 (0b11111111...) to make fetch_nand work correctly
185 const UINT_TRUE
: usize = !0;
188 /// Creates a new `AtomicBool`.
193 /// use std::sync::atomic::AtomicBool;
195 /// let atomic_true = AtomicBool::new(true);
196 /// let atomic_false = AtomicBool::new(false);
199 #[stable(feature = "rust1", since = "1.0.0")]
200 pub const fn new(v
: bool
) -> AtomicBool
{
201 AtomicBool { v: UnsafeCell::new(-(v as isize) as usize) }
204 /// Loads a value from the bool.
206 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
210 /// Panics if `order` is `Release` or `AcqRel`.
215 /// use std::sync::atomic::{AtomicBool, Ordering};
217 /// let some_bool = AtomicBool::new(true);
219 /// assert_eq!(some_bool.load(Ordering::Relaxed), true);
222 #[stable(feature = "rust1", since = "1.0.0")]
223 pub fn load(&self, order
: Ordering
) -> bool
{
224 unsafe { atomic_load(self.v.get(), order) > 0 }
227 /// Stores a value into the bool.
229 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
234 /// use std::sync::atomic::{AtomicBool, Ordering};
236 /// let some_bool = AtomicBool::new(true);
238 /// some_bool.store(false, Ordering::Relaxed);
239 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
244 /// Panics if `order` is `Acquire` or `AcqRel`.
246 #[stable(feature = "rust1", since = "1.0.0")]
247 pub fn store(&self, val
: bool
, order
: Ordering
) {
248 let val
= if val { UINT_TRUE }
else { 0 }
;
250 unsafe { atomic_store(self.v.get(), val, order); }
253 /// Stores a value into the bool, returning the old value.
255 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
260 /// use std::sync::atomic::{AtomicBool, Ordering};
262 /// let some_bool = AtomicBool::new(true);
264 /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true);
265 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
268 #[stable(feature = "rust1", since = "1.0.0")]
269 pub fn swap(&self, val
: bool
, order
: Ordering
) -> bool
{
270 let val
= if val { UINT_TRUE }
else { 0 }
;
272 unsafe { atomic_swap(self.v.get(), val, order) > 0 }
275 /// Stores a value into the bool if the current value is the same as the expected value.
277 /// The return value is always the previous value. If it is equal to `old`, then the value was
280 /// `swap` also takes an `Ordering` argument which describes the memory ordering of this
286 /// use std::sync::atomic::{AtomicBool, Ordering};
288 /// let some_bool = AtomicBool::new(true);
290 /// assert_eq!(some_bool.compare_and_swap(true, false, Ordering::Relaxed), true);
291 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
293 /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false);
294 /// assert_eq!(some_bool.load(Ordering::Relaxed), false);
297 #[stable(feature = "rust1", since = "1.0.0")]
298 pub fn compare_and_swap(&self, old
: bool
, new
: bool
, order
: Ordering
) -> bool
{
299 let old
= if old { UINT_TRUE }
else { 0 }
;
300 let new
= if new { UINT_TRUE }
else { 0 }
;
302 unsafe { atomic_compare_and_swap(self.v.get(), old, new, order) > 0 }
305 /// Logical "and" with a boolean value.
307 /// Performs a logical "and" operation on the current value and the argument `val`, and sets
308 /// the new value to the result.
310 /// Returns the previous value.
315 /// use std::sync::atomic::{AtomicBool, Ordering};
317 /// let foo = AtomicBool::new(true);
318 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), true);
319 /// assert_eq!(foo.load(Ordering::SeqCst), false);
321 /// let foo = AtomicBool::new(true);
322 /// assert_eq!(foo.fetch_and(true, Ordering::SeqCst), true);
323 /// assert_eq!(foo.load(Ordering::SeqCst), true);
325 /// let foo = AtomicBool::new(false);
326 /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false);
327 /// assert_eq!(foo.load(Ordering::SeqCst), false);
330 #[stable(feature = "rust1", since = "1.0.0")]
331 pub fn fetch_and(&self, val
: bool
, order
: Ordering
) -> bool
{
332 let val
= if val { UINT_TRUE }
else { 0 }
;
334 unsafe { atomic_and(self.v.get(), val, order) > 0 }
337 /// Logical "nand" with a boolean value.
339 /// Performs a logical "nand" operation on the current value and the argument `val`, and sets
340 /// the new value to the result.
342 /// Returns the previous value.
347 /// use std::sync::atomic::{AtomicBool, Ordering};
349 /// let foo = AtomicBool::new(true);
350 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), true);
351 /// assert_eq!(foo.load(Ordering::SeqCst), true);
353 /// let foo = AtomicBool::new(true);
354 /// assert_eq!(foo.fetch_nand(true, Ordering::SeqCst), true);
355 /// assert_eq!(foo.load(Ordering::SeqCst) as usize, 0);
356 /// assert_eq!(foo.load(Ordering::SeqCst), false);
358 /// let foo = AtomicBool::new(false);
359 /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false);
360 /// assert_eq!(foo.load(Ordering::SeqCst), true);
363 #[stable(feature = "rust1", since = "1.0.0")]
364 pub fn fetch_nand(&self, val
: bool
, order
: Ordering
) -> bool
{
365 let val
= if val { UINT_TRUE }
else { 0 }
;
367 unsafe { atomic_nand(self.v.get(), val, order) > 0 }
370 /// Logical "or" with a boolean value.
372 /// Performs a logical "or" operation on the current value and the argument `val`, and sets the
373 /// new value to the result.
375 /// Returns the previous value.
380 /// use std::sync::atomic::{AtomicBool, Ordering};
382 /// let foo = AtomicBool::new(true);
383 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), true);
384 /// assert_eq!(foo.load(Ordering::SeqCst), true);
386 /// let foo = AtomicBool::new(true);
387 /// assert_eq!(foo.fetch_or(true, Ordering::SeqCst), true);
388 /// assert_eq!(foo.load(Ordering::SeqCst), true);
390 /// let foo = AtomicBool::new(false);
391 /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false);
392 /// assert_eq!(foo.load(Ordering::SeqCst), false);
395 #[stable(feature = "rust1", since = "1.0.0")]
396 pub fn fetch_or(&self, val
: bool
, order
: Ordering
) -> bool
{
397 let val
= if val { UINT_TRUE }
else { 0 }
;
399 unsafe { atomic_or(self.v.get(), val, order) > 0 }
402 /// Logical "xor" with a boolean value.
404 /// Performs a logical "xor" operation on the current value and the argument `val`, and sets
405 /// the new value to the result.
407 /// Returns the previous value.
412 /// use std::sync::atomic::{AtomicBool, Ordering};
414 /// let foo = AtomicBool::new(true);
415 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), true);
416 /// assert_eq!(foo.load(Ordering::SeqCst), true);
418 /// let foo = AtomicBool::new(true);
419 /// assert_eq!(foo.fetch_xor(true, Ordering::SeqCst), true);
420 /// assert_eq!(foo.load(Ordering::SeqCst), false);
422 /// let foo = AtomicBool::new(false);
423 /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false);
424 /// assert_eq!(foo.load(Ordering::SeqCst), false);
427 #[stable(feature = "rust1", since = "1.0.0")]
428 pub fn fetch_xor(&self, val
: bool
, order
: Ordering
) -> bool
{
429 let val
= if val { UINT_TRUE }
else { 0 }
;
431 unsafe { atomic_xor(self.v.get(), val, order) > 0 }
435 #[stable(feature = "rust1", since = "1.0.0")]
437 /// Creates a new `AtomicIsize`.
442 /// use std::sync::atomic::AtomicIsize;
444 /// let atomic_forty_two = AtomicIsize::new(42);
447 #[stable(feature = "rust1", since = "1.0.0")]
448 pub const fn new(v
: isize) -> AtomicIsize
{
449 AtomicIsize {v: UnsafeCell::new(v)}
452 /// Loads a value from the isize.
454 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
458 /// Panics if `order` is `Release` or `AcqRel`.
463 /// use std::sync::atomic::{AtomicIsize, Ordering};
465 /// let some_isize = AtomicIsize::new(5);
467 /// assert_eq!(some_isize.load(Ordering::Relaxed), 5);
470 #[stable(feature = "rust1", since = "1.0.0")]
471 pub fn load(&self, order
: Ordering
) -> isize {
472 unsafe { atomic_load(self.v.get(), order) }
475 /// Stores a value into the isize.
477 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
482 /// use std::sync::atomic::{AtomicIsize, Ordering};
484 /// let some_isize = AtomicIsize::new(5);
486 /// some_isize.store(10, Ordering::Relaxed);
487 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
492 /// Panics if `order` is `Acquire` or `AcqRel`.
494 #[stable(feature = "rust1", since = "1.0.0")]
495 pub fn store(&self, val
: isize, order
: Ordering
) {
496 unsafe { atomic_store(self.v.get(), val, order); }
499 /// Stores a value into the isize, returning the old value.
501 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
506 /// use std::sync::atomic::{AtomicIsize, Ordering};
508 /// let some_isize = AtomicIsize::new(5);
510 /// assert_eq!(some_isize.swap(10, Ordering::Relaxed), 5);
513 #[stable(feature = "rust1", since = "1.0.0")]
514 pub fn swap(&self, val
: isize, order
: Ordering
) -> isize {
515 unsafe { atomic_swap(self.v.get(), val, order) }
518 /// Stores a value into the isize if the current value is the same as the expected value.
520 /// The return value is always the previous value. If it is equal to `old`, then the value was
523 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory ordering of
529 /// use std::sync::atomic::{AtomicIsize, Ordering};
531 /// let some_isize = AtomicIsize::new(5);
533 /// assert_eq!(some_isize.compare_and_swap(5, 10, Ordering::Relaxed), 5);
534 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
536 /// assert_eq!(some_isize.compare_and_swap(6, 12, Ordering::Relaxed), 10);
537 /// assert_eq!(some_isize.load(Ordering::Relaxed), 10);
540 #[stable(feature = "rust1", since = "1.0.0")]
541 pub fn compare_and_swap(&self, old
: isize, new
: isize, order
: Ordering
) -> isize {
542 unsafe { atomic_compare_and_swap(self.v.get(), old, new, order) }
545 /// Add an isize to the current value, returning the previous value.
550 /// use std::sync::atomic::{AtomicIsize, Ordering};
552 /// let foo = AtomicIsize::new(0);
553 /// assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0);
554 /// assert_eq!(foo.load(Ordering::SeqCst), 10);
557 #[stable(feature = "rust1", since = "1.0.0")]
558 pub fn fetch_add(&self, val
: isize, order
: Ordering
) -> isize {
559 unsafe { atomic_add(self.v.get(), val, order) }
562 /// Subtract an isize from the current value, returning the previous value.
567 /// use std::sync::atomic::{AtomicIsize, Ordering};
569 /// let foo = AtomicIsize::new(0);
570 /// assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 0);
571 /// assert_eq!(foo.load(Ordering::SeqCst), -10);
574 #[stable(feature = "rust1", since = "1.0.0")]
575 pub fn fetch_sub(&self, val
: isize, order
: Ordering
) -> isize {
576 unsafe { atomic_sub(self.v.get(), val, order) }
579 /// Bitwise and with the current isize, returning the previous value.
584 /// use std::sync::atomic::{AtomicIsize, Ordering};
586 /// let foo = AtomicIsize::new(0b101101);
587 /// assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101);
588 /// assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
590 #[stable(feature = "rust1", since = "1.0.0")]
591 pub fn fetch_and(&self, val
: isize, order
: Ordering
) -> isize {
592 unsafe { atomic_and(self.v.get(), val, order) }
595 /// Bitwise or with the current isize, returning the previous value.
600 /// use std::sync::atomic::{AtomicIsize, Ordering};
602 /// let foo = AtomicIsize::new(0b101101);
603 /// assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101);
604 /// assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
606 #[stable(feature = "rust1", since = "1.0.0")]
607 pub fn fetch_or(&self, val
: isize, order
: Ordering
) -> isize {
608 unsafe { atomic_or(self.v.get(), val, order) }
611 /// Bitwise xor with the current isize, returning the previous value.
616 /// use std::sync::atomic::{AtomicIsize, Ordering};
618 /// let foo = AtomicIsize::new(0b101101);
619 /// assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101);
620 /// assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
622 #[stable(feature = "rust1", since = "1.0.0")]
623 pub fn fetch_xor(&self, val
: isize, order
: Ordering
) -> isize {
624 unsafe { atomic_xor(self.v.get(), val, order) }
628 #[stable(feature = "rust1", since = "1.0.0")]
630 /// Creates a new `AtomicUsize`.
635 /// use std::sync::atomic::AtomicUsize;
637 /// let atomic_forty_two = AtomicUsize::new(42);
640 #[stable(feature = "rust1", since = "1.0.0")]
641 pub const fn new(v
: usize) -> AtomicUsize
{
642 AtomicUsize { v: UnsafeCell::new(v) }
645 /// Loads a value from the usize.
647 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
651 /// Panics if `order` is `Release` or `AcqRel`.
656 /// use std::sync::atomic::{AtomicUsize, Ordering};
658 /// let some_usize = AtomicUsize::new(5);
660 /// assert_eq!(some_usize.load(Ordering::Relaxed), 5);
663 #[stable(feature = "rust1", since = "1.0.0")]
664 pub fn load(&self, order
: Ordering
) -> usize {
665 unsafe { atomic_load(self.v.get(), order) }
668 /// Stores a value into the usize.
670 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
675 /// use std::sync::atomic::{AtomicUsize, Ordering};
677 /// let some_usize = AtomicUsize::new(5);
679 /// some_usize.store(10, Ordering::Relaxed);
680 /// assert_eq!(some_usize.load(Ordering::Relaxed), 10);
685 /// Panics if `order` is `Acquire` or `AcqRel`.
687 #[stable(feature = "rust1", since = "1.0.0")]
688 pub fn store(&self, val
: usize, order
: Ordering
) {
689 unsafe { atomic_store(self.v.get(), val, order); }
692 /// Stores a value into the usize, returning the old value.
694 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
699 /// use std::sync::atomic::{AtomicUsize, Ordering};
701 /// let some_usize= AtomicUsize::new(5);
703 /// assert_eq!(some_usize.swap(10, Ordering::Relaxed), 5);
704 /// assert_eq!(some_usize.load(Ordering::Relaxed), 10);
707 #[stable(feature = "rust1", since = "1.0.0")]
708 pub fn swap(&self, val
: usize, order
: Ordering
) -> usize {
709 unsafe { atomic_swap(self.v.get(), val, order) }
712 /// Stores a value into the usize if the current value is the same as the expected value.
714 /// The return value is always the previous value. If it is equal to `old`, then the value was
717 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory ordering of
723 /// use std::sync::atomic::{AtomicUsize, Ordering};
725 /// let some_usize = AtomicUsize::new(5);
727 /// assert_eq!(some_usize.compare_and_swap(5, 10, Ordering::Relaxed), 5);
728 /// assert_eq!(some_usize.load(Ordering::Relaxed), 10);
730 /// assert_eq!(some_usize.compare_and_swap(6, 12, Ordering::Relaxed), 10);
731 /// assert_eq!(some_usize.load(Ordering::Relaxed), 10);
734 #[stable(feature = "rust1", since = "1.0.0")]
735 pub fn compare_and_swap(&self, old
: usize, new
: usize, order
: Ordering
) -> usize {
736 unsafe { atomic_compare_and_swap(self.v.get(), old, new, order) }
739 /// Add to the current usize, returning the previous value.
744 /// use std::sync::atomic::{AtomicUsize, Ordering};
746 /// let foo = AtomicUsize::new(0);
747 /// assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0);
748 /// assert_eq!(foo.load(Ordering::SeqCst), 10);
751 #[stable(feature = "rust1", since = "1.0.0")]
752 pub fn fetch_add(&self, val
: usize, order
: Ordering
) -> usize {
753 unsafe { atomic_add(self.v.get(), val, order) }
756 /// Subtract from the current usize, returning the previous value.
761 /// use std::sync::atomic::{AtomicUsize, Ordering};
763 /// let foo = AtomicUsize::new(10);
764 /// assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 10);
765 /// assert_eq!(foo.load(Ordering::SeqCst), 0);
768 #[stable(feature = "rust1", since = "1.0.0")]
769 pub fn fetch_sub(&self, val
: usize, order
: Ordering
) -> usize {
770 unsafe { atomic_sub(self.v.get(), val, order) }
773 /// Bitwise and with the current usize, returning the previous value.
778 /// use std::sync::atomic::{AtomicUsize, Ordering};
780 /// let foo = AtomicUsize::new(0b101101);
781 /// assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101);
782 /// assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
784 #[stable(feature = "rust1", since = "1.0.0")]
785 pub fn fetch_and(&self, val
: usize, order
: Ordering
) -> usize {
786 unsafe { atomic_and(self.v.get(), val, order) }
789 /// Bitwise or with the current usize, returning the previous value.
794 /// use std::sync::atomic::{AtomicUsize, Ordering};
796 /// let foo = AtomicUsize::new(0b101101);
797 /// assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101);
798 /// assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
800 #[stable(feature = "rust1", since = "1.0.0")]
801 pub fn fetch_or(&self, val
: usize, order
: Ordering
) -> usize {
802 unsafe { atomic_or(self.v.get(), val, order) }
805 /// Bitwise xor with the current usize, returning the previous value.
810 /// use std::sync::atomic::{AtomicUsize, Ordering};
812 /// let foo = AtomicUsize::new(0b101101);
813 /// assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101);
814 /// assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
816 #[stable(feature = "rust1", since = "1.0.0")]
817 pub fn fetch_xor(&self, val
: usize, order
: Ordering
) -> usize {
818 unsafe { atomic_xor(self.v.get(), val, order) }
822 impl<T
> AtomicPtr
<T
> {
823 /// Creates a new `AtomicPtr`.
828 /// use std::sync::atomic::AtomicPtr;
830 /// let ptr = &mut 5;
831 /// let atomic_ptr = AtomicPtr::new(ptr);
834 #[stable(feature = "rust1", since = "1.0.0")]
835 pub const fn new(p
: *mut T
) -> AtomicPtr
<T
> {
836 AtomicPtr { p: UnsafeCell::new(p) }
839 /// Loads a value from the pointer.
841 /// `load` takes an `Ordering` argument which describes the memory ordering of this operation.
845 /// Panics if `order` is `Release` or `AcqRel`.
850 /// use std::sync::atomic::{AtomicPtr, Ordering};
852 /// let ptr = &mut 5;
853 /// let some_ptr = AtomicPtr::new(ptr);
855 /// let value = some_ptr.load(Ordering::Relaxed);
858 #[stable(feature = "rust1", since = "1.0.0")]
859 pub fn load(&self, order
: Ordering
) -> *mut T
{
861 atomic_load(self.p
.get() as *mut usize, order
) as *mut T
865 /// Stores a value into the pointer.
867 /// `store` takes an `Ordering` argument which describes the memory ordering of this operation.
872 /// use std::sync::atomic::{AtomicPtr, Ordering};
874 /// let ptr = &mut 5;
875 /// let some_ptr = AtomicPtr::new(ptr);
877 /// let other_ptr = &mut 10;
879 /// some_ptr.store(other_ptr, Ordering::Relaxed);
884 /// Panics if `order` is `Acquire` or `AcqRel`.
886 #[stable(feature = "rust1", since = "1.0.0")]
887 pub fn store(&self, ptr
: *mut T
, order
: Ordering
) {
888 unsafe { atomic_store(self.p.get() as *mut usize, ptr as usize, order); }
891 /// Stores a value into the pointer, returning the old value.
893 /// `swap` takes an `Ordering` argument which describes the memory ordering of this operation.
898 /// use std::sync::atomic::{AtomicPtr, Ordering};
900 /// let ptr = &mut 5;
901 /// let some_ptr = AtomicPtr::new(ptr);
903 /// let other_ptr = &mut 10;
905 /// let value = some_ptr.swap(other_ptr, Ordering::Relaxed);
908 #[stable(feature = "rust1", since = "1.0.0")]
909 pub fn swap(&self, ptr
: *mut T
, order
: Ordering
) -> *mut T
{
910 unsafe { atomic_swap(self.p.get() as *mut usize, ptr as usize, order) as *mut T }
913 /// Stores a value into the pointer if the current value is the same as the expected value.
915 /// The return value is always the previous value. If it is equal to `old`, then the value was
918 /// `compare_and_swap` also takes an `Ordering` argument which describes the memory ordering of
924 /// use std::sync::atomic::{AtomicPtr, Ordering};
926 /// let ptr = &mut 5;
927 /// let some_ptr = AtomicPtr::new(ptr);
929 /// let other_ptr = &mut 10;
930 /// let another_ptr = &mut 10;
932 /// let value = some_ptr.compare_and_swap(other_ptr, another_ptr, Ordering::Relaxed);
935 #[stable(feature = "rust1", since = "1.0.0")]
936 pub fn compare_and_swap(&self, old
: *mut T
, new
: *mut T
, order
: Ordering
) -> *mut T
{
938 atomic_compare_and_swap(self.p
.get() as *mut usize, old
as usize,
939 new
as usize, order
) as *mut T
945 unsafe fn atomic_store
<T
>(dst
: *mut T
, val
: T
, order
:Ordering
) {
947 Release
=> intrinsics
::atomic_store_rel(dst
, val
),
948 Relaxed
=> intrinsics
::atomic_store_relaxed(dst
, val
),
949 SeqCst
=> intrinsics
::atomic_store(dst
, val
),
950 Acquire
=> panic
!("there is no such thing as an acquire store"),
951 AcqRel
=> panic
!("there is no such thing as an acquire/release store"),
956 #[stable(feature = "rust1", since = "1.0.0")]
957 unsafe fn atomic_load
<T
>(dst
: *const T
, order
:Ordering
) -> T
{
959 Acquire
=> intrinsics
::atomic_load_acq(dst
),
960 Relaxed
=> intrinsics
::atomic_load_relaxed(dst
),
961 SeqCst
=> intrinsics
::atomic_load(dst
),
962 Release
=> panic
!("there is no such thing as a release load"),
963 AcqRel
=> panic
!("there is no such thing as an acquire/release load"),
968 #[stable(feature = "rust1", since = "1.0.0")]
969 unsafe fn atomic_swap
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
971 Acquire
=> intrinsics
::atomic_xchg_acq(dst
, val
),
972 Release
=> intrinsics
::atomic_xchg_rel(dst
, val
),
973 AcqRel
=> intrinsics
::atomic_xchg_acqrel(dst
, val
),
974 Relaxed
=> intrinsics
::atomic_xchg_relaxed(dst
, val
),
975 SeqCst
=> intrinsics
::atomic_xchg(dst
, val
)
979 /// Returns the old value (like __sync_fetch_and_add).
981 #[stable(feature = "rust1", since = "1.0.0")]
982 unsafe fn atomic_add
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
984 Acquire
=> intrinsics
::atomic_xadd_acq(dst
, val
),
985 Release
=> intrinsics
::atomic_xadd_rel(dst
, val
),
986 AcqRel
=> intrinsics
::atomic_xadd_acqrel(dst
, val
),
987 Relaxed
=> intrinsics
::atomic_xadd_relaxed(dst
, val
),
988 SeqCst
=> intrinsics
::atomic_xadd(dst
, val
)
992 /// Returns the old value (like __sync_fetch_and_sub).
994 #[stable(feature = "rust1", since = "1.0.0")]
995 unsafe fn atomic_sub
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
997 Acquire
=> intrinsics
::atomic_xsub_acq(dst
, val
),
998 Release
=> intrinsics
::atomic_xsub_rel(dst
, val
),
999 AcqRel
=> intrinsics
::atomic_xsub_acqrel(dst
, val
),
1000 Relaxed
=> intrinsics
::atomic_xsub_relaxed(dst
, val
),
1001 SeqCst
=> intrinsics
::atomic_xsub(dst
, val
)
1006 #[stable(feature = "rust1", since = "1.0.0")]
1007 unsafe fn atomic_compare_and_swap
<T
>(dst
: *mut T
, old
:T
, new
:T
, order
: Ordering
) -> T
{
1009 Acquire
=> intrinsics
::atomic_cxchg_acq(dst
, old
, new
),
1010 Release
=> intrinsics
::atomic_cxchg_rel(dst
, old
, new
),
1011 AcqRel
=> intrinsics
::atomic_cxchg_acqrel(dst
, old
, new
),
1012 Relaxed
=> intrinsics
::atomic_cxchg_relaxed(dst
, old
, new
),
1013 SeqCst
=> intrinsics
::atomic_cxchg(dst
, old
, new
),
1018 #[stable(feature = "rust1", since = "1.0.0")]
1019 unsafe fn atomic_and
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
1021 Acquire
=> intrinsics
::atomic_and_acq(dst
, val
),
1022 Release
=> intrinsics
::atomic_and_rel(dst
, val
),
1023 AcqRel
=> intrinsics
::atomic_and_acqrel(dst
, val
),
1024 Relaxed
=> intrinsics
::atomic_and_relaxed(dst
, val
),
1025 SeqCst
=> intrinsics
::atomic_and(dst
, val
)
1030 #[stable(feature = "rust1", since = "1.0.0")]
1031 unsafe fn atomic_nand
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
1033 Acquire
=> intrinsics
::atomic_nand_acq(dst
, val
),
1034 Release
=> intrinsics
::atomic_nand_rel(dst
, val
),
1035 AcqRel
=> intrinsics
::atomic_nand_acqrel(dst
, val
),
1036 Relaxed
=> intrinsics
::atomic_nand_relaxed(dst
, val
),
1037 SeqCst
=> intrinsics
::atomic_nand(dst
, val
)
1043 #[stable(feature = "rust1", since = "1.0.0")]
1044 unsafe fn atomic_or
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
1046 Acquire
=> intrinsics
::atomic_or_acq(dst
, val
),
1047 Release
=> intrinsics
::atomic_or_rel(dst
, val
),
1048 AcqRel
=> intrinsics
::atomic_or_acqrel(dst
, val
),
1049 Relaxed
=> intrinsics
::atomic_or_relaxed(dst
, val
),
1050 SeqCst
=> intrinsics
::atomic_or(dst
, val
)
1056 #[stable(feature = "rust1", since = "1.0.0")]
1057 unsafe fn atomic_xor
<T
>(dst
: *mut T
, val
: T
, order
: Ordering
) -> T
{
1059 Acquire
=> intrinsics
::atomic_xor_acq(dst
, val
),
1060 Release
=> intrinsics
::atomic_xor_rel(dst
, val
),
1061 AcqRel
=> intrinsics
::atomic_xor_acqrel(dst
, val
),
1062 Relaxed
=> intrinsics
::atomic_xor_relaxed(dst
, val
),
1063 SeqCst
=> intrinsics
::atomic_xor(dst
, val
)
1068 /// An atomic fence.
1070 /// A fence 'A' which has `Release` ordering semantics, synchronizes with a
1071 /// fence 'B' with (at least) `Acquire` semantics, if and only if there exists
1072 /// atomic operations X and Y, both operating on some atomic object 'M' such
1073 /// that A is sequenced before X, Y is synchronized before B and Y observes
1074 /// the change to M. This provides a happens-before dependence between A and B.
1076 /// Atomic operations with `Release` or `Acquire` semantics can also synchronize
1079 /// A fence which has `SeqCst` ordering, in addition to having both `Acquire`
1080 /// and `Release` semantics, participates in the global program order of the
1081 /// other `SeqCst` operations and/or fences.
1083 /// Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings.
1087 /// Panics if `order` is `Relaxed`.
1089 #[stable(feature = "rust1", since = "1.0.0")]
1090 pub fn fence(order
: Ordering
) {
1093 Acquire
=> intrinsics
::atomic_fence_acq(),
1094 Release
=> intrinsics
::atomic_fence_rel(),
1095 AcqRel
=> intrinsics
::atomic_fence_acqrel(),
1096 SeqCst
=> intrinsics
::atomic_fence(),
1097 Relaxed
=> panic
!("there is no such thing as a relaxed fence")