diff --git a/lifetimes.md b/lifetimes.md new file mode 100644 index 0000000..5730192 --- /dev/null +++ b/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 +* \ No newline at end of file diff --git a/raii.md b/raii.md new file mode 100644 index 0000000..13a2bdf --- /dev/null +++ b/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{ ptr: *mut T } + +impl Drop for Box { + 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{ ptr: *mut T } + +impl Drop for Box { + fn drop(&mut self) { + unsafe { + (*self.ptr).drop(); + heap::deallocate(self.ptr); + } + } +} + +struct SuperBox { box: Box } + +impl Drop for SuperBox { + 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 { + data1: Box, + data2: Box, + 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), + 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{ ptr: *mut T } + +impl Drop for Box { + fn drop(&mut self) { + unsafe { + (*self.ptr).drop(); + heap::deallocate(self.ptr); + } + } +} + +struct SuperBox { box: Option> } + +impl Drop for SuperBox { + 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]: \ No newline at end of file diff --git a/uninitialized.md b/uninitialized.md new file mode 100644 index 0000000..89d0a93 --- /dev/null +++ b/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; 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.