From 749e527be61c05775e5c797b302e3863a955fd89 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Sun, 16 Mar 2014 16:05:01 -0700 Subject: [PATCH] std: Improve docs for atomics. Fix two bugs This adds lots of docs to the atomics module. Two of the examples are using the future atomics API and are ignored temporarily. I discovered a bug in the way AtomicBool's fetch_nand method is implemented and fixed it by using the correct value for `true`. I also fixed the implementation of AcqRel fences (it was only doing a release barrier), and made a "relaxed" fence a failure. --- src/libstd/sync/atomics.rs | 461 +++++++++++++++++++++++++++++++------ 1 file changed, 393 insertions(+), 68 deletions(-) diff --git a/src/libstd/sync/atomics.rs b/src/libstd/sync/atomics.rs index 86efa0875dc..500ae04869b 100644 --- a/src/libstd/sync/atomics.rs +++ b/src/libstd/sync/atomics.rs @@ -8,16 +8,104 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -/*! - * Atomic types - * - * Basic atomic types supporting atomic operations. Each method takes an - * `Ordering` which represents the strength of the memory barrier for that - * operation. These orderings are the same as C++11 atomic orderings - * [http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync] - * - * All atomic types are a single word in size. - */ +//! Atomic types +//! +//! Atomic types provide primitive shared-memory communication between +//! threads, and are the building blocks of other concurrent +//! types. +//! +//! This module defines atomic versions of a select number of primitive +//! types, including `AtomicBool`, `AtomicInt`, `AtomicUint`, and `AtomicOption`. +//! Atomic types present operations that, when used correctly, synchronize +//! updates between threads. +//! +//! Each method takes an `Ordering` which represents the strength of +//! the memory barrier for that operation. These orderings are the +//! same as [C++11 atomic orderings][1]. +//! +//! [1]: http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync +//! +//! Atomic variables are safe to share between threads (they implement `Share`) +//! but they do not themselves provide the mechanism for sharing. The most +//! common way to share an atomic variable is to put it into an `Arc` (an +//! atomically-reference-counted shared pointer). +//! +//! Most atomic types may be stored in static variables, initialized using +//! the provided static initializers like `INIT_ATOMIC_BOOL`. Atomic statics +//! are often used for lazy global initialization. +//! +//! +//! # Examples +//! +//! A simple spinlock: +//! +//! ```ignore +//! # // FIXME: Needs PR #12430 +//! extern crate sync; +//! +//! use sync::Arc; +//! use std::sync::atomics::{AtomicUint, SeqCst}; +//! use std::task::deschedule; +//! +//! fn main() { +//! let spinlock = Arc::new(AtomicUint::new(1)); +//! +//! let spinlock_clone = spinlock.clone(); +//! spawn(proc() { +//! spinlock_clone.store(0, SeqCst); +//! }); +//! +//! // Wait for the other task to release the lock +//! while spinlock.load(SeqCst) != 0 { +//! // Since tasks may not be preemptive (if they are green threads) +//! // yield to the scheduler to let the other task run. Low level +//! // concurrent code needs to take into account Rust's two threading +//! // models. +//! deschedule(); +//! } +//! } +//! ``` +//! +//! Transferring a heap object with `AtomicOption`: +//! +//! ```ignore +//! # // FIXME: Needs PR #12430 +//! extern crate sync; +//! +//! use sync::Arc; +//! use std::sync::atomics::{AtomicOption, SeqCst}; +//! +//! fn main() { +//! struct BigObject; +//! +//! let shared_big_object = Arc::new(AtomicOption::empty()); +//! +//! let shared_big_object_clone = shared_big_object.clone(); +//! spawn(proc() { +//! let unwrapped_big_object = shared_big_object_clone.take(SeqCst); +//! if unwrapped_big_object.is_some() { +//! println!("got a big object from another task"); +//! } else { +//! println!("other task hasn't sent big object yet"); +//! } +//! }); +//! +//! shared_big_object.swap(~BigObject, SeqCst); +//! } +//! ``` +//! +//! Keep a global count of live tasks: +//! +//! ``` +//! use std::sync::atomics::{AtomicUint, SeqCst, INIT_ATOMIC_UINT}; +//! +//! static mut GLOBAL_TASK_COUNT: AtomicUint = INIT_ATOMIC_UINT; +//! +//! unsafe { +//! let old_task_count = GLOBAL_TASK_COUNT.fetch_add(1, SeqCst); +//! println!("live tasks: {}", old_task_count + 1); +//! } +//! ``` #[allow(missing_doc)]; @@ -27,165 +115,353 @@ use std::kinds::marker; use option::{Option,Some,None}; use ops::Drop; -/** - * An atomic boolean type. - */ +/// An atomic boolean type. pub struct AtomicBool { priv v: uint, priv nopod: marker::NoPod } -/** - * A signed atomic integer type, supporting basic atomic arithmetic operations - */ +/// A signed atomic integer type, supporting basic atomic arithmetic operations pub struct AtomicInt { priv v: int, priv nopod: marker::NoPod } -/** - * An unsigned atomic integer type, supporting basic atomic arithmetic operations - */ +/// An unsigned atomic integer type, supporting basic atomic arithmetic operations pub struct AtomicUint { priv v: uint, priv nopod: marker::NoPod } -/** - * An unsigned atomic integer type that is forced to be 64-bits. This does not - * support all operations. - */ +/// An unsigned atomic integer type that is forced to be 64-bits. This does not +/// support all operations. pub struct AtomicU64 { priv v: u64, priv nopod: marker::NoPod } -/** - * An unsafe atomic pointer. Only supports basic atomic operations - */ +/// An unsafe atomic pointer. Only supports basic atomic operations pub struct AtomicPtr { priv p: uint, priv nopod: marker::NoPod } -/** - * An owned atomic pointer. Ensures that only a single reference to the data is held at any time. - */ +/// An atomic, nullable unique pointer +/// +/// This can be used as the concurrency primitive for operations that transfer +/// owned heap objects across tasks. #[unsafe_no_drop_flag] pub struct AtomicOption { priv p: uint, } +/// Atomic memory orderings +/// +/// Memory orderings limit the ways that both the compiler and CPU may reorder +/// instructions around atomic operations. At its most restrictive, +/// "sequentially consistent" atomics allow neither reads nor writes +/// to be moved either before or after the atomic operation; on the other end +/// "relaxed" atomics allow all reorderings. +/// +/// Rust's memory orderings are the same as in C++[1]. +/// +/// [1]: http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync pub enum Ordering { + /// No ordering constraints, only atomic operations Relaxed, + /// When coupled with a store, all previous writes become visible + /// to another thread that performs a load with `Acquire` ordering + /// on the same value Release, + /// When coupled with a load, all subsequent loads will see data + /// written before a store with `Release` ordering on the same value + /// in another thread Acquire, + /// When coupled with a load, uses `Acquire` ordering, and with a store + /// `Release` ordering AcqRel, + /// Like `AcqRel` with the additional guarantee that all threads see all + /// sequentially consistent operations in the same order. SeqCst } +/// An `AtomicBool` initialized to `false` pub static INIT_ATOMIC_BOOL : AtomicBool = AtomicBool { v: 0, nopod: marker::NoPod }; +/// An `AtomicInt` initialized to `0` pub static INIT_ATOMIC_INT : AtomicInt = AtomicInt { v: 0, nopod: marker::NoPod }; +/// An `AtomicUint` initialized to `0` pub static INIT_ATOMIC_UINT : AtomicUint = AtomicUint { v: 0, nopod: marker::NoPod }; +/// An `AtomicU64` initialized to `0` pub static INIT_ATOMIC_U64 : AtomicU64 = AtomicU64 { v: 0, nopod: marker::NoPod }; + +// NB: Needs to be -1 (0b11111111...) to make fetch_nand work correctly +static UINT_TRUE: uint = -1; + impl AtomicBool { + /// Create a new `AtomicBool` pub fn new(v: bool) -> AtomicBool { - AtomicBool { v: if v { 1 } else { 0 }, nopod: marker::NoPod } + AtomicBool { v: if v { UINT_TRUE } else { 0 }, nopod: marker::NoPod } } + /// Load the value #[inline] pub fn load(&self, order: Ordering) -> bool { unsafe { atomic_load(&self.v, order) > 0 } } + /// Store the value #[inline] pub fn store(&mut self, val: bool, order: Ordering) { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_store(&mut self.v, val, order); } } + /// Store a value, returning the old value #[inline] pub fn swap(&mut self, val: bool, order: Ordering) -> bool { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_swap(&mut self.v, val, order) > 0 } } + /// If the current value is the same as expected, store a new value + /// + /// Compare the current value with `old`; if they are the same then + /// replace the current value with `new`. Return the previous value. + /// If the return value is equal to `old` then the value was updated. + /// + /// # Examples + /// + /// ```ignore + /// # // FIXME: Needs PR #12430 + /// extern crate sync; + /// + /// use sync::Arc; + /// use std::sync::atomics::{AtomicBool, SeqCst}; + /// + /// fn main() { + /// let spinlock = Arc::new(AtomicBool::new(false)); + /// let spinlock_clone = spin_lock.clone(); + /// + /// spawn(proc() { + /// with_lock(&spinlock, || println!("task 1 in lock")); + /// }); + /// + /// spawn(proc() { + /// with_lock(&spinlock_clone, || println!("task 2 in lock")); + /// }); + /// } + /// + /// fn with_lock(spinlock: &Arc, f: || -> ()) { + /// // CAS loop until we are able to replace `false` with `true` + /// while spinlock.compare_and_swap(false, true, SeqCst) == false { + /// // Since tasks may not be preemptive (if they are green threads) + /// // yield to the scheduler to let the other task run. Low level + /// // concurrent code needs to take into account Rust's two threading + /// // models. + /// deschedule(); + /// } + /// + /// // Now we have the spinlock + /// f(); + /// + /// // Release the lock + /// spinlock.store(false); + /// } + /// ``` #[inline] pub fn compare_and_swap(&mut self, old: bool, new: bool, order: Ordering) -> bool { - let old = if old { 1 } else { 0 }; - let new = if new { 1 } else { 0 }; + let old = if old { UINT_TRUE } else { 0 }; + let new = if new { UINT_TRUE } else { 0 }; unsafe { atomic_compare_and_swap(&mut self.v, old, new, order) > 0 } } - /// Returns the old value + /// A logical "and" operation + /// + /// Performs a logical "and" operation on the current value and the + /// argument `val`, and sets the new value to the result. + /// Returns the previous value. + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicBool, SeqCst}; + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_and(false, SeqCst)); + /// assert_eq!(false, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_and(true, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(false); + /// assert_eq!(false, foo.fetch_and(false, SeqCst)); + /// assert_eq!(false, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_and(&mut self, val: bool, order: Ordering) -> bool { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_and(&mut self.v, val, order) > 0 } } - /// Returns the old value + /// A logical "nand" operation + /// + /// Performs a logical "nand" operation on the current value and the + /// argument `val`, and sets the new value to the result. + /// Returns the previous value. + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicBool, SeqCst}; + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_nand(false, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_nand(true, SeqCst)); + /// assert_eq!(0, foo.load(SeqCst) as int); + /// assert_eq!(false, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(false); + /// assert_eq!(false, foo.fetch_nand(false, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_nand(&mut self, val: bool, order: Ordering) -> bool { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_nand(&mut self.v, val, order) > 0 } } - /// Returns the old value + /// A logical "or" operation + /// + /// Performs a logical "or" operation on the current value and the + /// argument `val`, and sets the new value to the result. + /// Returns the previous value. + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicBool, SeqCst}; + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_or(false, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_or(true, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(false); + /// assert_eq!(false, foo.fetch_or(false, SeqCst)); + /// assert_eq!(false, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_or(&mut self, val: bool, order: Ordering) -> bool { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_or(&mut self.v, val, order) > 0 } } - /// Returns the old value + /// A logical "xor" operation + /// + /// Performs a logical "xor" operation on the current value and the + /// argument `val`, and sets the new value to the result. + /// Returns the previous value. + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicBool, SeqCst}; + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_xor(false, SeqCst)); + /// assert_eq!(true, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(true); + /// assert_eq!(true, foo.fetch_xor(true, SeqCst)); + /// assert_eq!(false, foo.load(SeqCst)); + /// + /// let mut foo = AtomicBool::new(false); + /// assert_eq!(false, foo.fetch_xor(false, SeqCst)); + /// assert_eq!(false, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_xor(&mut self, val: bool, order: Ordering) -> bool { - let val = if val { 1 } else { 0 }; + let val = if val { UINT_TRUE } else { 0 }; unsafe { atomic_xor(&mut self.v, val, order) > 0 } } } impl AtomicInt { + /// Create a new `AtomicInt` pub fn new(v: int) -> AtomicInt { AtomicInt { v:v, nopod: marker::NoPod} } + /// Load the value #[inline] pub fn load(&self, order: Ordering) -> int { unsafe { atomic_load(&self.v, order) } } + /// Store the value #[inline] pub fn store(&mut self, val: int, order: Ordering) { unsafe { atomic_store(&mut self.v, val, order); } } + /// Store a value, returning the old value #[inline] pub fn swap(&mut self, val: int, order: Ordering) -> int { unsafe { atomic_swap(&mut self.v, val, order) } } + /// If the current value is the same as expected, store a new value + /// + /// Compare the current value with `old`; if they are the same then + /// replace the current value with `new`. Return the previous value. + /// If the return value is equal to `old` then the value was updated. #[inline] pub fn compare_and_swap(&mut self, old: int, new: int, order: Ordering) -> int { unsafe { atomic_compare_and_swap(&mut self.v, old, new, order) } } - /// Returns the old value (like __sync_fetch_and_add). + /// Add to the current value, returning the previous + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicInt, SeqCst}; + /// + /// let mut foo = AtomicInt::new(0); + /// assert_eq!(0, foo.fetch_add(10, SeqCst)); + /// assert_eq!(10, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_add(&mut self, val: int, order: Ordering) -> int { unsafe { atomic_add(&mut self.v, val, order) } } - /// Returns the old value (like __sync_fetch_and_sub). + /// Subtract from the current value, returning the previous + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicInt, SeqCst}; + /// + /// let mut foo = AtomicInt::new(0); + /// assert_eq!(0, foo.fetch_sub(10, SeqCst)); + /// assert_eq!(-10, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_sub(&mut self, val: int, order: Ordering) -> int { unsafe { atomic_sub(&mut self.v, val, order) } @@ -233,37 +509,66 @@ impl AtomicU64 { } impl AtomicUint { + /// Create a new `AtomicUint` pub fn new(v: uint) -> AtomicUint { AtomicUint { v:v, nopod: marker::NoPod } } + /// Load the value #[inline] pub fn load(&self, order: Ordering) -> uint { unsafe { atomic_load(&self.v, order) } } + /// Store the value #[inline] pub fn store(&mut self, val: uint, order: Ordering) { unsafe { atomic_store(&mut self.v, val, order); } } + /// Store a value, returning the old value #[inline] pub fn swap(&mut self, val: uint, order: Ordering) -> uint { unsafe { atomic_swap(&mut self.v, val, order) } } + /// If the current value is the same as expected, store a new value + /// + /// Compare the current value with `old`; if they are the same then + /// replace the current value with `new`. Return the previous value. + /// If the return value is equal to `old` then the value was updated. #[inline] pub fn compare_and_swap(&mut self, old: uint, new: uint, order: Ordering) -> uint { unsafe { atomic_compare_and_swap(&mut self.v, old, new, order) } } - /// Returns the old value (like __sync_fetch_and_add). + /// Add to the current value, returning the previous + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicUint, SeqCst}; + /// + /// let mut foo = AtomicUint::new(0); + /// assert_eq!(0, foo.fetch_add(10, SeqCst)); + /// assert_eq!(10, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_add(&mut self, val: uint, order: Ordering) -> uint { unsafe { atomic_add(&mut self.v, val, order) } } - /// Returns the old value (like __sync_fetch_and_sub).. + /// Subtract from the current value, returning the previous + /// + /// # Examples + /// + /// ``` + /// use std::sync::atomics::{AtomicUint, SeqCst}; + /// + /// let mut foo = AtomicUint::new(10); + /// assert_eq!(10, foo.fetch_sub(10, SeqCst)); + /// assert_eq!(0, foo.load(SeqCst)); + /// ``` #[inline] pub fn fetch_sub(&mut self, val: uint, order: Ordering) -> uint { unsafe { atomic_sub(&mut self.v, val, order) } @@ -271,10 +576,12 @@ impl AtomicUint { } impl AtomicPtr { + /// Create a new `AtomicPtr` pub fn new(p: *mut T) -> AtomicPtr { AtomicPtr { p: p as uint, nopod: marker::NoPod } } + /// Load the value #[inline] pub fn load(&self, order: Ordering) -> *mut T { unsafe { @@ -282,16 +589,23 @@ impl AtomicPtr { } } + /// Store the value #[inline] pub fn store(&mut self, ptr: *mut T, order: Ordering) { unsafe { atomic_store(&mut self.p, ptr as uint, order); } } + /// Store a value, returning the old value #[inline] pub fn swap(&mut self, ptr: *mut T, order: Ordering) -> *mut T { unsafe { atomic_swap(&mut self.p, ptr as uint, order) as *mut T } } + /// If the current value is the same as expected, store a new value + /// + /// Compare the current value with `old`; if they are the same then + /// replace the current value with `new`. Return the previous value. + /// If the return value is equal to `old` then the value was updated. #[inline] pub fn compare_and_swap(&mut self, old: *mut T, new: *mut T, order: Ordering) -> *mut T { unsafe { @@ -302,12 +616,15 @@ impl AtomicPtr { } impl AtomicOption { + /// Create a new `AtomicOption` pub fn new(p: ~T) -> AtomicOption { unsafe { AtomicOption { p: cast::transmute(p) } } } + /// Create a new `AtomicOption` that doesn't contain a value pub fn empty() -> AtomicOption { AtomicOption { p: 0 } } + /// Store a value, returning the old value #[inline] pub fn swap(&mut self, val: ~T, order: Ordering) -> Option<~T> { unsafe { @@ -322,13 +639,16 @@ impl AtomicOption { } } + /// Remove the value, leaving the `AtomicOption` empty. #[inline] pub fn take(&mut self, order: Ordering) -> Option<~T> { unsafe { self.swap(cast::transmute(0), order) } } - /// A compare-and-swap. Succeeds if the option is 'None' and returns 'None' - /// if so. If the option was already 'Some', returns 'Some' of the rejected + /// Replace an empty value with a non-empty value. + /// + /// Succeeds if the option is `None` and returns `None` if so. If + /// the option was already `Some`, returns `Some` of the rejected /// value. #[inline] pub fn fill(&mut self, val: ~T, order: Ordering) -> Option<~T> { @@ -344,6 +664,8 @@ impl AtomicOption { } } + /// Returns `true` if the `AtomicOption` is empty. + /// /// Be careful: The caller must have some external method of ensuring the /// result does not get invalidated by another task after this returns. #[inline] @@ -470,32 +792,35 @@ pub unsafe fn atomic_xor(dst: &mut T, val: T, order: Ordering) -> T { } -/** - * An atomic fence. - * - * A fence 'A' which has `Release` ordering semantics, synchronizes with a - * fence 'B' with (at least) `Acquire` semantics, if and only if there exists - * atomic operations X and Y, both operating on some atomic object 'M' such - * that A is sequenced before X, Y is synchronized before B and Y observers - * the change to M. This provides a happens-before dependence between A and B. - * - * Atomic operations with `Release` or `Acquire` semantics can also synchronize - * with a fence. - * - * A fence with has `SeqCst` ordering, in addition to having both `Acquire` and - * `Release` semantics, participates in the global program order of the other - * `SeqCst` operations and/or fences. - * - * Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings. - */ +/// An atomic fence. +/// +/// A fence 'A' which has `Release` ordering semantics, synchronizes with a +/// fence 'B' with (at least) `Acquire` semantics, if and only if there exists +/// atomic operations X and Y, both operating on some atomic object 'M' such +/// that A is sequenced before X, Y is synchronized before B and Y observers +/// the change to M. This provides a happens-before dependence between A and B. +/// +/// Atomic operations with `Release` or `Acquire` semantics can also synchronize +/// with a fence. +/// +/// A fence with has `SeqCst` ordering, in addition to having both `Acquire` and +/// `Release` semantics, participates in the global program order of the other +/// `SeqCst` operations and/or fences. +/// +/// Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings. +/// +/// # Failure +/// +/// Fails if `order` is `Relaxed` #[inline] pub fn fence(order: Ordering) { unsafe { match order { Acquire => intrinsics::atomic_fence_acq(), Release => intrinsics::atomic_fence_rel(), - AcqRel => intrinsics::atomic_fence_rel(), - _ => intrinsics::atomic_fence(), + AcqRel => intrinsics::atomic_fence_acqrel(), + SeqCst => intrinsics::atomic_fence(), + Relaxed => fail!("there is no such thing as a relaxed fence") } } }