std: Introduce std::sync

For now, this moves the following modules to std::sync

* UnsafeArc (also removed unwrap method)
* mpsc_queue
* spsc_queue
* atomics
* mpmc_bounded_queue
* deque

We may want to remove some of the queues, but for now this moves things out of
std::rt into std::sync

Author: alexcrichton

src/libextra/arc.rs

@@ -45,7 +45,7 @@ use sync;
 use sync::{Mutex, RWLock};
 
 use std::cast;
-use std::unstable::sync::UnsafeArc;
+use std::sync::arc::UnsafeArc;
 use std::task;
 use std::borrow;
 
@@ -127,20 +127,6 @@ impl<T:Freeze+Send> Arc<T> {
     pub fn get<'a>(&'a self) -> &'a T {
         unsafe { &*self.x.get_immut() }
     }
-
-    /**
-     * Retrieve the data back out of the Arc. This function blocks until the
-     * reference given to it is the last existing one, and then unwrap the data
-     * instead of destroying it.
-     *
-     * If multiple tasks call unwrap, all but the first will fail. Do not call
-     * unwrap from a task that holds another reference to the same Arc; it is
-     * guaranteed to deadlock.
-     */
-    pub fn unwrap(self) -> T {
-        let Arc { x: x } = self;
-        x.unwrap()
-    }
 }
 
 impl<T:Freeze + Send> Clone for Arc<T> {
@@ -247,22 +233,6 @@ impl<T:Send> MutexArc<T> {
                           cond: cond })
         })
     }
-
-    /**
-     * Retrieves the data, blocking until all other references are dropped,
-     * exactly as arc::unwrap.
-     *
-     * Will additionally fail if another task has failed while accessing the arc.
-     */
-    pub fn unwrap(self) -> T {
-        let MutexArc { x: x } = self;
-        let inner = x.unwrap();
-        let MutexArcInner { failed: failed, data: data, .. } = inner;
-        if failed {
-            fail!("Can't unwrap poisoned MutexArc - another task failed inside!");
-        }
-        data
-    }
 }
 
 impl<T:Freeze + Send> MutexArc<T> {
@@ -503,23 +473,6 @@ impl<T:Freeze + Send> RWArc<T> {
             }
         }
     }
-
-    /**
-     * Retrieves the data, blocking until all other references are dropped,
-     * exactly as arc::unwrap.
-     *
-     * Will additionally fail if another task has failed while accessing the arc
-     * in write mode.
-     */
-    pub fn unwrap(self) -> T {
-        let RWArc { x: x, .. } = self;
-        let inner = x.unwrap();
-        let RWArcInner { failed: failed, data: data, .. } = inner;
-        if failed {
-            fail!("Can't unwrap poisoned RWArc - another task failed inside!")
-        }
-        data
-    }
 }
 
 // Borrowck rightly complains about immutably aliasing the rwlock in order to
@@ -689,22 +642,6 @@ mod tests {
         })
     }
 
-    #[test] #[should_fail]
-    pub fn test_mutex_arc_unwrap_poison() {
-        let arc = MutexArc::new(1);
-        let arc2 = ~(&arc).clone();
-        let (p, c) = Chan::new();
-        do task::spawn {
-            arc2.access(|one| {
-                c.send(());
-                assert!(*one == 2);
-            })
-        }
-        let _ = p.recv();
-        let one = arc.unwrap();
-        assert!(one == 1);
-    }
-
     #[test]
     fn test_unsafe_mutex_arc_nested() {
         unsafe {

src/libextra/sync.rs

@@ -19,8 +19,9 @@
 
 
 use std::borrow;
-use std::unstable::sync::{Exclusive, UnsafeArc};
-use std::unstable::atomics;
+use std::unstable::sync::Exclusive;
+use std::sync::arc::UnsafeArc;
+use std::sync::atomics;
 use std::unstable::finally::Finally;
 use std::util;
 use std::util::NonCopyable;

src/librustc/middle/trans/debuginfo.rs

@@ -146,7 +146,7 @@ use std::hashmap::HashMap;
 use std::hashmap::HashSet;
 use std::libc::{c_uint, c_ulonglong, c_longlong};
 use std::ptr;
-use std::unstable::atomics;
+use std::sync::atomics;
 use std::vec;
 use syntax::codemap::{Span, Pos};
 use syntax::{ast, codemap, ast_util, ast_map, opt_vec};

src/libstd/lib.rs

@@ -159,6 +159,7 @@ pub mod trie;
 pub mod task;
 pub mod comm;
 pub mod local_data;
+pub mod sync;
 
 
 /* Runtime and platform support */

src/libstd/sync/arc.rs

@@ -0,0 +1,153 @@
+// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Atomically reference counted data
+//!
+//! This modules contains the implementation of an atomically reference counted
+//! pointer for the purpose of sharing data between tasks. This is obviously a
+//! very unsafe primitive to use, but it has its use cases when implementing
+//! concurrent data structures and similar tasks.
+//!
+//! Great care must be taken to ensure that data races do not arise through the
+//! usage of `UnsafeArc`, and this often requires some form of external
+//! synchronization. The only guarantee provided to you by this class is that
+//! the underlying data will remain valid (not free'd) so long as the reference
+//! count is greater than one.
+
+use cast;
+use clone::Clone;
+use kinds::Send;
+use ops::Drop;
+use ptr::RawPtr;
+use sync::atomics::{AtomicUint, SeqCst, Relaxed, Acquire};
+use vec;
+
+/// An atomically reference counted pointer.
+///
+/// Enforces no shared-memory safety.
+#[unsafe_no_drop_flag]
+pub struct UnsafeArc<T> {
+    priv data: *mut ArcData<T>,
+}
+
+struct ArcData<T> {
+    count: AtomicUint,
+    data: T,
+}
+
+unsafe fn new_inner<T: Send>(data: T, refcount: uint) -> *mut ArcData<T> {
+    let data = ~ArcData { count: AtomicUint::new(refcount), data: data };
+    cast::transmute(data)
+}
+
+impl<T: Send> UnsafeArc<T> {
+    /// Creates a new `UnsafeArc` which wraps the given data.
+    pub fn new(data: T) -> UnsafeArc<T> {
+        unsafe { UnsafeArc { data: new_inner(data, 1) } }
+    }
+
+    /// As new(), but returns an extra pre-cloned handle.
+    pub fn new2(data: T) -> (UnsafeArc<T>, UnsafeArc<T>) {
+        unsafe {
+            let ptr = new_inner(data, 2);
+            (UnsafeArc { data: ptr }, UnsafeArc { data: ptr })
+        }
+    }
+
+    /// As new(), but returns a vector of as many pre-cloned handles as
+    /// requested.
+    pub fn newN(data: T, num_handles: uint) -> ~[UnsafeArc<T>] {
+        unsafe {
+            if num_handles == 0 {
+                ~[] // need to free data here
+            } else {
+                let ptr = new_inner(data, num_handles);
+                vec::from_fn(num_handles, |_| UnsafeArc { data: ptr })
+            }
+        }
+    }
+
+    /// Gets a pointer to the inner shared data. Note that care must be taken to
+    /// ensure that the outer `UnsafeArc` does not fall out of scope while this
+    /// pointer is in use, otherwise it could possibly contain a use-after-free.
+    #[inline]
+    pub fn get(&self) -> *mut T {
+        unsafe {
+            assert!((*self.data).count.load(Relaxed) > 0);
+            return &mut (*self.data).data as *mut T;
+        }
+    }
+
+    /// Gets an immutable pointer to the inner shared data. This has the same
+    /// caveats as the `get` method.
+    #[inline]
+    pub fn get_immut(&self) -> *T {
+        unsafe {
+            assert!((*self.data).count.load(Relaxed) > 0);
+            return &(*self.data).data as *T;
+        }
+    }
+}
+
+impl<T: Send> Clone for UnsafeArc<T> {
+    fn clone(&self) -> UnsafeArc<T> {
+        unsafe {
+            // This barrier might be unnecessary, but I'm not sure...
+            let old_count = (*self.data).count.fetch_add(1, Acquire);
+            assert!(old_count >= 1);
+            return UnsafeArc { data: self.data };
+        }
+    }
+}
+
+#[unsafe_destructor]
+impl<T> Drop for UnsafeArc<T>{
+    fn drop(&mut self) {
+        unsafe {
+            // Happens when destructing an unwrapper's handle and from
+            // `#[unsafe_no_drop_flag]`
+            if self.data.is_null() {
+                return
+            }
+            // Must be acquire+release, not just release, to make sure this
+            // doesn't get reordered to after the unwrapper pointer load.
+            let old_count = (*self.data).count.fetch_sub(1, SeqCst);
+            assert!(old_count >= 1);
+            if old_count == 1 {
+                let _: ~ArcData<T> = cast::transmute(self.data);
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use prelude::*;
+    use super::UnsafeArc;
+    use task;
+    use mem::size_of;
+
+    #[test]
+    fn test_size() {
+        assert_eq!(size_of::<UnsafeArc<[int, ..10]>>(), size_of::<*[int, ..10]>());
+    }
+
+    #[test]
+    fn arclike_newN() {
+        // Tests that the many-refcounts-at-once constructors don't leak.
+        let _ = UnsafeArc::new2(~~"hello");
+        let x = UnsafeArc::newN(~~"hello", 0);
+        assert_eq!(x.len(), 0)
+        let x = UnsafeArc::newN(~~"hello", 1);
+        assert_eq!(x.len(), 1)
+        let x = UnsafeArc::newN(~~"hello", 10);
+        assert_eq!(x.len(), 10)
+    }
+}

src/libstd/unstable/atomics.rs renamed to src/libstd/sync/atomics.rs

@@ -11,13 +11,16 @@
 /*!
  * 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]
+ * 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.
  */
 
+#[allow(missing_doc)];
+
 use unstable::intrinsics;
 use cast;
 use option::{Option,Some,None};

src/libstd/rt/deque.rs renamed to src/libstd/sync/deque.rs

@@ -50,15 +50,18 @@
 
 use cast;
 use clone::Clone;
-use iter::range;
+use iter::{range, Iterator};
 use kinds::Send;
 use libc;
 use mem;
 use ops::Drop;
 use option::{Option, Some, None};
 use ptr;
-use unstable::atomics::{AtomicInt, AtomicPtr, SeqCst};
-use unstable::sync::{UnsafeArc, Exclusive};
+use ptr::RawPtr;
+use sync::arc::UnsafeArc;
+use sync::atomics::{AtomicInt, AtomicPtr, SeqCst};
+use unstable::sync::Exclusive;
+use vec::{OwnedVector, ImmutableVector};
 
 // Once the queue is less than 1/K full, then it will be downsized. Note that
 // the deque requires that this number be less than 2.
@@ -399,8 +402,8 @@ mod tests {
     use rt::thread::Thread;
     use rand;
     use rand::Rng;
-    use unstable::atomics::{AtomicBool, INIT_ATOMIC_BOOL, SeqCst,
-                            AtomicUint, INIT_ATOMIC_UINT};
+    use sync::atomics::{AtomicBool, INIT_ATOMIC_BOOL, SeqCst,
+                        AtomicUint, INIT_ATOMIC_UINT};
     use vec;
 
     #[test]

src/libstd/sync/mod.rs

@@ -0,0 +1,23 @@
+// Copyright 2013 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Useful synchronization primitives
+//!
+//! This modules contains useful safe and unsafe synchronization primitives.
+//! Most of the primitives in this module do not provide any sort of locking
+//! and/or blocking at all, but rather provide the necessary tools to build
+//! other types of concurrent primitives.
+
+pub mod arc;
+pub mod atomics;
+pub mod deque;
+pub mod mpmc_bounded_queue;
+pub mod mpsc_queue;
+pub mod spsc_queue;

src/libstd/rt/mpmc_bounded_queue.rs renamed to src/libstd/sync/mpmc_bounded_queue.rs

@@ -25,15 +25,17 @@
  * policies, either expressed or implied, of Dmitry Vyukov.
  */
 
+#[allow(missing_doc, dead_code)];
+
 // http://www.1024cores.net/home/lock-free-algorithms/queues/bounded-mpmc-queue
 
-use unstable::sync::UnsafeArc;
-use unstable::atomics::{AtomicUint,Relaxed,Release,Acquire};
-use option::*;
-use vec;
 use clone::Clone;
 use kinds::Send;
 use num::{Exponential,Algebraic,Round};
+use option::{Option, Some, None};
+use sync::arc::UnsafeArc;
+use sync::atomics::{AtomicUint,Relaxed,Release,Acquire};
+use vec;
 
 struct Node<T> {
     sequence: AtomicUint,