OpenE2K/rust
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

auto merge of #12954 : brson/rust/atomicdocs, r=alexcrichton

Browse Source 
This adds lots of docs to the atomics module. Two of the examples
are using the future atomics API (relying on `Share`) 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.
This commit is contained in:
bors 2014-03-18 21:16:46 -07:00
commit a39c294155
1 changed files with 393 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

461
src/libstd/sync/atomics.rs
View File

@ -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<T> {
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<T> {
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<AtomicBool>, 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<T> AtomicPtr<T> {
/// Create a new `AtomicPtr`
pub fn new(p: *mut T) -> AtomicPtr<T> {
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<T> AtomicPtr<T> {
}
}
/// 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<T> AtomicPtr<T> {
}
impl<T> AtomicOption<T> {
/// Create a new `AtomicOption`
pub fn new(p: ~T) -> AtomicOption<T> {
unsafe { AtomicOption { p: cast::transmute(p) } }
}
/// Create a new `AtomicOption` that doesn't contain a value
pub fn empty() -> AtomicOption<T> { 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<T> AtomicOption<T> {
}
}
/// 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<T> AtomicOption<T> {
}
}
/// 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<T>(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")
}
}
}