---

yaml
---
r: 138619
b: refs/heads/try2
c: febdb49
h: refs/heads/master
i:
  138617: 4d7eaf4
  138615: f549390
v: v3

Author: nikomatsakis

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 9519ee5d808d8015faad6681693cc406e00c9f81
+refs/heads/try2: febdb49e9269724058aacf645610912bf26ecdb4
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/configure

@@ -678,7 +678,7 @@ do
         LLVM_BUILD_DIR=${CFG_BUILD_DIR}llvm/$t
         if [ ! -z "$CFG_DISABLE_OPTIMIZE_LLVM" ]
         then
-            LLVM_DBG_OPTS="--enable-debug-symbols --disable-optimized"
+            LLVM_DBG_OPTS=""
             # Just use LLVM straight from its build directory to
             # avoid 'make install' time
             LLVM_INST_DIR=$LLVM_BUILD_DIR/Debug+Asserts

branches/try2/doc/rust.md

@@ -297,7 +297,7 @@ the following forms:
 num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ?
         | '0' [       [ dec_digit | '_' ] + num_suffix ?
               | 'b'   [ '1' | '0' | '_' ] + int_suffix ?
-              | 'x'   [ hex_digit | '_' ] + int_suffix ? ] ;
+              | 'x'   [ hex_digit | '-' ] + int_suffix ? ] ;
 
 num_suffix : int_suffix | float_suffix ;
 
@@ -1610,10 +1610,11 @@ The following are examples of structure expressions:
 ~~~~
 # struct Point { x: float, y: float }
 # struct TuplePoint(float, float);
-# mod game { pub struct User { name: &str, age: uint, score: uint } }
+# mod game { pub struct User { name: &str, age: uint, mut score: uint } }
+# use game;
 Point {x: 10f, y: 20f};
 TuplePoint(10f, 20f);
-let u = game::User {name: "Joe", age: 35u, score: 100_000};
+let u = game::User {name: "Joe", age: 35u, mut score: 100_000};
 ~~~~
 
 A structure expression forms a new value of the named structure type.

branches/try2/doc/tutorial-borrowed-ptr.md

@@ -348,12 +348,12 @@ mutations:
 ~~~ {.xfail-test}
 fn example3() -> int {
     struct R { g: int }
-    struct S { f: ~R }
+    struct S { mut f: ~R }
 
-    let mut x = ~S {f: ~R {g: 3}};
+    let mut x = ~S {mut f: ~R {g: 3}};
     let y = &x.f.g;
-    x = ~S {f: ~R {g: 4}};  // Error reported here.
-    x.f = ~R {g: 5};        // Error reported here.
+    x = ~S {mut f: ~R {g: 4}}; // Error reported here.
+    x.f = ~R {g: 5};           // Error reported here.
     *y
 }
 ~~~
@@ -362,6 +362,91 @@ In this case, two errors are reported, one when the variable `x` is
 modified and another when `x.f` is modified. Either modification would
 invalidate the pointer `y`.
 
+Things get trickier when the unique box is not uniquely owned by the
+stack frame, or when there is no way for the compiler to determine the
+box's owner. Consider a program like this:
+
+~~~ {.xfail-test}
+struct R { g: int }
+struct S { mut f: ~R }
+fn example5a(x: @S, callback: @fn()) -> int {
+    let y = &x.f.g;   // Error reported here.
+    ...
+    callback();
+    ...
+#   return 0;
+}
+~~~
+
+Here the heap looks something like:
+
+~~~ {.notrust}
+     Stack            Managed Heap       Exchange Heap
+
+  x +------+        +-------------+       +------+
+    | @... | ---->  | mut f: ~... | --+-> | g: 3 |
+  y +------+        +-------------+   |   +------+
+    | &int | -------------------------+
+    +------+
+~~~
+
+In this case, the owning reference to the value being borrowed is
+`x.f`. Moreover, `x.f` is both mutable and *aliasable*. Aliasable
+means that there may be other pointers to that same managed box, so
+even if the compiler were to prove an absence of mutations to `x.f`,
+code could mutate `x.f` indirectly by changing an alias of
+`x`. Therefore, to be safe, the compiler only accepts *pure* actions
+during the lifetime of `y`. We define what "pure" means in the section
+on [purity](#purity).
+
+Besides ensuring purity, the only way to borrow the interior of a
+unique found in aliasable memory is to ensure that the borrowed field
+itself is also unique, as in the following example:
+
+~~~
+struct R { g: int }
+struct S { f: ~R }
+fn example5b(x: @S) -> int {
+    let y = &x.f.g;
+    ...
+# return 0;
+}
+~~~
+
+Here, the field `f` is not declared as mutable. But that is enough for
+the compiler to know that, even if aliases to `x` exist, the field `f`
+cannot be changed and hence the unique box `g` will remain valid.
+
+If you do have a unique box in a mutable field, and you wish to borrow
+it, one option is to use the swap operator to move that unique box
+onto your stack:
+
+~~~
+struct R { g: int }
+struct S { mut f: ~R }
+fn example5c(x: @S) -> int {
+    let mut v = ~R {g: 0};
+    v <-> x.f;         // Swap v and x.f
+    { // Block constrains the scope of `y`:
+        let y = &v.g;
+        ...
+    }
+    x.f = v;          // Replace x.f
+    ...
+# return 0;
+}
+~~~
+
+Of course, this has the side effect of modifying your managed box for
+the duration of the borrow, so it only works when you know that you
+won't be accessing that same box for the duration of the loan. Also,
+it is sometimes necessary to introduce additional blocks to constrain
+the scope of the loan.  In this example, the borrowed pointer `y`
+would still be in scope when you moved the value `v` back into `x.f`,
+and hence moving `v` would be considered illegal.  You cannot move
+values if they are the targets of valid outstanding loans. Introducing
+the block restricts the scope of `y`, making the move legal.
+
 # Borrowing and enums
 
 The previous example showed that the type system forbids any borrowing
@@ -473,6 +558,11 @@ permit `ref` bindings into data owned by the stack frame even if the
 data are mutable, but otherwise it requires that the data reside in
 immutable memory.
 
+> ***Note:*** Right now, pattern bindings not explicitly annotated
+> with `ref` or `copy` use a special mode of "implicit by reference".
+> This is changing as soon as we finish updating all the existing code
+> in the compiler that relies on the current settings.
+
 # Returning borrowed pointers
 
 So far, all of the examples we've looked at use borrowed pointers in a
@@ -655,6 +745,69 @@ fn select<T>(shape: &Shape, threshold: float,
 
 This is equivalent to the previous definition.
 
+# Purity
+
+As mentioned before, the Rust compiler offers a kind of escape hatch
+that permits borrowing of any data, as long as the actions that occur
+during the lifetime of the borrow are pure. Pure actions are those
+that only modify data owned by the current stack frame. The compiler
+can therefore permit arbitrary pointers into the heap, secure in the
+knowledge that no pure action will ever cause them to become
+invalidated (the compiler must still track data on the stack which is
+borrowed and enforce those rules normally, of course). A pure function
+in Rust is referentially transparent: it returns the same results
+given the same (observably equivalent) inputs. That is because while
+pure functions are allowed to modify data, they may only modify
+*stack-local* data, which cannot be observed outside the scope of the
+function itself. (Using an `unsafe` block invalidates this guarantee.)
+
+Let’s revisit a previous example and show how purity can affect
+typechecking. Here is `example5a()`, which borrows the interior of a
+unique box found in an aliasable, mutable location, only now we’ve
+replaced the `...` with some specific code:
+
+~~~
+struct R { g: int }
+struct S { mut f: ~R }
+fn example5a(x: @S ...) -> int {
+    let y = &x.f.g;   // Unsafe
+    *y + 1        
+}
+~~~
+
+The new code simply returns an incremented version of `y`. This code
+clearly doesn't mutate the heap, so the compiler is satisfied.
+
+But suppose we wanted to pull the increment code into a helper, like
+this:
+
+~~~
+fn add_one(x: &int) -> int { *x + 1 }
+~~~
+
+We can now update `example5a()` to use `add_one()`:
+
+~~~
+# struct R { g: int }
+# struct S { mut f: ~R }
+# pure fn add_one(x: &int) -> int { *x + 1 }
+fn example5a(x: @S ...) -> int {
+    let y = &x.f.g;
+    add_one(y)        // Error reported here
+}
+~~~
+
+But now the compiler will report an error again. The reason is that it
+only considers one function at a time (like most typecheckers), and
+so it does not know that `add_one()` consists of pure code. We can
+help the compiler by labeling `add_one()` as pure:
+
+~~~
+pure fn add_one(x: &int) -> int { *x + 1 }
+~~~
+
+With this change, the modified version of `example5a()` will again compile.
+
 # Conclusion
 
 So there you have it: a (relatively) brief tour of the borrowed pointer

branches/try2/doc/tutorial-ffi.md

@@ -220,21 +220,21 @@ extern mod std;
 use libc::c_ulonglong;
 
 struct timeval {
-    tv_sec: c_ulonglong,
-    tv_usec: c_ulonglong
+    mut tv_sec: c_ulonglong,
+    mut tv_usec: c_ulonglong
 }
 
 #[nolink]
 extern mod lib_c {
-    fn gettimeofday(tv: *mut timeval, tz: *()) -> i32;
+    fn gettimeofday(tv: *timeval, tz: *()) -> i32;
 }
 fn unix_time_in_microseconds() -> u64 {
     unsafe {
-        let mut x = timeval {
-            tv_sec: 0 as c_ulonglong,
-            tv_usec: 0 as c_ulonglong
+        let x = timeval {
+            mut tv_sec: 0 as c_ulonglong,
+            mut tv_usec: 0 as c_ulonglong
         };
-        lib_c::gettimeofday(&mut x, ptr::null());
+        lib_c::gettimeofday(ptr::addr_of(&x), ptr::null());
         return (x.tv_sec as u64) * 1000_000_u64 + (x.tv_usec as u64);
     }
 }

branches/try2/doc/tutorial-tasks.md

@@ -468,6 +468,7 @@ Here is the function that implements the child task:
 
 ~~~~
 # use std::comm::DuplexStream;
+# use comm::{Port, Chan};
 fn stringifier(channel: &DuplexStream<~str, uint>) {
     let mut value: uint;
     loop {
@@ -490,6 +491,7 @@ Here is the code for the parent task:
 
 ~~~~
 # use std::comm::DuplexStream;
+# use comm::{Port, Chan};
 # use task::spawn;
 # fn stringifier(channel: &DuplexStream<~str, uint>) {
 #     let mut value: uint;

branches/try2/doc/tutorial.md

@@ -556,7 +556,7 @@ let mut x = 5;
 loop {
     x += x - 3;
     if x % 5 == 0 { break; }
-    io::println(int::to_str(x));
+    io::println(int::str(x));
 }
 ~~~~
 
@@ -583,16 +583,19 @@ Inherited mutability means that any field of a struct may be mutable, if the
 struct is in a mutable slot (or a field of a struct in a mutable slot, and
 so forth).
 
+A struct that is not mutable due to inherited mutability may declare some
+of its fields nevertheless mutable, using the `mut` keyword.
+
 ~~~~
 struct Stack {
     content: ~[int],
-    head: uint
+    mut head: uint
 }
 ~~~~
 
-With a value (say, `mystack`) of such a type in a mutable location, you can do
-`mystack.head += 1`. But in an immutable location, such an assignment to a
-struct without inherited mutability would result in a type error.
+With a value of such a type, you can do `mystack.head += 1`. If `mut` were
+omitted from the type, such an assignment to a struct without inherited
+mutability would result in a type error.
 
 `match` patterns destructure structs. The basic syntax is
 `Name { fieldname: pattern, ... }`:
@@ -935,19 +938,19 @@ type that contains managed boxes or other managed types.
 ~~~
 // A linked list node
 struct Node {
-    next: MaybeNode,
-    prev: MaybeNode,
+    mut next: MaybeNode,
+    mut prev: MaybeNode,
     payload: int
 }
 
 enum MaybeNode {
-    SomeNode(@mut Node),
+    SomeNode(@Node),
     NoNode
 }
 
-let node1 = @mut Node { next: NoNode, prev: NoNode, payload: 1 };
-let node2 = @mut Node { next: NoNode, prev: NoNode, payload: 2 };
-let node3 = @mut Node { next: NoNode, prev: NoNode, payload: 3 };
+let node1 = @Node { next: NoNode, prev: NoNode, payload: 1 };
+let node2 = @Node { next: NoNode, prev: NoNode, payload: 2 };
+let node3 = @Node { next: NoNode, prev: NoNode, payload: 3 };
 
 // Link the three list nodes together
 node1.next = SomeNode(node2);
@@ -1126,7 +1129,7 @@ points to.
 
 ~~~
 let managed = @mut 10;
-let mut owned = ~20;
+let owned = ~mut 20;
 
 let mut value = 30;
 let borrowed = &mut value;
@@ -2270,9 +2273,7 @@ fn chicken_farmer() {
     // The same, but name it `my_chicken`
     use my_chicken = farm::chicken;
     ...
-# my_chicken();
 }
-# chicken();
 # }
 ~~~
 
@@ -2299,15 +2300,16 @@ mod farm {
 # impl Human { fn rest(&self) { } }
 # pub fn make_me_a_farm() -> farm::Farm { farm::Farm { chickens: ~[], cows: ~[], farmer: Human(0) } }
     pub struct Farm {
-        priv chickens: ~[Chicken],
-        priv cows: ~[Cow],
+        priv mut chickens: ~[Chicken],
+        priv mut cows: ~[Cow],
         farmer: Human
     }
 
+    // Note - visibility modifiers on impls currently have no effect
     impl Farm {
         priv fn feed_chickens(&self) { ... }
         priv fn feed_cows(&self) { ... }
-        pub fn add_chicken(&self, c: Chicken) { ... }
+        fn add_chicken(&self, c: Chicken) { ... }
     }
 
     pub fn feed_animals(farm: &Farm) {