add md files

lifetimes.md

@@ -0,0 +1,13 @@
+% Advanced Lifetimes
+
+Lifetimes are the breakout feature of Rust.
+
+# Safe Rust
+
+* no aliasing of &mut
+
+# Unsafe Rust
+
+* Splitting lifetimes into disjoint regions
+* Creating lifetimes from raw pointers
+*

raii.md

@@ -0,0 +1,179 @@
+% The Perils Of RAII
+
+Ownership Based Resource Management (AKA RAII: Resource Acquisition is Initialization) is
+something you'll interact with a lot in Rust. Especially if you use the standard library.
+
+Roughly speaking the pattern is as follows: to acquire a resource, you create an object that
+manages it. To release the resource, you simply destroy the object, and it cleans up the
+resource for you. The most common "resource"
+this pattern manages is simply *memory*. `Box`, `Rc`, and basically everything in
+`std::collections` is a convenience to enable correctly managing memory. This is particularly
+important in Rust because we have no pervasive GC to rely on for memory management. Which is the
+point, really: Rust is about control. However we are not limited to just memory.
+Pretty much every other system resource like a thread, file, or socket is exposed through
+this kind of API.
+
+So, how does RAII work in Rust? Unlike C++, Rust does not come with a slew on builtin
+kinds of constructor. There are no Copy, Default, Assignment, Move, or whatever constructors.
+This largely has to do with Rust's philosophy of being explicit.
+
+Move constructors are meaningless in Rust because we don't enable types to "care" about their
+location in memory. Every type must be ready for it to be blindly memcopied to somewhere else
+in memory. This means pure on-the-stack-but-still-movable intrusive linked lists are simply
+not happening in Rust (safely).
+
+Assignment and copy constructors similarly don't exist because move semantics are the *default*
+in rust. At most `x = y` just moves the bits of y into the x variable. Rust does provide two
+facilities for going back to C++'s copy-oriented semantics: `Copy` and `Clone`. Clone is our
+moral equivalent of copy constructor, but it's never implicitly invoked. You have to explicitly
+call `clone` on an element you want to be cloned. Copy is a special case of Clone where the
+implementation is just "duplicate the bitwise representation". Copy types *are* implicitely
+cloned whenever they're moved, but because of the definition of Copy this just means *not*
+treating the old copy as uninitialized; a no-op.
+
+While Rust provides a `Default` trait for specifying the moral equivalent of a default
+constructor, it's incredibly rare for this trait to be used. This is because variables
+aren't implicitely initialized (see [working with uninitialized memory][uninit] for details).
+Default is basically only useful for generic programming.
+
+More often than not, in a concrete case a type will provide a static `new` method for any
+kind of "default" constructor. This has no relation to `new` in other languages and has no
+special meaning. It's just a naming convention.
+
+What the language *does* provide is full-blown automatic destructors through the `Drop` trait,
+which provides the following method:
+
+```rust
+fn drop(&mut self);
+```
+
+This method gives the type time to somehow finish what it was doing. **After `drop` is run,
+Rust will recursively try to drop all of the fields of the `self` struct**. This is a
+convenience feature so that you don't have to write "destructor boilerplate" dropping
+children. **There is no way to prevent this in Rust 1.0**.  Also note that `&mut self` means
+that even if you *could* supress recursive Drop, Rust will prevent you from e.g. moving fields
+out of self. For most types, this is totally fine: they own all their data, there's no
+additional state passed into drop to try to send it to, and `self` is about to be marked as
+uninitialized (and therefore inaccessible).
+
+For instance, a custom implementation of `Box` might write `Drop` like this:
+
+```rust
+struct Box<T>{ ptr: *mut T }
+
+impl<T> Drop for Box<T> {
+	fn drop(&mut self) {
+		unsafe {
+			(*self.ptr).drop();
+			heap::deallocate(self.ptr);
+		}
+	}
+}
+```
+
+and this works fine because when Rust goes to drop the `ptr` field it just sees a *mut that
+has no actual `Drop` implementation. Similarly nothing can use-after-free the `ptr` because
+the Box is completely gone.
+
+However this wouldn't work:
+
+```rust
+struct Box<T>{ ptr: *mut T }
+
+impl<T> Drop for Box<T> {
+	fn drop(&mut self) {
+		unsafe {
+			(*self.ptr).drop();
+			heap::deallocate(self.ptr);
+		}
+	}
+}
+
+struct SuperBox<T> { box: Box<T> }
+
+impl<T> Drop for SuperBox<T> {
+	fn drop(&mut self) {
+		unsafe {
+			// Hyper-optimized: deallocate the box's contents for it
+			// without `drop`ing the contents
+			heap::deallocate(self.box.ptr);
+		}
+	}
+}
+```
+
+because after we deallocate the `box`'s ptr in SuperBox's destructor, Rust will
+happily proceed to tell the box to Drop itself and everything will blow up with
+use-after-frees and double-frees.
+
+Note that the recursive drop behaviour applies to *all* structs and enums
+regardless of whether they implement Drop. Therefore something like
+
+```rust
+struct Boxy<T> {
+	data1: Box<T>,
+	data2: Box<T>,
+	info: u32,
+}
+```
+
+will have its data1 and data2's fields destructors whenever it "would" be
+dropped, even though it itself doesn't implement Drop. We say that such a type
+*needs Drop*, even though it is not itself Drop.
+
+Similarly,
+
+```rust
+enum Link {
+	Next(Box<Link>),
+	None,
+}
+```
+
+will have its inner Box field dropped *if and only if* a value stores the Next variant.
+
+In general this works really nice because you don't need to worry about adding/removing
+dtors when you refactor your data layout. Still there's certainly many valid usecases for
+needing to do trickier things with destructors.
+
+The classic safe solution to blocking recursive drop semantics and allowing moving out
+of Self is to use an Option:
+
+```rust
+struct Box<T>{ ptr: *mut T }
+
+impl<T> Drop for Box<T> {
+	fn drop(&mut self) {
+		unsafe {
+			(*self.ptr).drop();
+			heap::deallocate(self.ptr);
+		}
+	}
+}
+
+struct SuperBox<T> { box: Option<Box<T>> }
+
+impl<T> Drop for SuperBox<T> {
+	fn drop(&mut self) {
+		unsafe {
+			// Hyper-optimized: deallocate the box's contents for it
+			// without `drop`ing the contents. Need to set the `box`
+			// fields as `None` to prevent Rust from trying to Drop it.
+			heap::deallocate(self.box.take().unwrap().ptr);
+		}
+	}
+}
+```
+
+However this has fairly odd semantics: you're saying that a field that *should* always be Some
+may be None, just because that happens in the dtor. Of course this conversely makes a lot of sense:
+you can call arbitrary methods on self during the destructor, and this should prevent you from
+ever doing so after deinitializing the field. Not that it will prevent you from producing any other
+arbitrarily invalid state in there.
+
+On balance this is an ok choice. Certainly if you're just getting started.
+
+In the future, we expect there to be a first-class way to announce that a field
+should be automatically dropped.
+
+[uninit]:

uninitialized.md

@@ -0,0 +1,179 @@
+% Working With Uninitialized Memory
+
+All runtime-allocated memory in a Rust program begins its life as *uninitialized*. In this state the value of the memory is an indeterminate pile of bits that may or may not even reflect a valid state for the type that is supposed to inhabit that location of memory. Attempting to interpret this memory as a value of *any* type will cause Undefined Behaviour. Do Not Do This.
+
+Like C, all stack variables in Rust begin their life as uninitialized until a value is explicitly assigned to them. Unlike C, Rust statically prevents you from ever reading them until you do:
+
+```rust
+fn main() {
+	let x: i32;
+	println!("{}", x);
+}
+```
+
+```text
+src/main.rs:3:20: 3:21 error: use of possibly uninitialized variable: `x`
+src/main.rs:3     println!("{}", x);
+                                 ^
+```
+
+This is based off of a basic branch analysis: every branch must assign a value to `x` before it
+is first used. Interestingly, Rust doesn't require the variable to be mutable to perform a delayed initialization if every branch assigns exactly once. However the analysis does not take advantage of constant analysis or anything like that. So this compiles:
+
+```rust
+fn main() {
+	let x: i32;
+	let y: i32;
+
+	y = 1;
+
+	if true {
+		x = 1;
+	} else {
+		x = 2;
+	}
+
+    println!("{} {}", x, y);
+}
+```
+
+but this doesn't:
+
+```rust
+fn main() {
+	let x: i32;
+	if true {
+		x = 1;
+	}
+	println!("{}", x);
+}
+```
+
+```text
+src/main.rs:6:17: 6:18 error: use of possibly uninitialized variable: `x`
+src/main.rs:6 	println!("{}", x);
+```
+
+while this does:
+
+```rust
+fn main() {
+	let x: i32;
+	if true {
+		x = 1;
+		println!("{}", x);
+	}
+	// Don't care that there are branches where it's not initialized
+	// since we don't use the value in those branches
+}
+```
+
+If a value is moved out of a variable, that variable becomes logically uninitialized if the type
+of the value isn't Copy. That is:
+
+```rust
+fn main() {
+	let x = 0;
+	let y = Box::new(0);
+	let z1 = x; // x is still valid because i32 is Copy
+	let z2 = y; // y has once more become logically uninitialized, since Box is not Copy
+}
+```
+
+However reassigning `y` in this example *would* require `y` to be marked as mutable, as a
+Safe Rust program could observe that the value of `y` changed. Otherwise the variable is
+exactly like new.
+
+This raises an interesting question with respect to `Drop`: where does Rust
+try to call the destructor of a variable that is conditionally initialized?
+It turns out that Rust actually tracks whether a type should be dropped or not *at runtime*. As a
+variable becomes initialized and uninitialized, a *drop flag* for that variable is set and unset.
+When a variable goes out of scope or is assigned it evaluates whether the current value of the
+variable should be dropped. Of course, static analysis can remove these checks. If the compiler
+can prove that a value is guaranteed to be either initialized or not, then it can theoretically
+generate more efficient code! As such it may be desirable to structure code to have *static drop
+semantics* when possible.
+
+As of Rust 1.0, the drop flags are actually not-so-secretly stashed in a secret field of any type
+that implements Drop. The language sets the drop flag by overwriting the entire struct with a
+particular value. This is pretty obviously Not The Fastest and causes a bunch of trouble with
+optimizing code. As such work is currently under way to move the flags out onto the stack frame
+where they more reasonably belong. Unfortunately this work will take some time as it requires
+fairly substantial changes to the compiler.
+
+So in general, Rust programs don't need to worry about uninitialized values on the stack for
+correctness. Although they might care for performance. Thankfully, Rust makes it easy to take
+control here! Uninitialized values are there, and Safe Rust lets you work with them, but you're
+never in trouble.
+
+One interesting exception to this rule is working with arrays. Safe Rust doesn't permit you to
+partially initialize an array. When you initialize an array, you can either set every value to the
+same thing with `let x = [val; N]`, or you can specify each member individually with
+`let x = [val1, val2, val3]`. Unfortunately this is pretty rigid, especially if you need
+to initialize your array in a more incremental or dynamic way.
+
+Unsafe Rust gives us a powerful tool to handle this problem: `std::mem::uninitialized`.
+This function pretends to return a value when really it does nothing at all. Using it, we can
+convince Rust that we have initialized a variable, allowing us to do trickier things with
+conditional and incremental initialization.
+
+Unfortunately, this raises a tricky problem. Assignment has a different meaning to Rust based on
+whether it believes that a variable is initialized or not. If it's uninitialized, then Rust will
+semantically just memcopy the bits over the uninit ones, and do nothing else. However if Rust
+believes a value to be initialized, it will try to `Drop` the old value! Since we've tricked Rust
+into believing that the value is initialized, we can no longer safely use normal assignment.
+
+This is also a problem if you're working with a raw system allocator, which of course returns a
+pointer to uninitialized memory.
+
+To handle this, we must use the `std::ptr` module. In particular, it provides three functions that
+allow us to assign bytes to a location in memory without evaluating the old value: `write`, `copy`, and `copy_nonoverlapping`.
+
+* `ptr::write(ptr, val)` takes a `val` and moves it into the address pointed to by `ptr`.
+* `ptr::copy(src, dest, count)` copies the bits that `count` T's would occupy from src to dest. (this is equivalent to memmove -- note that the argument order is reversed!)
+* `ptr::copy_nonoverlapping(src, dest, count)` does what `copy` does, but a little faster on the
+assumption that the two ranges of memory don't overlap. (this is equivalent to memcopy -- note that the argument order is reversed!)
+
+It should go without saying that these functions, if misused, will cause serious havoc or just
+straight up Undefined Behaviour. The only things that these functions *themselves* require is that
+the locations you want to read and write are allocated. However the ways writing arbitrary bit
+patterns to arbitrary locations of memory can break things are basically uncountable!
+
+Putting this all together, we get the following:
+
+```rust
+fn main() {
+	use std::mem;
+
+	// size of the array is hard-coded but easy to change. This means we can't
+	// use [a, b, c] syntax to initialize the array, though!
+	const SIZE = 10;
+
+	let x: [Box<u32>; SIZE];
+
+	unsafe {
+		// convince Rust that x is Totally Initialized
+		x = mem::uninitialized();
+		for i in 0..SIZE {
+			// very carefully overwrite each index without reading it
+			ptr::write(&mut x[i], Box::new(i));
+		}
+	}
+
+	println!("{}", x);
+}
+```
+
+It's worth noting that you don't need to worry about ptr::write-style shenanigans with
+Plain Old Data (POD; types which don't implement Drop, nor contain Drop types),
+because Rust knows not to try to Drop them. Similarly you should be able to assign the POD
+fields of partially initialized structs directly.
+
+However when working with uninitialized memory you need to be ever vigilant for Rust trying to
+Drop values you make like this before they're fully initialized. So every control path through
+that variable's scope must initialize the value before it ends. *This includes code panicking*.
+Again, POD types need not worry.
+
+And that's about it for working with uninitialized memory! Basically nothing anywhere expects
+to be handed uninitialized memory, so if you're going to pass it around at all, be sure to be
+*really* careful.