---

yaml
---
r: 89962
b: refs/heads/master
c: a1afe9c
h: refs/heads/master
v: v3

Author: thestinger

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 6143400aaac2239feb979deebe9777f6edccce1a
+refs/heads/master: a1afe9cc0ad410af599ff580d41ce9c9e158136f
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: a6d3e57dca68fde4effdda3e4ae2887aa535fcd6
 refs/heads/try: b160761e35efcd1207112b3b782c06633cf441a8

trunk/doc/tutorial.md

@@ -890,7 +890,9 @@ 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.
+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.
 
 ~~~~
 // the struct owns the objects contained in the `x` and `y` fields
@@ -1007,6 +1009,51 @@ 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
@@ -1300,52 +1347,6 @@ 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/librustdoc/html/render.rs

@@ -466,15 +466,14 @@ impl DocFolder for Cache {
         // Register any generics to their corresponding string. This is used
         // when pretty-printing types
         match item.inner {
-            clean::StructItem(ref s)          => self.generics(&s.generics),
-            clean::EnumItem(ref e)            => self.generics(&e.generics),
-            clean::FunctionItem(ref f)        => self.generics(&f.generics),
-            clean::TypedefItem(ref t)         => self.generics(&t.generics),
-            clean::TraitItem(ref t)           => self.generics(&t.generics),
-            clean::ImplItem(ref i)            => self.generics(&i.generics),
-            clean::TyMethodItem(ref i)        => self.generics(&i.generics),
-            clean::MethodItem(ref i)          => self.generics(&i.generics),
-            clean::ForeignFunctionItem(ref f) => self.generics(&f.generics),
+            clean::StructItem(ref s)   => self.generics(&s.generics),
+            clean::EnumItem(ref e)     => self.generics(&e.generics),
+            clean::FunctionItem(ref f) => self.generics(&f.generics),
+            clean::TypedefItem(ref t)  => self.generics(&t.generics),
+            clean::TraitItem(ref t)    => self.generics(&t.generics),
+            clean::ImplItem(ref i)     => self.generics(&i.generics),
+            clean::TyMethodItem(ref i) => self.generics(&i.generics),
+            clean::MethodItem(ref i)   => self.generics(&i.generics),
             _ => {}
         }
 

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
+}