---

yaml
---
r: 52223
b: refs/heads/dist-snap
c: f0fa67d
h: refs/heads/master
i:
  52221: 658eb92
  52219: c8b5c1b
  52215: 9845623
  52207: 124e9ef
  52191: 09c4b89
  52159: 7977215
  52095: bd64783
  51967: d089c10
  51711: 775cbe8
  51199: 3ac8141
v: v3

Author: pcwalton

[refs]

@@ -7,7 +7,7 @@ refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
 refs/heads/try2: 147ecfdd8221e4a4d4e090486829a06da1e0ca3c
 refs/heads/incoming: 44d4d6de762f3f9aae1fedcf454c66b79b3ad58d
-refs/heads/dist-snap: ca71c6ec5bb8106121cbe33eec5a6a9ca7786039
+refs/heads/dist-snap: f0fa67d6bf22bbca80c1c148de05c7990a2ed04b
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503
 refs/heads/try3: 9387340aab40a73e8424c48fd42f0c521a4875c0

branches/dist-snap/doc/tutorial.md

@@ -863,11 +863,34 @@ allocating memory and indirecting through a pointer. But for big structs, or
 those with mutable fields, it can be useful to have a single copy on
 the stack or on the heap, and refer to that through a pointer.
 
-Rust supports several types of pointers. The safe pointer types are
-`@T`, for managed boxes allocated on the local heap, `~T`, for
-uniquely-owned boxes allocated on the exchange heap, and `&T`, for
-borrowed pointers, which may point to any memory, and whose lifetimes
-are governed by the call stack.
+Whenever memory is allocated on the heap, the program needs a strategy to
+dispose of the memory when no longer needed. Most languages, such as Java or
+Python, use *garbage collection* for this, a strategy in which the program
+periodically searches for allocations that are no longer reachable in order
+to dispose of them. Other languages, such as C, use *manual memory
+management*, which relies on the programmer to specify when memory should be
+reclaimed.
+
+Rust is in a different position. It differs from the garbage-collected
+environments in that allows the programmer to choose the disposal
+strategy on an object-by-object basis. Not only does this have benefits for
+performance, but we will later see that this model has benefits for
+concurrency as well, by making it possible for the Rust compiler to detect
+data races at compile time. Rust also differs from the manually managed
+languages in that it is *safe*—it uses a [pointer lifetime
+analysis][borrow] to ensure that manual memory management cannot cause memory
+errors at runtime.
+
+[borrow]: tutorial-borrowed-ptr.html
+
+The cornerstone of Rust's memory management is the concept of a *smart
+pointer*—a pointer type that indicates the lifetime of the object it points
+to. This solution is familiar to C++ programmers; Rust differs from C++,
+however, in that a small set of smart pointers are built into the language.
+The safe pointer types are `@T`, for *managed* boxes allocated on the *local
+heap*, `~T`, for *uniquely-owned* boxes allocated on the *exchange
+heap*, and `&T`, for *borrowed* pointers, which may point to any memory, and
+whose lifetimes are governed by the call stack.
 
 All pointer types can be dereferenced with the `*` unary operator.
 
@@ -919,7 +942,17 @@ node2.next = SomeNode(node3);
 node3.prev = SomeNode(node2);
 ~~~
 
-Managed boxes never cross task boundaries.
+Managed boxes never cross task boundaries. This has several benefits for
+performance:
+
+* The Rust garbage collector does not need to stop multiple threads in order
+  to collect garbage.
+
+* You can separate your application into "real-time" tasks that do not use
+  the garbage collector and "non-real-time" tasks that do, and the real-time
+  tasks will not be interrupted by the non-real-time tasks.
+
+C++ programmers will recognize `@T` as similar to `std::shared_ptr<T>`.
 
 > ***Note:*** Currently, the Rust compiler generates code to reclaim
 > managed boxes through reference counting and a cycle collector, but
@@ -956,10 +989,19 @@ let z = *x + *y;
 assert z == 20;
 ~~~~
 
-Owned boxes, when they do not contain any managed boxes, can be sent
-to other tasks. The sending task will give up ownership of the box,
+When they do not contain any managed boxes, owned boxes can be sent
+to other tasks. The sending task will give up ownership of the box
 and won't be able to access it afterwards. The receiving task will
-become the sole owner of the box.
+become the sole owner of the box. This prevents *data races*—errors
+that could otherwise result from multiple tasks working on the same
+data without synchronization.
+
+When an owned pointer goes out of scope or is overwritten, the object
+it points to is immediately freed. Effective use of owned boxes can
+therefore be an efficient alternative to garbage collection.
+
+C++ programmers will recognize `~T` as similar to `std::unique_ptr<T>`
+(or `std::auto_ptr<T>` in C++03 and below).
 
 ## Borrowed pointers