---

yaml
---
r: 89967
b: refs/heads/master
c: 8d87e9d
h: refs/heads/master
i:
  89965: b195c08
  89963: 1c6dc4e
  89959: 345c788
  89951: 77915df
v: v3

Author: bors

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 80dff186416180423fe8117cbd19930a6c813ed9
+refs/heads/master: 8d87e9da2146b911ded797eac1a7aa9464902617
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: a6d3e57dca68fde4effdda3e4ae2887aa535fcd6
 refs/heads/try: b160761e35efcd1207112b3b782c06633cf441a8

trunk/doc/tutorial.md

@@ -890,9 +890,7 @@ calling the destructor, and the owner determines whether the object is mutable.
 
 Ownership is recursive, so mutability is inherited recursively and a destructor
 destroys the contained tree of owned objects. Variables are top-level owners
-and destroy the contained object when they go out of scope. A box managed by
-the garbage collector starts a new ownership tree, and the destructor is called
-when it is collected.
+and destroy the contained object when they go out of scope.
 
 ~~~~
 // the struct owns the objects contained in the `x` and `y` fields
@@ -1009,51 +1007,6 @@ let mut s = r; // box becomes mutable
 let t = s; // box becomes immutable
 ~~~~
 
-# Managed boxes
-
-A managed box (`@`) is a heap allocation with the lifetime managed by a
-task-local garbage collector. It will be destroyed at some point after there
-are no references left to the box, no later than the end of the task. Managed
-boxes lack an owner, so they start a new ownership tree and don't inherit
-mutability. They do own the contained object, and mutability is defined by the
-type of the managed box (`@` or `@mut`). An object containing a managed box is
-not `Owned`, and can't be sent between tasks.
-
-~~~~
-let a = @5; // immutable
-
-let mut b = @5; // mutable variable, immutable box
-b = @10;
-
-let c = @mut 5; // immutable variable, mutable box
-*c = 10;
-
-let mut d = @mut 5; // mutable variable, mutable box
-*d += 5;
-d = @mut 15;
-~~~~
-
-A mutable variable and an immutable variable can refer to the same box, given
-that their types are compatible. Mutability of a box is a property of its type,
-however, so for example a mutable handle to an immutable box cannot be
-assigned a reference to a mutable box.
-
-~~~~
-let a = @1;     // immutable box
-let b = @mut 2; // mutable box
-
-let mut c : @int;       // declare a variable with type managed immutable int
-let mut d : @mut int;   // and one of type managed mutable int
-
-c = a;          // box type is the same, okay
-d = b;          // box type is the same, okay
-~~~~
-
-~~~~ {.xfail-test}
-// but b cannot be assigned to c, or a to d
-c = b;          // error
-~~~~
-
 # Borrowed pointers
 
 Rust's borrowed pointers are a general purpose reference type. In contrast with
@@ -1347,6 +1300,52 @@ defined in [`std::vec`] and [`std::str`].
 [`std::vec`]: std/vec/index.html
 [`std::str`]: std/str/index.html
 
+# Ownership escape hatches
+
+Ownership can cleanly describe tree-like data structures, and borrowed pointers provide non-owning
+references. However, more flexibility is often desired and Rust provides ways to escape from strict
+single parent ownership.
+
+The standard library provides the `std::rc::Rc` pointer type to express *shared ownership* over a
+reference counted box. As soon as all of the `Rc` pointers go out of scope, the box and the
+contained value are destroyed.
+
+~~~
+use std::rc::Rc;
+
+// A fixed-size array allocated in a reference-counted box
+let x = Rc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+let y = x.clone(); // a new owner
+let z = x; // this moves `x` into `z`, rather than creating a new owner
+
+assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+
+let mut a = Rc::new([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]); // the variable is mutable, but not the box
+a = z;
+~~~
+
+A garbage collected pointer is provided via `std::gc::Gc`, with a task-local garbage collector
+having ownership of the box. It allows the creation of cycles, and the individual `Gc` pointers do
+not have a destructor.
+
+~~~
+use std::gc::Gc;
+
+// A fixed-size array allocated in a garbage-collected box
+let x = Gc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+let y = x; // does not perform a move, unlike with `Rc`
+let z = x;
+
+assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
+~~~
+
+With shared ownership, mutability cannot be inherited so the boxes are always immutable. However,
+it's possible to use *dynamic* mutability via types like `std::cell::Cell` where freezing is handled
+via dynamic checks and can fail at runtime.
+
+The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe
+immutable and mutable shared memory is provided by the `extra::arc` module.
+
 # Closures
 
 Named functions, like those we've seen so far, may not refer to local

trunk/src/librustc/middle/lint.rs

@@ -75,6 +75,7 @@ pub enum lint {
     type_limits,
     type_overflow,
     unused_unsafe,
+    unsafe_block,
 
     managed_heap_memory,
     owned_heap_memory,
@@ -236,6 +237,13 @@ static lint_table: &'static [(&'static str, LintSpec)] = &[
         default: warn
     }),
 
+    ("unsafe_block",
+     LintSpec {
+        lint: unsafe_block,
+        desc: "usage of an `unsafe` block",
+        default: allow
+    }),
+
     ("unused_variable",
      LintSpec {
         lint: unused_variable,
@@ -870,8 +878,7 @@ fn check_pat_non_uppercase_statics(cx: &Context, p: &ast::Pat) {
 
 fn check_unused_unsafe(cx: &Context, e: &ast::Expr) {
     match e.node {
-        // Don't warn about generated blocks, that'll just pollute the
-        // output.
+        // Don't warn about generated blocks, that'll just pollute the output.
         ast::ExprBlock(ref blk) => {
             if blk.rules == ast::UnsafeBlock(ast::UserProvided) &&
                 !cx.tcx.used_unsafe.contains(&blk.id) {
@@ -883,6 +890,16 @@ fn check_unused_unsafe(cx: &Context, e: &ast::Expr) {
     }
 }
 
+fn check_unsafe_block(cx: &Context, e: &ast::Expr) {
+    match e.node {
+        // Don't warn about generated blocks, that'll just pollute the output.
+        ast::ExprBlock(ref blk) if blk.rules == ast::UnsafeBlock(ast::UserProvided) => {
+            cx.span_lint(unsafe_block, blk.span, "usage of an `unsafe` block");
+        }
+        _ => ()
+    }
+}
+
 fn check_unused_mut_pat(cx: &Context, p: @ast::Pat) {
     match p.node {
         ast::PatIdent(ast::BindByValue(ast::MutMutable),
@@ -1126,6 +1143,7 @@ impl<'self> Visitor<()> for Context<'self> {
         check_while_true_expr(self, e);
         check_stability(self, e);
         check_unused_unsafe(self, e);
+        check_unsafe_block(self, e);
         check_unnecessary_allocation(self, e);
         check_heap_expr(self, e);
 

trunk/src/libstd/rand/distributions/mod.rs

@@ -444,17 +444,17 @@ mod tests {
     fn test_rand_sample() {
         let mut rand_sample = RandSample::<ConstRand>;
 
-        assert_eq!(*rand_sample.sample(task_rng()), 0);
-        assert_eq!(*rand_sample.ind_sample(task_rng()), 0);
+        assert_eq!(*rand_sample.sample(&mut task_rng()), 0);
+        assert_eq!(*rand_sample.ind_sample(&mut task_rng()), 0);
     }
 
     #[test]
     fn test_normal() {
         let mut norm = Normal::new(10.0, 10.0);
-        let rng = task_rng();
+        let mut rng = task_rng();
         for _ in range(0, 1000) {
-            norm.sample(rng);
-            norm.ind_sample(rng);
+            norm.sample(&mut rng);
+            norm.ind_sample(&mut rng);
         }
     }
     #[test]
@@ -466,10 +466,10 @@ mod tests {
     #[test]
     fn test_exp() {
         let mut exp = Exp::new(10.0);
-        let rng = task_rng();
+        let mut rng = task_rng();
         for _ in range(0, 1000) {
-            assert!(exp.sample(rng) >= 0.0);
-            assert!(exp.ind_sample(rng) >= 0.0);
+            assert!(exp.sample(&mut rng) >= 0.0);
+            assert!(exp.ind_sample(&mut rng) >= 0.0);
         }
     }
     #[test]

trunk/src/libstd/rand/distributions/range.rs

@@ -183,7 +183,7 @@ mod tests {
 
     #[test]
     fn test_integers() {
-        let rng = task_rng();
+        let mut rng = task_rng();
         macro_rules! t (
             ($($ty:ty),*) => {{
                 $(
@@ -193,9 +193,9 @@ mod tests {
                    for &(low, high) in v.iter() {
                         let mut sampler: Range<$ty> = Range::new(low, high);
                         for _ in range(0, 1000) {
-                            let v = sampler.sample(rng);
+                            let v = sampler.sample(&mut rng);
                             assert!(low <= v && v < high);
-                            let v = sampler.ind_sample(rng);
+                            let v = sampler.ind_sample(&mut rng);
                             assert!(low <= v && v < high);
                         }
                     }
@@ -208,7 +208,7 @@ mod tests {
 
     #[test]
     fn test_floats() {
-        let rng = task_rng();
+        let mut rng = task_rng();
         macro_rules! t (
             ($($ty:ty),*) => {{
                 $(
@@ -219,9 +219,9 @@ mod tests {
                    for &(low, high) in v.iter() {
                         let mut sampler: Range<$ty> = Range::new(low, high);
                         for _ in range(0, 1000) {
-                            let v = sampler.sample(rng);
+                            let v = sampler.sample(&mut rng);
                             assert!(low <= v && v < high);
-                            let v = sampler.ind_sample(rng);
+                            let v = sampler.ind_sample(&mut rng);
                             assert!(low <= v && v < high);
                         }
                     }

trunk/src/libstd/rand/mod.rs

@@ -577,11 +577,24 @@ impl reseeding::Reseeder<StdRng> for TaskRngReseeder {
     }
 }
 static TASK_RNG_RESEED_THRESHOLD: uint = 32_768;
+type TaskRngInner = reseeding::ReseedingRng<StdRng, TaskRngReseeder>;
 /// The task-local RNG.
-pub type TaskRng = reseeding::ReseedingRng<StdRng, TaskRngReseeder>;
+#[no_send]
+pub struct TaskRng {
+    // This points into TLS (specifically, it points to the endpoint
+    // of a ~ stored in TLS, to make it robust against TLS moving
+    // things internally) and so this struct cannot be legally
+    // transferred between tasks *and* it's unsafe to deallocate the
+    // RNG other than when a task is finished.
+    //
+    // The use of unsafe code here is OK if the invariants above are
+    // satisfied; and it allows us to avoid (unnecessarily) using a
+    // GC'd or RC'd pointer.
+    priv rng: *mut TaskRngInner
+}
 
 // used to make space in TLS for a random number generator
-local_data_key!(TASK_RNG_KEY: @mut TaskRng)
+local_data_key!(TASK_RNG_KEY: ~TaskRngInner)
 
 /// Retrieve the lazily-initialized task-local random number
 /// generator, seeded by the system. Intended to be used in method
@@ -594,34 +607,34 @@ local_data_key!(TASK_RNG_KEY: @mut TaskRng)
 /// if the operating system random number generator is rigged to give
 /// the same sequence always. If absolute consistency is required,
 /// explicitly select an RNG, e.g. `IsaacRng` or `Isaac64Rng`.
-pub fn task_rng() -> @mut TaskRng {
-    let r = local_data::get(TASK_RNG_KEY, |k| k.map(|k| *k));
-    match r {
+pub fn task_rng() -> TaskRng {
+    local_data::get_mut(TASK_RNG_KEY, |rng| match rng {
         None => {
-            let rng = @mut reseeding::ReseedingRng::new(StdRng::new(),
+            let mut rng = ~reseeding::ReseedingRng::new(StdRng::new(),
                                                         TASK_RNG_RESEED_THRESHOLD,
                                                         TaskRngReseeder);
+            let ptr = &mut *rng as *mut TaskRngInner;
+
             local_data::set(TASK_RNG_KEY, rng);
-            rng
+
+            TaskRng { rng: ptr }
         }
-        Some(rng) => rng
-    }
+        Some(rng) => TaskRng { rng: &mut **rng }
+    })
 }
 
-// Allow direct chaining with `task_rng`
-impl<R: Rng> Rng for @mut R {
-    #[inline]
+impl Rng for TaskRng {
     fn next_u32(&mut self) -> u32 {
-        (**self).next_u32()
+        unsafe { (*self.rng).next_u32() }
     }
-    #[inline]
+
     fn next_u64(&mut self) -> u64 {
-        (**self).next_u64()
+        unsafe { (*self.rng).next_u64() }
     }
 
     #[inline]
     fn fill_bytes(&mut self, bytes: &mut [u8]) {
-        (**self).fill_bytes(bytes);
+        unsafe { (*self.rng).fill_bytes(bytes) }
     }
 }
 

trunk/src/test/compile-fail/lint-unsafe-block.rs

@@ -0,0 +1,20 @@
+// 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.
+
+#[allow(unused_unsafe)];
+#[deny(unsafe_block)];
+
+unsafe fn allowed() {}
+
+#[allow(unsafe_block)] fn also_allowed() { unsafe {} }
+
+fn main() {
+    unsafe {} //~ ERROR: usage of an `unsafe` block
+}

trunk/src/test/compile-fail/task-rng-isnt-sendable.rs

@@ -0,0 +1,18 @@
+// 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.
+
+// ensure that the TaskRng isn't/doesn't become accidentally sendable.
+
+fn test_send<S: Send>() {}
+
+pub fn main() {
+    test_send::<::std::rand::TaskRng>();
+    //~^ ERROR: incompatible type `std::rand::TaskRng`, which does not fulfill `Send`
+}