---

yaml
---
r: 121471
b: refs/heads/master
c: 315f2a7
h: refs/heads/master
i:
  121469: 92e5462
  121467: dc89d95
  121463: 0ea63ef
  121455: e239b0b
  121439: 3c891a8
  121407: b488d6f
  121343: 4d3dd29
v: v3

Author: pcwalton

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 9e103acaba98ce654c073c89f74a84b861f16d6e
+refs/heads/master: 315f2a70542078c45c9f7ebf4face32a54fde774
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: bab614f5fa725d248afc5f0530c835f37998ce8f
 refs/heads/try: 1813e5aa1a03b0596b8de7abd1af31edf5d6098f

trunk/src/doc/guide-unsafe.md

@@ -3,12 +3,13 @@
 # Introduction
 
 Rust aims to provide safe abstractions over the low-level details of
-the CPU and operating system, but sometimes one needs to drop down and
-write code at that level. This guide aims to provide an overview of
-the dangers and power one gets with Rust's unsafe subset.
+the CPU and operating system, but sometimes one is forced to drop down
+and write code at that level (those abstractions have to be created
+somehow). This guide aims to provide an overview of the dangers and
+power one gets with Rust's unsafe subset.
 
 Rust provides an escape hatch in the form of the `unsafe { ... }`
-block which allows the programmer to dodge some of the compiler's
+block which allows the programmer to dodge some of the compilers
 checks and do a wide range of operations, such as:
 
 - dereferencing [raw pointers](#raw-pointers)
@@ -17,12 +18,13 @@ checks and do a wide range of operations, such as:
 - [inline assembly](#inline-assembly)
 
 Note that an `unsafe` block does not relax the rules about lifetimes
-of `&` and the freezing of borrowed data.
+of `&` and the freezing of borrowed data, it just allows the use of
+additional techniques for skirting the compiler's watchful eye. Any
+use of `unsafe` is the programmer saying "I know more than you" to the
+compiler, and, as such, the programmer should be very sure that they
+actually do know more about why that piece of code is valid.
 
-Any use of `unsafe` is the programmer saying "I know more than you" to
-the compiler, and, as such, the programmer should be very sure that
-they actually do know more about why that piece of code is valid.  In
-general, one should try to minimize the amount of unsafe code in a
+In general, one should try to minimize the amount of unsafe code in a
 code base; preferably by using the bare minimum `unsafe` blocks to
 build safe interfaces.
 
@@ -36,25 +38,25 @@ build safe interfaces.
 
 ## References
 
-One of Rust's biggest features is memory safety.  This is achieved in
-part via [the lifetime system](guide-lifetimes.html), which is how the
+One of Rust's biggest goals as a language is ensuring memory safety,
+achieved in part via [the lifetime system](guide-lifetimes.html) which
+every `&` references has associated with it. This system is how the
 compiler can guarantee that every `&` reference is always valid, and,
 for example, never pointing to freed memory.
 
-These restrictions on `&` have huge advantages. However, they also
-constrain how we can use them. For example, `&` doesn't behave
-identically to C's pointers, and so cannot be used for pointers in
-foreign function interfaces (FFI). Additionally, both immutable (`&`)
-and mutable (`&mut`) references have some aliasing and freezing
-guarantees, required for memory safety.
+These restrictions on `&` have huge advantages. However, there's no
+free lunch club. For example, `&` isn't a valid replacement for C's
+pointers, and so cannot be used for FFI, in general. Additionally,
+both immutable (`&`) and mutable (`&mut`) references have some
+aliasing and freezing guarantees, required for memory safety.
 
 In particular, if you have an `&T` reference, then the `T` must not be
 modified through that reference or any other reference. There are some
 standard library types, e.g. `Cell` and `RefCell`, that provide inner
 mutability by replacing compile time guarantees with dynamic checks at
 runtime.
 
-An `&mut` reference has a different constraint: when an object has an
+An `&mut` reference has a stronger requirement: when an object has an
 `&mut T` pointing into it, then that `&mut` reference must be the only
 such usable path to that object in the whole program. That is, an
 `&mut` cannot alias with any other references.
@@ -104,19 +106,19 @@ offered by the Rust language and libraries. For example, they
 
 Fortunately, they come with a redeeming feature: the weaker guarantees
 mean weaker restrictions. The missing restrictions make raw pointers
-appropriate as a building block for implementing things like smart
-pointers and vectors inside libraries. For example, `*` pointers are
-allowed to alias, allowing them to be used to write shared-ownership
-types like reference counted and garbage collected pointers, and even
-thread-safe shared memory types (`Rc` and the `Arc` types are both
-implemented entirely in Rust).
+appropriate as a building block for (carefully!) implementing things
+like smart pointers and vectors inside libraries. For example, `*`
+pointers are allowed to alias, allowing them to be used to write
+shared-ownership types like reference counted and garbage collected
+pointers, and even thread-safe shared memory types (`Rc` and the `Arc`
+types are both implemented entirely in Rust).
 
 There are two things that you are required to be careful about
 (i.e. require an `unsafe { ... }` block) with raw pointers:
 
 - dereferencing: they can have any value: so possible results include
   a crash, a read of uninitialised memory, a use-after-free, or
-  reading data as normal.
+  reading data as normal (and one hopes happens).
 - pointer arithmetic via the `offset` [intrinsic](#intrinsics) (or
   `.offset` method): this intrinsic uses so-called "in-bounds"
   arithmetic, that is, it is only defined behaviour if the result is
@@ -175,10 +177,9 @@ code:
 - store pointers privately (i.e. not in public fields of public
   structs), so that you can see and control all reads and writes to
   the pointer in one place.
-- use `assert!()` a lot: since you can't rely on the protection of the
-  compiler & type-system to ensure that your `unsafe` code is correct
-  at compile-time, use `assert!()` to verify that it is doing the
-  right thing at run-time.
+- use `assert!()` a lot: once you've thrown away the protection of the
+  compiler & type-system via `unsafe { ... }` you're left with just
+  your wits and your `assert!()`s, any bug is potentially exploitable.
 - implement the `Drop` for resource clean-up via a destructor, and use
   RAII (Resource Acquisition Is Initialization). This reduces the need
   for any manual memory management by users, and automatically ensures
@@ -304,8 +305,8 @@ asm!(assembly template
 Any use of `asm` is feature gated (requires `#![feature(asm)]` on the
 crate to allow) and of course requires an `unsafe` block.
 
-> **Note**: the examples here are given in x86/x86-64 assembly, but
-> all platforms are supported.
+> **Note**: the examples here are given in x86/x86-64 assembly, but all
+> platforms are supported.
 
 ## Assembly template
 
@@ -595,7 +596,7 @@ standard library itself.
 > parts of the language may never be full specified and so details may
 > differ wildly between implementations (and even versions of `rustc`
 > itself).
-> 
+>
 > Furthermore, this is just an overview; the best form of
 > documentation for specific instances of these features are their
 > definitions and uses in `std`.
@@ -688,7 +689,8 @@ fn main(argc: int, argv: **u8) -> int {
 ```
 
 Note the use of `abort`: the `exchange_malloc` lang item is assumed to
-return a valid pointer, and so needs to do the check internally.
+return a valid pointer, and so needs to do the check
+internally.
 
 Other features provided by lang items include: