auto merge of #14169 : alexcrichton/rust/atomics, r=sanxiyn

This module is a foundation on which many other algorithms are built. When hardware support is missing, stubs are provided in libcompiler-rt.a, so this should be available on all platforms.

src/libcore/failure.rs

@@ -10,7 +10,7 @@
 
 //! Failure support for libcore
 
-#![allow(dead_code)]
+#![allow(dead_code, missing_doc)]
 
 #[cfg(not(test))]
 use str::raw::c_str_to_static_slice;

src/libcore/lib.rs

@@ -9,6 +9,27 @@
 // except according to those terms.
 
 //! The Rust core library
+//!
+//! This library is meant to represent the core functionality of rust that is
+//! maximally portable to other platforms. To that exent, this library has no
+//! knowledge of things like allocation, threads, I/O, etc. This library is
+//! built on the assumption of a few existing symbols:
+//!
+//! * `memcpy`, `memcmp`, `memset` - These are core memory routines which are
+//!   often generated by LLVM. Additionally, this library can make explicit
+//!   calls to these funcitons. Their signatures are the same as found in C.
+//!
+//! * `rust_begin_unwind` - This function takes three arguments, a
+//!   `&fmt::Arguments`, a `&str`, and a `uint. These three arguments dictate
+//!   the failure message, the file at which failure was invoked, and the line.
+//!   It is up to consumers of this core library to define this failure
+//!   function; it is only required to never return.
+//!
+//! Currently, it is *not* recommended to use the core library. The stable
+//! functionality of libcore is exported directly into the
+//! [standard library](../std/index.html). The composition of this library is
+//! subject to change over time, only the interface exposed through libstd is
+//! intended to be stable.
 
 #![crate_id = "core#0.11.0-pre"]
 #![license = "MIT/ASL2"]
@@ -81,9 +102,11 @@
 mod unicode;
 mod unit;
 pub mod any;
+pub mod atomics;
 pub mod bool;
 pub mod cell;
 pub mod char;
+pub mod failure;
 pub mod finally;
 pub mod iter;
 pub mod option;
@@ -96,13 +119,15 @@
 #[cfg(stage0, not(test))]
 pub mod owned;
 
-mod failure;
-
 // FIXME: this module should not exist. Once owned allocations are no longer a
 //        language type, this module can move outside to the owned allocation
 //        crate.
 mod should_not_exist;
 
+mod core {
+    pub use failure;
+}
+
 mod std {
     pub use clone;
     pub use cmp;

src/libcore/macros.rs

@@ -17,7 +17,7 @@
         fail!("explicit failure")
     );
     ($msg:expr) => (
-        ::failure::begin_unwind($msg, file!(), line!())
+        ::core::failure::begin_unwind($msg, file!(), line!())
     );
 )
 

src/libcore/should_not_exist.rs

@@ -8,6 +8,22 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// As noted by this file name, this file should not exist. This file should not
+// exist because it performs allocations which libcore is not allowed to do. The
+// reason for this file's existence is that the `~[T]` and `~str` types are
+// language-defined types. Traits are defined in libcore, such as `Clone`, which
+// these types need to implement, but the implementation can only be found in
+// libcore.
+//
+// Plan of attack for solving this problem:
+//
+//      1. Implement DST
+//      2. Make `Box<T>` not a language feature
+//      3. Move `Box<T>` to a separate crate, liballoc.
+//      4. Implement relevant trais in liballoc, not libcore
+//
+// Currently, no progress has been made on this list.
+
 use char::Char;
 use clone::Clone;
 use container::Container;