Stabilization for `owned` (now `boxed`) and `cell`

This PR is the outcome of the library stabilization meeting for the
`liballoc::owned` and `libcore::cell` modules.

Aside from the stability attributes, there are a few breaking changes:

* The `owned` modules is now named `boxed`, to better represent its
  contents. (`box` was unavailable, since it's a keyword.) This will
  help avoid the misconception that `Box` plays a special role wrt
  ownership.

* The `AnyOwnExt` extension trait is renamed to `BoxAny`, and its `move`
  method is renamed to `downcast`, in both cases to improve clarity.

* The recently-added `AnySendOwnExt` extension trait is removed; it was
  not being used and is unnecessary.

[breaking-change]

2 files changed, 29 insertions, 44 deletions

diff --git a/src/liballoc/owned.rs b/src/liballoc/boxed.rs
index addec396bbe..56506d798d9 100644
--- a/src/liballoc/owned.rs
+++ b/src/liballoc/boxed.rs
@@ -16,7 +16,6 @@ use core::cmp::{PartialEq, PartialOrd, Eq, Ord, Ordering};
 use core::default::Default;
 use core::fmt;
 use core::intrinsics;
-use core::kinds::Send;
 use core::mem;
 use core::option::Option;
 use core::raw::TraitObject;
@@ -27,17 +26,19 @@ use core::result::{Ok, Err, Result};
 ///
 /// The following two examples are equivalent:
 ///
-///     use std::owned::HEAP;
+///     use std::boxed::HEAP;
 ///
 ///     # struct Bar;
 ///     # impl Bar { fn new(_a: int) { } }
 ///     let foo = box(HEAP) Bar::new(2);
 ///     let foo = box Bar::new(2);
-#[lang="exchange_heap"]
+#[lang = "exchange_heap"]
+#[experimental = "may be renamed; uncertain about custom allocator design"]
 pub static HEAP: () = ();
 
 /// A type that represents a uniquely-owned value.
-#[lang="owned_box"]
+#[lang = "owned_box"]
+#[unstable = "custom allocators will add an additional type parameter (with default)"]
 pub struct Box<T>(*mut T);
 
 impl<T: Default> Default for Box<T> {
@@ -57,7 +58,6 @@ impl<T: Clone> Clone for Box<T> {
     }
 }
 
-// box pointers
 impl<T:PartialEq> PartialEq for Box<T> {
     #[inline]
     fn eq(&self, other: &Box<T>) -> bool { *(*self) == *(*other) }
@@ -85,48 +85,27 @@ impl<T: Ord> Ord for Box<T> {
 impl<T: Eq> Eq for Box<T> {}
 
 /// Extension methods for an owning `Any` trait object
-pub trait AnyOwnExt {
+#[unstable = "post-DST, the signature of `downcast` will change to take `Box<Self>`"]
+pub trait BoxAny {
     /// Returns the boxed value if it is of type `T`, or
     /// `Err(Self)` if it isn't.
-    fn move<T: 'static>(self) -> Result<Box<T>, Self>;
-}
-
-impl AnyOwnExt for Box<Any> {
-    #[inline]
-    fn move<T: 'static>(self) -> Result<Box<T>, Box<Any>> {
-        if self.is::<T>() {
-            unsafe {
-                // Get the raw representation of the trait object
-                let to: TraitObject =
-                    *mem::transmute::<&Box<Any>, &TraitObject>(&self);
-
-                // Prevent destructor on self being run
-                intrinsics::forget(self);
+    fn downcast<T: 'static>(self) -> Result<Box<T>, Self>;
 
-                // Extract the data pointer
-                Ok(mem::transmute(to.data))
-            }
-        } else {
-            Err(self)
-        }
+    /// Deprecated; this method has been renamed to `downcast`.
+    #[deprecated = "use downcast instead"]
+    fn move<T: 'static>(self) -> Result<Box<T>, Self> {
+        self.downcast::<T>()
     }
 }
 
-/// Extension methods for an owning `Any+Send` trait object
-pub trait AnySendOwnExt {
-    /// Returns the boxed value if it is of type `T`, or
-    /// `Err(Self)` if it isn't.
-    fn move_send<T: 'static>(self) -> Result<Box<T>, Self>;
-}
-
-impl AnySendOwnExt for Box<Any+Send> {
+impl BoxAny for Box<Any> {
     #[inline]
-    fn move_send<T: 'static>(self) -> Result<Box<T>, Box<Any+Send>> {
+    fn downcast<T: 'static>(self) -> Result<Box<T>, Box<Any>> {
         if self.is::<T>() {
             unsafe {
                 // Get the raw representation of the trait object
                 let to: TraitObject =
-                    *mem::transmute::<&Box<Any+Send>, &TraitObject>(&self);
+                    *mem::transmute::<&Box<Any>, &TraitObject>(&self);
 
                 // Prevent destructor on self being run
                 intrinsics::forget(self);
@@ -166,11 +145,11 @@ mod test {
         let a = box 8u as Box<Any>;
         let b = box Test as Box<Any>;
 
-        match a.move::<uint>() {
+        match a.downcast::<uint>() {
             Ok(a) => { assert!(a == box 8u); }
             Err(..) => fail!()
         }
-        match b.move::<Test>() {
+        match b.downcast::<Test>() {
             Ok(a) => { assert!(a == box Test); }
             Err(..) => fail!()
         }
@@ -178,8 +157,8 @@ mod test {
         let a = box 8u as Box<Any>;
         let b = box Test as Box<Any>;
 
-        assert!(a.move::<Box<Test>>().is_err());
-        assert!(b.move::<Box<uint>>().is_err());
+        assert!(a.downcast::<Box<Test>>().is_err());
+        assert!(b.downcast::<Box<uint>>().is_err());
     }
 
     #[test]
diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs
index 80b6cee2a9d..6ae91f38971 100644
--- a/src/liballoc/lib.rs
+++ b/src/liballoc/lib.rs
@@ -21,11 +21,11 @@
 //!
 //! Currently, there are four major definitions in this library.
 //!
-//! ## Owned pointers
+//! ## Boxed values
 //!
-//! The [`Box`](owned/index.html) type is the core owned pointer type in rust.
+//! The [`Box`](boxed/index.html) type is the core owned pointer type in rust.
 //! There can only be one owner of a `Box`, and the owner can decide to mutate
-//! the contents.
+//! the contents, which live on the heap.
 //!
 //! This type can be sent among tasks efficiently as the size of a `Box` value
 //! is just a pointer. Tree-like data structures are often built on owned
@@ -82,6 +82,12 @@ extern crate libc;
 #[cfg(test)] #[phase(plugin, link)] extern crate std;
 #[cfg(test)] #[phase(plugin, link)] extern crate log;
 
+// The deprecated name of the boxed module
+
+#[deprecated = "use boxed instead"]
+#[cfg(not(test))]
+pub use owned = boxed;
+
 // Heaps provided for low-level allocation strategies
 
 pub mod heap;
@@ -91,7 +97,7 @@ pub mod util;
 // Primitive types using the heaps above
 
 #[cfg(not(test))]
-pub mod owned;
+pub mod boxed;
 pub mod arc;
 pub mod rc;