auto merge of #17853 : alexcrichton/rust/issue-17718, r=pcwalton

This change is an implementation of [RFC 69][rfc] which adds a third kind of
global to the language, `const`. This global is most similar to what the old
`static` was, and if you're unsure about what to use then you should use a
`const`.

The semantics of these three kinds of globals are:

* A `const` does not represent a memory location, but only a value. Constants
  are translated as rvalues, which means that their values are directly inlined
  at usage location (similar to a #define in C/C++). Constant values are, well,
  constant, and can not be modified. Any "modification" is actually a
  modification to a local value on the stack rather than the actual constant
  itself.

  Almost all values are allowed inside constants, whether they have interior
  mutability or not. There are a few minor restrictions listed in the RFC, but
  they should in general not come up too often.

* A `static` now always represents a memory location (unconditionally). Any
  references to the same `static` are actually a reference to the same memory
  location. Only values whose types ascribe to `Sync` are allowed in a `static`.
  This restriction is in place because many threads may access a `static`
  concurrently. Lifting this restriction (and allowing unsafe access) is a
  future extension not implemented at this time.

* A `static mut` continues to always represent a memory location. All references
  to a `static mut` continue to be `unsafe`.

This is a large breaking change, and many programs will need to be updated
accordingly. A summary of the breaking changes is:

* Statics may no longer be used in patterns. Statics now always represent a
  memory location, which can sometimes be modified. To fix code, repurpose the
  matched-on-`static` to a `const`.

      static FOO: uint = 4;
      match n {
          FOO => { /* ... */ }
          _ => { /* ... */ }
      }

  change this code to:

      const FOO: uint = 4;
      match n {
          FOO => { /* ... */ }
          _ => { /* ... */ }
      }

* Statics may no longer refer to other statics by value. Due to statics being
  able to change at runtime, allowing them to reference one another could
  possibly lead to confusing semantics. If you are in this situation, use a
  constant initializer instead. Note, however, that statics may reference other
  statics by address, however.

* Statics may no longer be used in constant expressions, such as array lengths.
  This is due to the same restrictions as listed above. Use a `const` instead.

[breaking-change]
Closes #17718 

[rfc]: rust-lang/rfcs#246

src/doc/reference.md

@@ -1383,44 +1383,87 @@ a = Cat { name: "Spotty".to_string(), weight: 2.7 };
 In this example, `Cat` is a _struct-like enum variant_,
 whereas `Dog` is simply called an enum variant.
 
-### Static items
+### Constant items
 
 ```{.ebnf .gram}
-static_item : "static" ident ':' type '=' expr ';' ;
+const_item : "const" ident ':' type '=' expr ';' ;
 ```
 
-A *static item* is a named _constant value_ stored in the global data section
-of a crate. Immutable static items are stored in the read-only data section.
-The constant value bound to a static item is, like all constant values,
-evaluated at compile time. Static items have the `static` lifetime, which
-outlives all other lifetimes in a Rust program. Only values stored in the
-global data section (such as string constants and static items) can have the
-`static` lifetime; dynamically constructed values cannot safely be assigned the
-`static` lifetime. Static items are declared with the `static` keyword. A
-static item must have a _constant expression_ giving its definition.
+A *constant item* is a named _constant value_ which is not associated with a
+specific memory location in the program. Constants are essentially inlined
+wherever they are used, meaning that they are copied directly into the relevant
+context when used. References to the same constant are not necessarily
+guaranteed to refer to the same memory address.
+
+Constant values must not have destructors, and otherwise permit most forms of
+data. Constants may refer to the address of other constants, in which case the
+address will have the `static` lifetime. The compiler is, however, still at
+liberty to translate the constant many times, so the address referred to may not
+be stable.
 
-Static items must be explicitly typed. The type may be `bool`, `char`,
-a number, or a type derived from those primitive types. The derived types are
-references with the `static` lifetime, fixed-size arrays, tuples, and structs.
+Constants must be explicitly typed. The type may be `bool`, `char`, a number, or
+a type derived from those primitive types. The derived types are references with
+the `static` lifetime, fixed-size arrays, tuples, enum variants, and structs.
 
 ```
-static BIT1: uint = 1 << 0;
-static BIT2: uint = 1 << 1;
+const BIT1: uint = 1 << 0;
+const BIT2: uint = 1 << 1;
 
-static BITS: [uint, ..2] = [BIT1, BIT2];
-static STRING: &'static str = "bitstring";
+const BITS: [uint, ..2] = [BIT1, BIT2];
+const STRING: &'static str = "bitstring";
 
 struct BitsNStrings<'a> {
     mybits: [uint, ..2],
     mystring: &'a str
 }
 
-static BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
+const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
     mybits: BITS,
     mystring: STRING
 };
 ```
 
+### Static items
+
+```{.ebnf .gram}
+static_item : "static" ident ':' type '=' expr ';' ;
+```
+
+A *static item* is similar to a *constant*, except that it represents a precise
+memory location in the program. A static is never "inlined" at the usage site,
+and all references to it refer to the same memory location. Static items have
+the `static` lifetime, which outlives all other lifetimes in a Rust program.
+Static items may be placed in read-only memory if they do not contain any
+interior mutability.
+
+Statics may contain interior mutability through the `UnsafeCell` language item.
+All access to a static is safe, but there are a number of restrictions on
+statics:
+
+* Statics may not contain any destructors.
+* The types of static values must ascribe to `Sync` to allow threadsafe access.
+* Statics may not refer to other statics by value, only by reference.
+* Constants cannot refer to statics.
+
+Constants should in general be preferred over statics, unless large amounts of
+data are being stored, or single-address and mutability properties are required.
+
+```
+use std::sync::atomic;
+
+// Note that INIT_ATOMIC_UINT is a *const*, but it may be used to initialize a
+// static. This static can be modified, so it is not placed in read-only memory.
+static COUNTER: atomic::AtomicUint = atomic::INIT_ATOMIC_UINT;
+
+// This table is a candidate to be placed in read-only memory.
+static TABLE: &'static [uint] = &[1, 2, 3, /* ... */];
+
+for slot in TABLE.iter() {
+    println!("{}", slot);
+}
+COUNTER.fetch_add(1, atomic::SeqCst);
+```
+
 #### Mutable statics
 
 If a static item is declared with the `mut` keyword, then it is allowed to
@@ -1455,6 +1498,9 @@ unsafe fn bump_levels_unsafe2() -> uint {
 }
 ```
 
+Mutable statics have the same restrictions as normal statics, except that the
+type of the value is not required to ascribe to `Sync`.
+
 ### Traits
 
 A _trait_ describes a set of method types.

src/etc/unicode.py

@@ -333,14 +333,14 @@ def emit_property_module(f, mod, tbl, emit_fn):
 def emit_regex_module(f, cats, w_data):
     f.write("pub mod regex {\n")
     regex_class = "&'static [(char, char)]"
-    class_table = "&'static [(&'static str, %s)]" % regex_class
+    class_table = "&'static [(&'static str, &'static %s)]" % regex_class
 
     emit_table(f, "UNICODE_CLASSES", cats, class_table,
-        pfun=lambda x: "(\"%s\",super::%s::%s_table)" % (x[0], x[1], x[0]))
+        pfun=lambda x: "(\"%s\",&super::%s::%s_table)" % (x[0], x[1], x[0]))
 
-    f.write("    pub static PERLD: %s = super::general_category::Nd_table;\n\n"
+    f.write("    pub static PERLD: &'static %s = &super::general_category::Nd_table;\n\n"
             % regex_class)
-    f.write("    pub static PERLS: %s = super::property::White_Space_table;\n\n"
+    f.write("    pub static PERLS: &'static %s = &super::property::White_Space_table;\n\n"
             % regex_class)
 
     emit_table(f, "PERLW", w_data, regex_class)

src/liballoc/heap.rs

@@ -85,7 +85,7 @@ pub fn stats_print() {
 ///
 /// This preserves the non-null invariant for types like `Box<T>`. The address may overlap with
 /// non-zero-size memory allocations.
-pub static EMPTY: *mut () = 0x1 as *mut ();
+pub const EMPTY: *mut () = 0x1 as *mut ();
 
 /// The allocator for unique pointers.
 #[cfg(not(test))]

src/libcollections/trie.rs

@@ -34,10 +34,10 @@ use slice::{Items, MutItems};
 use slice;
 
 // FIXME: #5244: need to manually update the TrieNode constructor
-static SHIFT: uint = 4;
-static SIZE: uint = 1 << SHIFT;
-static MASK: uint = SIZE - 1;
-static NUM_CHUNKS: uint = uint::BITS / SHIFT;
+const SHIFT: uint = 4;
+const SIZE: uint = 1 << SHIFT;
+const MASK: uint = SIZE - 1;
+const NUM_CHUNKS: uint = uint::BITS / SHIFT;
 
 #[deriving(Clone)]
 enum Child<T> {

src/libcore/atomic.rs

@@ -77,19 +77,19 @@ pub enum Ordering {
 
 /// An `AtomicBool` initialized to `false`
 #[unstable = "may be renamed, pending conventions for static initalizers"]
-pub static INIT_ATOMIC_BOOL: AtomicBool =
+pub const INIT_ATOMIC_BOOL: AtomicBool =
         AtomicBool { v: UnsafeCell { value: 0 }, nocopy: marker::NoCopy };
 /// An `AtomicInt` initialized to `0`
 #[unstable = "may be renamed, pending conventions for static initalizers"]
-pub static INIT_ATOMIC_INT: AtomicInt =
+pub const INIT_ATOMIC_INT: AtomicInt =
         AtomicInt { v: UnsafeCell { value: 0 }, nocopy: marker::NoCopy };
 /// An `AtomicUint` initialized to `0`
 #[unstable = "may be renamed, pending conventions for static initalizers"]
-pub static INIT_ATOMIC_UINT: AtomicUint =
+pub const INIT_ATOMIC_UINT: AtomicUint =
         AtomicUint { v: UnsafeCell { value: 0, }, nocopy: marker::NoCopy };
 
 // NB: Needs to be -1 (0b11111111...) to make fetch_nand work correctly
-static UINT_TRUE: uint = -1;
+const UINT_TRUE: uint = -1;
 
 #[stable]
 impl AtomicBool {

src/libcore/cell.rs

@@ -219,8 +219,8 @@ pub struct RefCell<T> {
 // Values [1, MAX-1] represent the number of `Ref` active
 // (will not outgrow its range since `uint` is the size of the address space)
 type BorrowFlag = uint;
-static UNUSED: BorrowFlag = 0;
-static WRITING: BorrowFlag = -1;
+const UNUSED: BorrowFlag = 0;
+const WRITING: BorrowFlag = -1;
 
 impl<T> RefCell<T> {
     /// Create a new `RefCell` containing `value`

src/libcore/char.rs

@@ -63,7 +63,7 @@ static MAX_THREE_B: u32 =  0x10000u32;
 */
 
 /// The highest valid code point
-pub static MAX: char = '\U0010ffff';
+pub const MAX: char = '\U0010ffff';
 
 /// Converts from `u32` to a `char`
 #[inline]

src/libcore/num/f32.rs

@@ -20,29 +20,29 @@ use num::{FPNormal, FPCategory, FPZero, FPSubnormal, FPInfinite, FPNaN};
 use num::Float;
 use option::Option;
 
-pub static RADIX: uint = 2u;
+pub const RADIX: uint = 2u;
 
-pub static MANTISSA_DIGITS: uint = 24u;
-pub static DIGITS: uint = 6u;
+pub const MANTISSA_DIGITS: uint = 24u;
+pub const DIGITS: uint = 6u;
 
-pub static EPSILON: f32 = 1.19209290e-07_f32;
+pub const EPSILON: f32 = 1.19209290e-07_f32;
 
 /// Smallest finite f32 value
-pub static MIN_VALUE: f32 = -3.40282347e+38_f32;
+pub const MIN_VALUE: f32 = -3.40282347e+38_f32;
 /// Smallest positive, normalized f32 value
-pub static MIN_POS_VALUE: f32 = 1.17549435e-38_f32;
+pub const MIN_POS_VALUE: f32 = 1.17549435e-38_f32;
 /// Largest finite f32 value
-pub static MAX_VALUE: f32 = 3.40282347e+38_f32;
+pub const MAX_VALUE: f32 = 3.40282347e+38_f32;
 
-pub static MIN_EXP: int = -125;
-pub static MAX_EXP: int = 128;
+pub const MIN_EXP: int = -125;
+pub const MAX_EXP: int = 128;
 
-pub static MIN_10_EXP: int = -37;
-pub static MAX_10_EXP: int = 38;
+pub const MIN_10_EXP: int = -37;
+pub const MAX_10_EXP: int = 38;
 
-pub static NAN: f32 = 0.0_f32/0.0_f32;
-pub static INFINITY: f32 = 1.0_f32/0.0_f32;
-pub static NEG_INFINITY: f32 = -1.0_f32/0.0_f32;
+pub const NAN: f32 = 0.0_f32/0.0_f32;
+pub const INFINITY: f32 = 1.0_f32/0.0_f32;
+pub const NEG_INFINITY: f32 = -1.0_f32/0.0_f32;
 
 /// Various useful constants.
 pub mod consts {
@@ -53,55 +53,55 @@ pub mod consts {
     // of `Float`.
 
     /// Archimedes' constant
-    pub static PI: f32 = 3.14159265358979323846264338327950288_f32;
+    pub const PI: f32 = 3.14159265358979323846264338327950288_f32;
 
     /// pi * 2.0
-    pub static PI_2: f32 = 6.28318530717958647692528676655900576_f32;
+    pub const PI_2: f32 = 6.28318530717958647692528676655900576_f32;
 
     /// pi/2.0
-    pub static FRAC_PI_2: f32 = 1.57079632679489661923132169163975144_f32;
+    pub const FRAC_PI_2: f32 = 1.57079632679489661923132169163975144_f32;
 
     /// pi/3.0
-    pub static FRAC_PI_3: f32 = 1.04719755119659774615421446109316763_f32;
+    pub const FRAC_PI_3: f32 = 1.04719755119659774615421446109316763_f32;
 
     /// pi/4.0
-    pub static FRAC_PI_4: f32 = 0.785398163397448309615660845819875721_f32;
+    pub const FRAC_PI_4: f32 = 0.785398163397448309615660845819875721_f32;
 
     /// pi/6.0
-    pub static FRAC_PI_6: f32 = 0.52359877559829887307710723054658381_f32;
+    pub const FRAC_PI_6: f32 = 0.52359877559829887307710723054658381_f32;
 
     /// pi/8.0
-    pub static FRAC_PI_8: f32 = 0.39269908169872415480783042290993786_f32;
+    pub const FRAC_PI_8: f32 = 0.39269908169872415480783042290993786_f32;
 
     /// 1.0/pi
-    pub static FRAC_1_PI: f32 = 0.318309886183790671537767526745028724_f32;
+    pub const FRAC_1_PI: f32 = 0.318309886183790671537767526745028724_f32;
 
     /// 2.0/pi
-    pub static FRAC_2_PI: f32 = 0.636619772367581343075535053490057448_f32;
+    pub const FRAC_2_PI: f32 = 0.636619772367581343075535053490057448_f32;
 
     /// 2.0/sqrt(pi)
-    pub static FRAC_2_SQRTPI: f32 = 1.12837916709551257389615890312154517_f32;
+    pub const FRAC_2_SQRTPI: f32 = 1.12837916709551257389615890312154517_f32;
 
     /// sqrt(2.0)
-    pub static SQRT2: f32 = 1.41421356237309504880168872420969808_f32;
+    pub const SQRT2: f32 = 1.41421356237309504880168872420969808_f32;
 
     /// 1.0/sqrt(2.0)
-    pub static FRAC_1_SQRT2: f32 = 0.707106781186547524400844362104849039_f32;
+    pub const FRAC_1_SQRT2: f32 = 0.707106781186547524400844362104849039_f32;
 
     /// Euler's number
-    pub static E: f32 = 2.71828182845904523536028747135266250_f32;
+    pub const E: f32 = 2.71828182845904523536028747135266250_f32;
 
     /// log2(e)
-    pub static LOG2_E: f32 = 1.44269504088896340735992468100189214_f32;
+    pub const LOG2_E: f32 = 1.44269504088896340735992468100189214_f32;
 
     /// log10(e)
-    pub static LOG10_E: f32 = 0.434294481903251827651128918916605082_f32;
+    pub const LOG10_E: f32 = 0.434294481903251827651128918916605082_f32;
 
     /// ln(2.0)
-    pub static LN_2: f32 = 0.693147180559945309417232121458176568_f32;
+    pub const LN_2: f32 = 0.693147180559945309417232121458176568_f32;
 
     /// ln(10.0)
-    pub static LN_10: f32 = 2.30258509299404568401799145468436421_f32;
+    pub const LN_10: f32 = 2.30258509299404568401799145468436421_f32;
 }
 
 impl Float for f32 {
@@ -143,8 +143,8 @@ impl Float for f32 {
     /// is going to be tested, it is generally faster to use the specific
     /// predicate instead.
     fn classify(self) -> FPCategory {
-        static EXP_MASK: u32 = 0x7f800000;
-        static MAN_MASK: u32 = 0x007fffff;
+        const EXP_MASK: u32 = 0x7f800000;
+        const MAN_MASK: u32 = 0x007fffff;
 
         let bits: u32 = unsafe { mem::transmute(self) };
         match (bits & MAN_MASK, bits & EXP_MASK) {