From 89df25f400844092e2f667f954e84f839e3731bc Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 8 Jun 2015 09:37:34 -0700 Subject: [PATCH 001/104] first commit --- README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000000000..4227beb19de14 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +# turpl From cc5b4d314cef29aa94c5ab508f13726d934ba142 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 8 Jun 2015 09:41:58 -0700 Subject: [PATCH 002/104] add md files --- lifetimes.md | 13 ++++ raii.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++ uninitialized.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 371 insertions(+) create mode 100644 lifetimes.md create mode 100644 raii.md create mode 100644 uninitialized.md diff --git a/lifetimes.md b/lifetimes.md new file mode 100644 index 0000000000000..5730192b6a3fb --- /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 0000000000000..13a2bdf8fff7c --- /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 0000000000000..89d0a93f6385a --- /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. From f2a37fce151c2eeef1edea7001c34b2588e80f5c Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 8 Jun 2015 09:57:05 -0700 Subject: [PATCH 003/104] blurp --- .gitignore | 1 + conversions.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) create mode 100644 .gitignore create mode 100644 conversions.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000..0b84df0f02531 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.html \ No newline at end of file diff --git a/conversions.md b/conversions.md new file mode 100644 index 0000000000000..b4bde01f5ae74 --- /dev/null +++ b/conversions.md @@ -0,0 +1,12 @@ +% Type Conversions + +# Safe Rust + +* Coercions +* Casts +* Conversion Traits (Into/As/...) + +# Unsafe Rust + +* raw ptr casts +* mem::transmute From 39c047317f39df2b0f55da10f276b88826f54d3b Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 10 Jun 2015 13:57:00 -0700 Subject: [PATCH 004/104] progress --- conversions.md | 70 ++++++++++++++ data.md | 254 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 324 insertions(+) create mode 100644 data.md diff --git a/conversions.md b/conversions.md index b4bde01f5ae74..2fd750bb6649e 100644 --- a/conversions.md +++ b/conversions.md @@ -1,7 +1,77 @@ % Type Conversions +At the end of the day, everything is just a pile of bits somewhere, and type systems +are just there to help us use those bits right. Needing to reinterpret those piles +of bits as different types is a common problem and Rust consequently gives you +several ways to do that. + # Safe Rust +First we'll look at the ways that *Safe Rust* gives you to reinterpret values. The +most trivial way to do this is to just destructure a value into its constituent +parts and then build a new type out of them. e.g. + +```rust +struct Foo { + x: u32, + y: u16, +} + +struct Bar { + a: u32, + b: u16, +} + +fn reinterpret(foo: Foo) -> Bar { + let Foo { x, y } = foo; + Bar { a: x, b: y } +} +``` + +But this is, at best, annoying to do. For common conversions, rust provides +more ergonomic alternatives. + +## Auto-Deref + +Deref is a trait that allows you to overload the unary `*` to specify a type +you dereference to. This is largely only intended to be implemented by pointer +types like `&`, `Box`, and `Rc`. The dot operator will automatically perform +automatic dereferencing, so that foo.bar() will work uniformly on `Foo`, `&Foo`, `&&Foo`, +`&Rc>>` and so-on. Search bottoms out on the *first* match, +so implementing methods on pointers is generally to be avoided, as it will shadow +"actual" methods. + +## Coercions + +Types can implicitly be coerced to change in certain contexts. These changes are generally +just *weakening* of types, largely focused around pointers. They mostly exist to make +Rust "just work" in more cases. For instance +`&mut T` coerces to `&T`, and `&T` coerces to `*const T`. The most useful coercion you will +actually think about it is probably the general *Deref Coercion*: `&T` coerces to `&U` when +`T: Deref`. This enables us to pass an `&String` where an `&str` is expected, for instance. + +## Casts + +Casts are a superset of coercions: every coercion can be explicitly invoked via a cast, +but some changes require a cast. These "true casts" are generally regarded as dangerous or +problematic actions. The set of true casts is actually quite small, and once again revolves +largely around pointers. However it also introduces the primary mechanism to convert between +numeric types. + +* rawptr -> rawptr (e.g. `*mut T as *const T` or `*mut T as *mut U`) +* rawptr <-> usize (e.g. `*mut T as usize` or `usize as *mut T`) +* primitive -> primitive (e.g. `u32 as u8` or `u8 as u32`) +* c-like enum -> integer/bool (e.g. `DaysOfWeek as u8`) +* `u8` -> `char` + + +## Conversion Traits + +For full formal specification of all the kinds of coercions and coercion sites, see: +https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md + + + * Coercions * Casts * Conversion Traits (Into/As/...) diff --git a/data.md b/data.md new file mode 100644 index 0000000000000..6fa63568862c5 --- /dev/null +++ b/data.md @@ -0,0 +1,254 @@ +% Data Representation in Rust + +Low-level programming cares a lot about data layout. It's a big deal. It also pervasively +influences the rest of the language, so we're going to start by digging into how data is +represented in Rust. + +# The `rust` repr + +Rust gives you the following ways to lay out composite data: + +* structs (named product types) +* tuples (anonymous product types) +* arrays (homogeneous product types) +* enums (named sum types -- tagged unions) + +For all these, individual fields are aligned to their preferred alignment. +For primitives this is equal to +their size. For instance, a u32 will be aligned to a multiple of 32 bits, and a u16 will +be aligned to a multiple of 16 bits. Composite structures will have their size rounded +up to be a multiple of the highest alignment required by their fields, and an alignment +requirement equal to the highest alignment required by their fields. So for instance, + +```rust +struct A { + a: u8, + c: u64, + b: u32, +} +``` + +will have a size that is a multiple of 64-bits, and 64-bit alignment. + +There is *no indirection* for these types; all data is stored contiguously as you would +expect in C. However with the exception of arrays, the layout of data is not by +default specified in Rust. Given the two following struct definitions: + +```rust +struct A { + a: i32, + b: u64, +} + +struct B { + x: i32, + b: u64, +} +``` + +Rust *does* guarantee that two instances of A have their data laid out in exactly +the same way. However Rust *does not* guarantee that an instance of A has the same +field ordering or padding as an instance of B (in practice there's no *particular* +reason why they wouldn't, other than that its not currently guaranteed). + +With A and B as written, this is basically nonsensical, but several other features +of Rust make it desirable for the language to play with data layout in complex ways. + +For instance, consider this struct: + +```rust +struct Foo { + count: u16, + data1: T, + data2: U, +} +``` + +Now consider the monomorphizations of `Foo` and `Foo`. If Rust lays out the +fields in the order specified, we expect it to *pad* the values in the struct to satisfy +their *alignment* requirements. So if Rust didn't reorder fields, we would expect Rust to +produce the following: + +```rust +struct Foo { + count: u16, + data1: u16, + data2: u32, +} + +struct Foo { + count: u16, + _pad1: u16, + data1: u32, + data2: u16, + _pad2: u16, +} +``` + +The former case quite simply wastes space. An optimal use of space therefore requires +different monomorphizations to *have different field orderings*. + +**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0.0** + +Enums make this consideration even more complicated. Naively, an enum such as: + +```rust +enum Foo { + A(u32), + B(u64), + C(u8), +} +``` + +would be laid out as: + +```rust +struct FooRepr { + data: u64, // this is *really* either a u64, u32, or u8 based on `tag` + tag: u8, // 0 = A, 1 = B, 2 = C +} +``` + +And indeed this is approximately how it would be laid out in general +(modulo the size and position of `tag`). However there are several cases where +such a representation is ineffiecient. The classic case of this is Rust's +"null pointer optimization". Given a pointer that is known to not be null +(e.g. `&u32`), an enum can *store* a discriminant bit *inside* the pointer +by using null as a special value. The net result is that +`sizeof(Option<&T>) == sizeof<&T>` + +There are many types in Rust that are, or contain, "not null" pointers such as `Box`, `Vec`, +`String`, `&T`, and `&mut T`. Similarly, one can imagine nested enums pooling their tags into +a single descriminant, as they are by definition known to have a limited range of valid values. +In principle enums can use fairly elaborate algorithms to cache bits throughout nested types +with special constrained representations. As such it is *especially* desirable that we leave +enum layout unspecified today. + +# Dynamically Sized Types (DSTs) + +Rust also supports types without a statically known size. On the surface, +this is a bit nonsensical: Rust must know the size of something in order to +work with it. DSTs are generally produced as views, or through type-erasure +of types that *do* have a known size. Due to their lack of a statically known +size, these types can only exist *behind* some kind of pointer. They consequently +produce a *fat* pointer consisting of the pointer and the information that +*completes* them. + +For instance, the slice type, `[T]`, is some statically unknown number of elements +stored contiguously. `&[T]` consequently consists of a `(&T, usize)` pair that specifies +where the slice starts, and how many elements it contains. Similarly Trait Objects +support interface-oriented type erasure through a `(data_ptr, vtable_ptr)` pair. + +Structs can actually store a single DST directly as their last field, but this +makes them a DST as well: + +```rust +// Can't be stored on the stack directly +struct Foo { + info: u32, + data: [u8], +} +``` + +# Zero Sized Types (ZSTs) + +Rust actually allows types to be specified that occupy *no* space: + +```rust +struct Foo; // No fields = no size +enum Bar; // No variants = no size + +// All fields have no size = no size +struct Baz { + foo: Foo, + bar: Bar, + qux: (), // empty tuple has no size +} +``` + +On their own, ZSTs are, for obvious reasons, pretty useless. However +as with many curious layout choices in Rust, their potential is realized in a generic +context. + +Rust largely understands that any operation that produces or stores a ZST +can be reduced to a no-op. For instance, a `HashSet` can be effeciently implemented +as a thin wrapper around `HashMap` because all the operations `HashMap` normally +does to store and retrieve keys will be completely stripped in monomorphization. + +Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. + +Safe code need not worry about ZSTs, but *unsafe* code must be careful about the +consequence of types with no size. In particular, pointer offsets are no-ops, and +standard allocators (including jemalloc, the one used by Rust) generally consider +passing in `0` as Undefined Behaviour. + +# Drop Flags + +For unfortunate legacy implementation reasons, Rust as of 1.0.0 will do a nasty trick to +any type that implements the `Drop` trait (has a destructor): it will insert a secret field +in the type. That is, + +```rust +struct Foo { + a: u32, + b: u32, +} + +impl Drop for Foo { + fn drop(&mut self) { } +} +``` + +will cause Foo to secretly become: + +```rust +struct Foo { + a: u32, + b: u32, + _drop_flag: u8, +} +``` + +For details as to *why* this is done, and how to make it not happen, check out +[SOME OTHER SECTION]. + +# Alternative representations + +Rust allows you to specify alternative data layout strategies from the default Rust +one. + +# repr(C) + +This is the most important `repr`. It has fairly simple intent: do what C does. +The order, size, and alignment of fields is exactly what you would expect from +C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, +as C is the lingua-franca of the programming world. However this is also necessary +to soundly do more elaborate tricks with data layout such as reintepretting values +as a different type. + +However, the interaction with Rust's more exotic data layout features must be kept +in mind. Due to its dual purpose as a "for FFI" and "for layout control", repr(C) +can be applied to types that will be nonsensical or problematic if passed through +the FFI boundary. + +* ZSTs are still zero-sized, even though this is not a standard behaviour +in C, and is explicitly contrary to the behaviour of an empty type in C++, which +still consumes a byte of space. + +* DSTs are not a concept in C + +* **The drop flag will still be added** + +* This is equivalent to repr(u32) for enums (see below) + +# repr(packed) + +`repr(packed)` forces rust to strip any padding it would normally apply. +This may improve the memory footprint of a type, but will have negative +side-effects from "field access is heavily penalized" to "completely breaks +everything" based on target platform. + +# repr(u8), repr(u16), repr(u32), repr(u64) + +These specify the size to make a c-like enum (one which has no values in its variants). + From 3318e3d8edd4336021f4314a25618e77061f2684 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 10 Jun 2015 14:08:03 -0700 Subject: [PATCH 005/104] progress --- conversions.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/conversions.md b/conversions.md index 2fd750bb6649e..753a01416aab6 100644 --- a/conversions.md +++ b/conversions.md @@ -54,15 +54,27 @@ actually think about it is probably the general *Deref Coercion*: `&T` coerces t Casts are a superset of coercions: every coercion can be explicitly invoked via a cast, but some changes require a cast. These "true casts" are generally regarded as dangerous or -problematic actions. The set of true casts is actually quite small, and once again revolves -largely around pointers. However it also introduces the primary mechanism to convert between -numeric types. +problematic actions. True casts revolves around raw pointers and the primitive numeric +types. Here's an exhaustive list of all the true casts: * rawptr -> rawptr (e.g. `*mut T as *const T` or `*mut T as *mut U`) * rawptr <-> usize (e.g. `*mut T as usize` or `usize as *mut T`) -* primitive -> primitive (e.g. `u32 as u8` or `u8 as u32`) -* c-like enum -> integer/bool (e.g. `DaysOfWeek as u8`) +* number -> number (e.g. `u32 as i8` or `i16 as f64`) +* c-like enum -> integer/bool (e.g. `DaysOfWeek as u32`) * `u8` -> `char` +* something about arrays? + +For number -> number casts, there are quite a few cases to consider: + +* unsigned to bigger unsigned will zero-extend losslessly +* unsigned to smaller unsigned will truncate via wrapping +* signed to unsigned will ... TODO rest of this list + +The casts involving rawptrs also allow us to completely bypass type-safety +by re-interpretting a pointer of T to a pointer of U for arbitrary types, as +well as interpret integers as addresses. However it is impossible to actually +*capitalize* on this violation in Safe Rust, because derefencing a raw ptr is +`unsafe`. ## Conversion Traits From f8be0737ea47a41097bba940ce5f9f9527fb2087 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Thu, 18 Jun 2015 21:04:48 -0700 Subject: [PATCH 006/104] progress --- concurrency.md | 186 +++++++++++++++++++ conversions.md | 39 ++-- intro.md | 151 ++++++++++++++++ lifetimes.md | 470 ++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 823 insertions(+), 23 deletions(-) create mode 100644 concurrency.md create mode 100644 intro.md diff --git a/concurrency.md b/concurrency.md new file mode 100644 index 0000000000000..c600644ba63e4 --- /dev/null +++ b/concurrency.md @@ -0,0 +1,186 @@ +% Concurrency and Paralellism + +```Not sure if I want this +Safe Rust features *a ton* of tooling to make concurrency and parallelism totally +safe, easy, and fearless. This is a case where we'll really just +[defer to TRPL][trpl-conc] for the basics. + +TL;DR: The `Send` and `Sync` traits in conjunction with Rust's ownership model and +normal generic bounds make using concurrent APIs really easy and painless for +a user of Safe Rust. +``` + +## Data Races and Race Conditions + +Safe Rust guarantees an absence of data races, which are defined as: + +* two or more threads concurrently accessing a location of memory +* one of them is a write +* one of them is unsynchronized + +A data race has Undefined Behaviour, and is therefore impossible to perform +in Safe Rust. Data races are *mostly* prevented through rust's ownership system: +it's impossible to alias a mutable reference, so it's impossible to perform a +data race. Interior mutability makes this more complicated, which is largely why +we have the Send and Sync traits (see below). + +However Rust *does not* prevent general race conditions. This is +pretty fundamentally impossible, and probably honestly undesirable. Your hardware +is racy, your OS is racy, the other programs on your computer are racy, and the +world this all runs in is racy. Any system that could genuinely claim to prevent +*all* race conditions would be pretty awful to use, if not just incorrect. + +So it's perfectly "fine" for a Safe Rust program to get deadlocked or do +something incredibly stupid with incorrect synchronization. Obviously such a +program isn't very good, but Rust can only hold your hand so far. Still, a +race condition can't violate memory safety in a Rust program on +its own. Only in conjunction with some other unsafe code can a race condition +actually violate memory safety. For instance: + +```rust +use std::thread; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; + +let data = vec![1, 2, 3, 4]; +// Arc so that the memory the AtomicUsize is stored in still exists for +// the other thread to increment, even if we completely finish executing +// before it. Rust won't compile the program without it, because of the +// lifetime requirements of thread::spawn! +let idx = Arc::new(AtomicUsize::new(0)); +let other_idx = idx.clone(); + +// `move` captures other_idx by-value, moving it into this thread +thread::spawn(move || { + // It's ok to mutate idx because this value + // is an atomic, so it can't cause a Data Race. + other_idx.fetch_add(10, Ordering::SeqCst); +}); + +// Index with the value loaded from the atomic. This is safe because we +// read the atomic memory only once, and then pass a *copy* of that value +// to the Vec's indexing implementation. This indexing will be correctly +// bounds checked, and there's no chance of the value getting changed +// in the middle. However our program may panic if the thread we spawned +// managed to increment before this ran. A race condition because correct +// program execution (panicing is rarely correct) depends on order of +// thread execution. +println!("{}", data[idx.load(Ordering::SeqCst)]); + +if idx.load(Ordering::SeqCst) < data.len() { + unsafe { + // Incorrectly loading the idx *after* we did the bounds check. + // It could have changed. This is a race condition, *and dangerous* + // because we decided to do `get_unchecked`, which is `unsafe`. + println!("{}", data.get_unchecked(idx.load(Ordering::SeqCst))); + } +} +``` + +## Send and Sync + +Not everything obeys inherited mutability, though. Some types allow you to multiply +alias a location in memory while mutating it. Unless these types use synchronization +to manage this access, they are absolutely not thread safe. Rust captures this with +through the `Send` and `Sync` traits. + +* A type is Send if it is safe to send it to another thread. +* A type is Sync if it is safe to share between threads (`&T` is Send). + +Send and Sync are *very* fundamental to Rust's concurrency story. As such, a +substantial amount of special tooling exists to make them work right. First and +foremost, they're *unsafe traits*. This means that they are unsafe *to implement*, +and other unsafe code can *trust* that they are correctly implemented. Since +they're *marker traits* (they have no associated items like methods), correctly +implemented simply means that they have the intrinsic properties an implementor +should have. Incorrectly implementing Send or Sync can cause Undefined Behaviour. + +Send and Sync are also what Rust calls *opt-in builtin traits*. +This means that, unlike every other trait, they are *automatically* derived: +if a type is composed entirely of Send or Sync types, then it is Send or Sync. +Almost all primitives are Send and Sync, and as a consequence pretty much +all types you'll ever interact with are Send and Sync. + +Major exceptions include: +* raw pointers are neither Send nor Sync (because they have no safety guards) +* `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) +* `Rc` isn't Send or Sync (because the refcount is shared and unsynchronized) + +`Rc` and `UnsafeCell` are very fundamentally not thread-safe: they enable +unsynchronized shared mutable state. However raw pointers are, strictly speaking, +marked as thread-unsafe as more of a *lint*. Doing anything useful +with a raw pointer requires dereferencing it, which is already unsafe. In that +sense, one could argue that it would be "fine" for them to be marked as thread safe. + +However it's important that they aren't thread safe to prevent types that +*contain them* from being automatically marked as thread safe. These types have +non-trivial untracked ownership, and it's unlikely that their author was +necessarily thinking hard about thread safety. In the case of Rc, we have a nice +example of a type that contains a `*mut` that is *definitely* not thread safe. + +Types that aren't automatically derived can *opt-in* to Send and Sync by simply +implementing them: + +```rust +struct MyBox(*mut u8); + +unsafe impl Send for MyBox {} +unsafe impl Sync for MyBox {} +``` + +In the *incredibly rare* case that a type is *inappropriately* automatically +derived to be Send or Sync, then one can also *unimplement* Send and Sync: + +```rust +struct SpecialThreadToken(u8); + +impl !Send for SpecialThreadToken {} +impl !Sync for SpecialThreadToken {} +``` + +Note that *in and of itself* it is impossible to incorrectly derive Send and Sync. +Only types that are ascribed special meaning by other unsafe code can possible cause +trouble by being incorrectly Send or Sync. + +Most uses of raw pointers should be encapsulated behind a sufficient abstraction +that Send and Sync can be derived. For instance all of Rust's standard +collections are Send and Sync (when they contain Send and Sync types) +in spite of their pervasive use raw pointers to +manage allocations and complex ownership. Similarly, most iterators into these +collections are Send and Sync because they largely behave like an `&` or `&mut` +into the collection. + +TODO: better explain what can or can't be Send or Sync. Sufficient to appeal +only to data races? + +## Atomics + +Rust pretty blatantly just inherits LLVM's model for atomics, which in turn is +largely based off of the C11 model for atomics. This is not due these models +being particularly excellent or easy to understand. Indeed, these models are +quite complex and are known to have several flaws. Rather, it is a pragmatic +concession to the fact that *everyone* is pretty bad at modeling atomics. At very +least, we can benefit from existing tooling and research around C's model. + +Trying to fully explain these models is fairly hopeless, so we're just going to +drop that problem in LLVM's lap. + +## Actually Doing Things Concurrently + +Rust as a language doesn't *really* have an opinion on how to do concurrency or +parallelism. The standard library exposes OS threads and blocking sys-calls +because *everyone* has those and they're uniform enough that you can provide +an abstraction over them in a relatively uncontroversial way. Message passing, +green threads, and async APIs are all diverse enough that any abstraction over +them tends to involve trade-offs that we weren't willing to commit to for 1.0. + +However Rust's current design is setup so that you can set up your own +concurrent paradigm or library as you see fit. Just require the right +lifetimes and Send and Sync where appropriate and everything should Just Work +with everyone else's stuff. + + + + +[llvm-conc]: http://llvm.org/docs/Atomics.html +[trpl-conc]: https://doc.rust-lang.org/book/concurrency.html diff --git a/conversions.md b/conversions.md index 753a01416aab6..4fe86284a31ef 100644 --- a/conversions.md +++ b/conversions.md @@ -13,18 +13,18 @@ parts and then build a new type out of them. e.g. ```rust struct Foo { - x: u32, - y: u16, + x: u32, + y: u16, } struct Bar { - a: u32, - b: u16, + a: u32, + b: u16, } fn reinterpret(foo: Foo) -> Bar { - let Foo { x, y } = foo; - Bar { a: x, b: y } + let Foo { x, y } = foo; + Bar { a: x, b: y } } ``` @@ -57,18 +57,27 @@ but some changes require a cast. These "true casts" are generally regarded as da problematic actions. True casts revolves around raw pointers and the primitive numeric types. Here's an exhaustive list of all the true casts: -* rawptr -> rawptr (e.g. `*mut T as *const T` or `*mut T as *mut U`) -* rawptr <-> usize (e.g. `*mut T as usize` or `usize as *mut T`) -* number -> number (e.g. `u32 as i8` or `i16 as f64`) -* c-like enum -> integer/bool (e.g. `DaysOfWeek as u32`) -* `u8` -> `char` -* something about arrays? +TODO: gank the RFC for sweet casts For number -> number casts, there are quite a few cases to consider: -* unsigned to bigger unsigned will zero-extend losslessly -* unsigned to smaller unsigned will truncate via wrapping -* signed to unsigned will ... TODO rest of this list +* casting between two integers of the same size (e.g. i32 -> u32) is a no-op +* casting from a smaller integer to a bigger integer (e.g. u32 -> u8) will truncate +* casting from a larger integer to a smaller integer (e.g. u8 -> u32) will + * zero-extend if unsigned + * sign-extend if signed +* casting from a float to an integer will round the float towards zero. + * **NOTE: currently this will cause Undefined Behaviour if the rounded + value cannot be represented by the target integer type**. This is a bug + and will be fixed. +* casting from an integer to float will produce the floating point representation + of the integer, rounded if necessary (rounding strategy unspecified). +* casting from an f32 to an f64 is perfect and lossless. +* casting from an f64 to an f32 will produce the closest possible value + (rounding strategy unspecified). + * **NOTE: currently this will cause Undefined Behaviour if the value + is finite but larger or smaller than the largest or smallest finite + value representable by f32**. This is a bug and will be fixed. The casts involving rawptrs also allow us to completely bypass type-safety by re-interpretting a pointer of T to a pointer of U for arbitrary types, as diff --git a/intro.md b/intro.md new file mode 100644 index 0000000000000..bc0f6483baa4f --- /dev/null +++ b/intro.md @@ -0,0 +1,151 @@ +% The Unsafe Rust Programming Language + +This document seeks to complement [The Rust Programming Language][] (TRPL). +Where TRPL introduces the language and teaches the basics, TURPL dives deep into +the specification of the language, and all the nasty bits necessary to write +Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know +the basics of the language and systems programming. We will not explain the +stack or heap, we will not explain the syntax. + +## A Tale Of Two Languages + +Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. +Any time someone opines the guarantees of Rust, they are almost surely talking about +Safe Rust. However Safe Rust is not sufficient to write every program. For that, +we need the Unsafe Rust superset. + +Most fundamentally, writing bindings to other languages +(such as the C exposed by your operating system) is never going to be safe. Rust +can't control what other languages do to program execution! However Unsafe Rust is +also necessary to construct fundamental abstractions where the type system is not +sufficient to automatically prove what you're doing is sound. + +Indeed, the Rust standard library is implemented in Rust, and it makes substantial +use of Unsafe Rust for implementing IO, memory allocation, collections, +synchronization, and other low-level computational primitives. + +Upon hearing this, many wonder why they would not simply just use C or C++ in place of +Rust (or just use a "real" safe language). If we're going to do unsafe things, why not +lean on these much more established languages? + +The most important difference between C++ and Rust is a matter of defaults: +Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular +action. In deciding to work with unchecked uninitialized memory, this does not +suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, +one does not have to suddenly worry about indexing out of bounds on `y`. + +C and C++, by contrast, have pervasive unsafety baked into the language. Even the +modern best practices like `unique_ptr` have various safety pitfalls. + +It should also be noted that writing Unsafe Rust should be regarded as an exceptional +action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs +to make FFI bindings or define core abstractions. These fundamental libraries then expose +a *safe* interface for intermediate libraries and applications to build upon. And these +safe interfaces make an important promise: if your application segfaults, it's not your +fault. *They* have a bug. + +And really, how is that different from *any* safe language? Python, Ruby, and Java libraries +can internally do all sorts of nasty things. The languages themselves are no +different. Safe languages regularly have bugs that cause critical vulnerabilities. +The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different. +However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of +C to do the nasty things that need to get done. + +## What does `unsafe` mean? + +Rust tries to model memory safety through the `unsafe` keyword. Interestingly, +the meaning of `unsafe` largely revolves around what +its *absence* means. If the `unsafe` keyword is absent from a program, it should +not be possible to violate memory safety under *any* conditions. The presence +of `unsafe` means that there are conditions under which this code *could* +violate memory safety. + +To be more concrete, Rust cares about preventing the following things: + +* Dereferencing null/dangling pointers +* Reading uninitialized memory +* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell) +* Invoking Undefined Behaviour (in e.g. compiler intrinsics) +* Producing invalid primitive values: + * dangling/null references + * a `bool` that isn't 0 or 1 + * an undefined `enum` discriminant + * a `char` larger than char::MAX + * A non-utf8 `str` +* Unwinding into an FFI function +* Causing a data race + +However libraries are free to declare arbitrary requirements if they could transitively +cause memory safety issues. However Rust is otherwise quite permisive with respect to +other dubious operations. Rust considers it "safe" to: + +* Deadlock +* Leak memory +* Fail to call destructors +* Access private fields +* Overflow integers +* Delete the production database + +However any program that does such a thing is *probably* incorrect. Rust just isn't +interested in modeling these problems, as they are much harder to prevent in general, +and it's basically impossible to prevent incorrect programs from getting written. + +Their are several places `unsafe` can appear in Rust today, which can largely be +grouped into two categories: + +* There are unchecked contracts here. To declare you understand this, I require +you to write `unsafe` elsewhere: + * On functions, `unsafe` is declaring the function to be unsafe to call. Users + of the function must check the documentation to determine what this means, + and then have to write `unsafe` somewhere to identify that they're aware of + the danger. + * On trait declarations, `unsafe` is declaring that *implementing* the trait + is an unsafe operation, as it has contracts that other unsafe code is free to + trust blindly. + +* I am declaring that I have, to the best of my knowledge, adhered to the +unchecked contracts: + * On trait implementations, `unsafe` is declaring that the contract of the + `unsafe` trait has been upheld. + * On blocks, `unsafe` is declaring any unsafety from an unsafe + operation to be handled, and therefore the parent function is safe. + +There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for +historical reasons and is in the process of being phased out. See the section on +destructors for details. + +Some examples of unsafe functions: + +* `slice::get_unchecked` will perform unchecked indexing, allowing memory +safety to be freely violated. +* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is +not "in bounds" as defined by LLVM (see the lifetimes section for details). +* `mem::transmute` reinterprets some value as having the given type, +bypassing type safety in arbitrary ways. (see the conversions section for details) +* All FFI functions are `unsafe` because they can do arbitrary things. +C being an obvious culprit, but generally any language can do something +that Rust isn't happy about. (see the FFI section for details) + +As of Rust 1.0 there are exactly two unsafe traits: + +* `Send` is a marker trait (it has no actual API) that promises implementors +are safe to send to another thread. +* `Sync` is a marker trait that promises that threads can safely share +implementors through a shared reference. + +All other traits that declare any kind of contract *really* can't be trusted +to adhere to their contract when memory-safety is at stake. For instance Rust has +`PartialOrd` and `Ord` to differentiate between types which can "just" be +compared and those that implement a total ordering. However you can't actually +trust an implementor of `Ord` to actually provide a total ordering if failing to +do so causes you to e.g. index out of bounds. But if it just makes your program +do a stupid thing, then it's "fine" to rely on `Ord`. + +The reason this is the case is that `Ord` is safe to implement, and it should be +impossible for bad *safe* code to violate memory safety. Rust has traditionally +avoided making traits unsafe because it makes `unsafe` pervasive in the language, +which is not desirable. The only reason `Send` and `Sync` are unsafe is because +thread safety is a sort of fundamental thing that a program can't really guard +against locally (even by-value message passing still requires a notion Send). + + diff --git a/lifetimes.md b/lifetimes.md index 5730192b6a3fb..42304681c206e 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -1,13 +1,467 @@ -% Advanced Lifetimes +% Ownership -Lifetimes are the breakout feature of Rust. +Ownership is the breakout feature of Rust. It allows Rust to be completely +memory-safe and efficient, while avoiding garbage collection. Before getting +into the ownership system in detail, we will consider a simple but *fundamental* +language-design problem. -# Safe Rust -* no aliasing of &mut -# Unsafe Rust +## The Tagged Union Problem + +The core of the lifetime and mutability system derives from a simple problem: +internal pointers to tagged unions. For instance, consider the following code: + +```rust +enum Foo { + A(u32), + B(f64), +} + +let mut x = B(2.0); +if let B(ref mut y) = x { + *x = A(7); + // OH NO! a u32 has been interpretted as an f64! Type-safety hole! + // (this does not actually compile) + println!("{}", y); + +} +``` + +The problem here is an intersection of 3 choices: + +* data in a tagged union is inline with the tag +* tagged unions are mutable +* being able to take a pointer into a tagged union + +Remove *any* of these 3 and the problem goes away. Traditionally, functional +languages have avoided this problem by removing the mutable +option. This means that they can in principle keep their data inline (ghc has +a pragma for this). A garbage collected imperative language like Java could alternatively +solve this problem by just keeping all variants elsewhere, so that changing the +variant of a tagged union just overwrites a pointer, and anyone with an outstanding +pointer to the inner data is unaffected thanks to The Magic Of Garbage Collection. + +Rust, by contrast, takes a subtler approach. Rust allows mutation, +allows pointers to inner data, and its enums have their data allocated inline. +However it prevents anything from being mutated while there are outstanding +pointers to it! And this is all done at compile time. + +Interestingly, Rust's `std::cell` module exposes two types that offer an alternative +approach to this problem: + +* The `Cell` type allows mutation of aliased data, but +instead forbids internal pointers to that data. The only way to read or write +a Cell is to copy the bits in or out. + +* The `RefCell` type allows mutation of aliased data *and* internal pointers, but +manages this through *runtime* checks. It is effectively a thread-unsafe +read-write lock. + + + +## Lifetimes + +Rust's static checks are managed by the *borrow checker* (borrowck), which tracks +mutability and outstanding loans. This analysis can in principle be done without +any help locally. However as soon as data starts crossing the function boundary, +we have some serious trouble. In principle, borrowck could be a massive +whole-program analysis engine to handle this problem, but this would be an +atrocious solution. It would be terribly slow, and errors would be horribly +non-local. + +Instead, Rust tracks ownership through *lifetimes*. Every single reference and value +in Rust is tagged with a lifetime that indicates the scope it is valid for. +Rust has two kinds of reference: + +* Shared reference: `&` +* Mutable reference: `&mut` + +The main rules are as follows: + +* A shared reference can be aliased +* A mutable reference cannot be aliased +* A reference cannot outlive its referrent (`&'a T -> T: 'a`) + +However non-mutable variables have some special rules: + +* You cannot mutate or mutably borrow a non-mut variable, + +Only variables marked as mutable can be borrowed mutably, though this is little +more than a local lint against incorrect usage of a value. + + + + +## Weird Lifetimes + +Almost always, the mutability of a lifetime can be derived from the mutability +of the reference it is attached to. However this is not necessarily the case. +For instance in the following code: + +```rust +fn foo<'a>(input: &'a mut u8) -> &'a u8 { &* input } +``` + +One would expect the output of foo to be an immutable lifetime. However we have +derived it from the input, which is a mutable lifetime. So although we have a +shared reference, it will have the much more limited aliasing rules of a mutable +reference. As a consequence, there is no expressive benefit in a method that +mutates returning a shared reference. + + + + +## Lifetime Elision + +In order to make common patterns more ergonomic, Rust allows lifetimes to be +*elided* in function, impl, and type signatures. + +A *lifetime position* is anywhere you can write a lifetime in a type: + +```rust +&'a T +&'a mut T +T<'a> +``` + +Lifetime positions can appear as either "input" or "output": + +* For `fn` definitions, input refers to the types of the formal arguments + in the `fn` definition, while output refers to + result types. So `fn foo(s: &str) -> (&str, &str)` has elided one lifetime in + input position and two lifetimes in output position. + Note that the input positions of a `fn` method definition do not + include the lifetimes that occur in the method's `impl` header + (nor lifetimes that occur in the trait header, for a default method). + +* In the future, it should be possible to elide `impl` headers in the same manner. + +Elision rules are as follows: + +* Each elided lifetime in input position becomes a distinct lifetime + parameter. + +* If there is exactly one input lifetime position (elided or not), that lifetime + is assigned to *all* elided output lifetimes. + +* If there are multiple input lifetime positions, but one of them is `&self` or + `&mut self`, the lifetime of `self` is assigned to *all* elided output lifetimes. + +* Otherwise, it is an error to elide an output lifetime. + +Examples: + +```rust +fn print(s: &str); // elided +fn print<'a>(s: &'a str); // expanded + +fn debug(lvl: uint, s: &str); // elided +fn debug<'a>(lvl: uint, s: &'a str); // expanded + +fn substr(s: &str, until: uint) -> &str; // elided +fn substr<'a>(s: &'a str, until: uint) -> &'a str; // expanded + +fn get_str() -> &str; // ILLEGAL + +fn frob(s: &str, t: &str) -> &str; // ILLEGAL + +fn get_mut(&mut self) -> &mut T; // elided +fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded + +fn args(&mut self, args: &[T]) -> &mut Command // elided +fn args<'a, 'b, T:ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command // expanded + +fn new(buf: &mut [u8]) -> BufWriter; // elided +fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded + +``` + + + +## Unbounded Lifetimes + +Unsafe code can often end up producing references or lifetimes out of thin air. +Such lifetimes come into the world as *unbounded*. The most common source of this +is derefencing a raw pointer, which produces a reference with an unbounded lifetime. +Such a lifetime becomes as big as context demands. This is in fact more powerful +than simply becoming `'static`, because for instance `&'static &'a T` +will fail to typecheck, but the unbound lifetime will perfectly mold into +`&'a &'a T` as needed. However for most intents and purposes, such an unbounded +lifetime can be regarded as `'static`. + +Almost no reference is `'static`, so this is probably wrong. `transmute` and +`transmute_copy` are the two other primary offenders. One should endeavour to +bound an unbounded lifetime as quick as possible, especially across function +boundaries. + +Given a function, any output lifetimes that don't derive from inputs are +unbounded. For instance: + +``` +fn get_str<'a>() -> &'a str; +``` + +will produce an `&str` with an unbounded lifetime. The easiest way to avoid +unbounded lifetimes is to use lifetime elision at the function boundary. +If an output lifetime is elided, then it *must* be bounded by an input lifetime. +Of course, it might be bounded by the *wrong* lifetime, but this will usually +just cause a compiler error, rather than allow memory safety to be trivially +violated. + +Within a function, bounding lifetimes is more error-prone. The safest route +is to just use a small function to ensure the lifetime is bound. However if +this is unacceptable, the reference can be placed in a location with a specific +lifetime. Unfortunately it's impossible to name all lifetimes involved in a +function. To get around this, you can in principle use `copy_lifetime`, though +these are unstable due to their awkward nature and questionable utility. + + + + +## Subtyping and Variance + +Although Rust doesn't have any notion of inheritance, it *does* include subtyping. +In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are derived +from scopes, we can partially order them based on an *outlives* relationship. We +can even express this as a generic bound: `T: 'a` specifies that `T` *outlives* `'a`. + +We can then define subtyping on lifetimes in terms of lifetimes: `'a : 'b` implies +`'a <: b` -- if `'a' outlives `'b`, then `'a` is a subtype of `'b`. This is a very +large source of confusion, because a bigger scope is a *sub type* of a smaller scope. +This does in fact make sense. The intuitive reason for this is that if you expect an +`&'a u8`, then it's totally fine for me to hand you an `&'static u8`, in the same way +that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. + +Variance is where things get really harsh. + +Variance is a property that *type constructors* have. A type constructor in Rust +is a generic type with unbound arguments. For instance `Vec` is a type constructor +that takes a `T` and returns a `Vec`. `&` and `&mut` are type constructors that +take a lifetime and a type. + +A type constructor's *variance* is how the subtypes of its inputs affects the +subtypes of its outputs. There are three kinds of variance: + +* F is *covariant* if `T <: U` implies `F <: F` +* F is *contravariant* if `T <: U` implies `F <: F` +* F is *invariant* otherwise (no subtyping relation can be derived) + +Some important variances: + +* `&` is covariant (as is *const by metaphor) +* `&mut` is invariant (as is *mut by metaphor) +* `Fn(T)` is contravariant with respect to `T` +* `Box`, `Vec`, and all other collections are covariant +* `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" + types are invariant + +To understand why these variances are correct and desirable, we will consider several +examples. We have already covered why `&` should be covariant. + +To see why `&mut` should be invariant, consider the following code: + +```rust +fn main() { + let mut forever_str: &'static str = "hello"; + { + let string = String::from("world"); + overwrite(&mut forever_str, &mut &*string); + } + println!("{}", forever_str); +} + +fn overwrite(input: &mut T, new: &mut T) { + *input = *new; +} +``` + +The signature of `overwrite` is clearly valid: it takes mutable references to two values +of the same type, and replaces one with the other. We have seen already that `&` is +covariant, and `'static` is a subtype of *any* `'a', so `&'static str` is a +subtype of `&'a str`. Therefore, if `&mut` was +*also* covariant, then the lifetime of the `&'static str` would successfully be +"shrunk" down to the shorter lifetime of the string, and `replace` would be +called successfully. The string would subsequently be dropped, and `forever_str` +would point to freed memory when we print it! + +Therefore `&mut` should be invariant. This is the general theme of covariance vs +invariance: if covariance would allow you to *store* a short-lived value in a +longer-lived slot, then you must be invariant. + +`Box` and `Vec` are interesting cases because they're covariant, but you can +definitely store values in them! This is fine because *you can only store values +in them through a mutable reference*! The mutable reference makes the whole type +invariant, and therefore prevents you from getting in trouble. + +Being covariant allows them to be covariant when shared immutably (so you can pass +a `&Box<&'static str>` where a `&Box<&'a str>` is expected). It also allows you to +forever weaken the type by moving it into a weaker slot. That is, you can do: + +```rust +fn get_box<'a>(&'a u8) -> Box<&'a str> { + Box::new("hello") +} +``` + +which is fine because unlike the mutable borrow case, there's no one else who +"remembers" the old lifetime in the box. + +The variance of the cell types similarly follows. `&` is like an `&mut` for a +cell, because you can still store values in them through an `&`. Therefore cells +must be invariant to avoid lifetime smuggling. + +`Fn` is the most confusing case, largely because contravariance is easily the +most confusing kind of variance, and basically never comes up. To understand it, +consider a function that *takes* a function `len` that takes a function `F`. + +```rust +fn len(func: F) -> usize + where F: Fn(&'static str) -> usize +{ + func("hello") +} +``` + +We require that F is a Fn that can take an `&'static str` and print a usize. Now +say we have a function that can take an `&'a str` (for *some* 'a). Such a function actually +accepts *more* inputs, since `&'static str` is a subtype of `&'a str`. Therefore +`len` should happily accept such a function! + +So a `Fn(&'a str)` is a subtype of a `Fn(&'static str)` because +`&'static str` is a subtype of `&'a str`. Exactly contravariance. + +The variance of `*const` and `*mut` is basically arbitrary as they're not at all +type or memory safe, so their variance is determined in analogy to & and &mut +respectively. + + + + +## PhantomData and PhantomFn + +This is all well and good for the types the standard library provides, but +how is variance determined for type that *you* define? The variance of a type +over its generic arguments is determined by how they're stored. + +```rust +struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { + a: &'a A, // covariant over 'a and A + b: &'b mut B, // invariant over 'b and B + c: *const C, // covariant over C + d: *mut D, // invariant over D + e: Vec, // covariant over E + f: Cell, // invariant over F + g: G // covariant over G + h1: H // would also be covariant over H except... + h2: Cell // invariant over H, because invariance wins +} +``` + +However when working with unsafe code, we can often end up in a situation where +types or lifetimes are logically associated with a struct, but not actually +reachable. This most commonly occurs with lifetimes. For instance, the `Iter` +for `&'a [T]` is (approximately) defined as follows: + +``` +pub struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, +} +``` + +However because `'a` is unused within the struct's body, it's *unbound*. +Because of the troubles this has historically caused, unbound lifetimes and +types are *illegal* in struct definitions. Therefore we must somehow refer +to these types in the body. + +We do this using *PhantomData*, which is a special marker type. PhantomData +consumes no space, but simulates a field of the given type for the purpose of +variance. This was deemed to be less error-prone than explicitly telling the +type-system the kind of variance that you want. + +Iter logically contains `&'a T`, so this is exactly what we tell +the PhantomData to simulate: + +``` +pub struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, + _marker: marker::PhantomData<&'a T>, +} +``` + + +## Splitting Lifetimes + +The mutual exclusion property of mutable references can be very limiting when +working with a composite structure. Borrowck understands some basic stuff, but +will fall over pretty easily. Borrowck understands structs sufficiently to +understand that it's possible to borrow disjoint fields of a struct simultaneously. +So this works today: + +```rust +struct Foo { + a: i32, + b: i32, + c: i32, +} + +let mut x = Foo {a: 0, b: 0, c: 0}; +let a = &mut x.a; +let b = &mut x.b; +let c = &x.c; +*b += 1; +let c2 = &x.c; +*a += 10; +println!("{} {} {} {}", a, b, c, c2); +``` + +However borrowck doesn't understand arrays or slices in any way, so this doesn't +work: + +```rust +let x = [1, 2, 3]; +let a = &mut x[0]; +let b = &mut x[1]; +println!("{} {}", a, b); +``` + +```text +:3:18: 3:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:3 let a = &mut x[0]; + ^~~~ +:4:18: 4:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:4 let b = &mut x[1]; + ^~~~ +error: aborting due to 2 previous errors +``` + +While it was plausible that borrowck could understand this simple case, it's +pretty clearly hopeless for borrowck to understand disjointness in general +container types like a tree, especially if distinct keys actually *do* map +to the same value. + +In order to "teach" borrowck that what we're doing is ok, we need to drop down +to unsafe code. For instance, mutable slices expose a `split_at_mut` function that +consumes the slice and returns *two* mutable slices. One for everything to the +left of the index, and one for everything to the right. Intuitively we know this +is safe because the slices don't alias. However the implementation requires some +unsafety: + +```rust +fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { + unsafe { + let self2: &mut [T] = mem::transmute_copy(&self); + + (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), + ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) + } +} +``` + +This is pretty plainly dangerous. We use transmute to duplicate the slice with an +*unbounded* lifetime, so that it + + -* Splitting lifetimes into disjoint regions -* Creating lifetimes from raw pointers -* \ No newline at end of file From 3be2643cb2a64f2667fc187ed9899f291714e85a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Thu, 18 Jun 2015 21:11:00 -0700 Subject: [PATCH 007/104] stub out more stuff --- ffi.md | 0 intro.md | 11 +++++++++++ no_std.md | 0 3 files changed, 11 insertions(+) create mode 100644 ffi.md create mode 100644 no_std.md diff --git a/ffi.md b/ffi.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/intro.md b/intro.md index bc0f6483baa4f..cb644c515f2ed 100644 --- a/intro.md +++ b/intro.md @@ -7,6 +7,17 @@ Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know the basics of the language and systems programming. We will not explain the stack or heap, we will not explain the syntax. +## Sections + +* [Data Layout](data.html) +* [Ownership and Lifetimes](lifetimes.html) +* [Conversions](conversions.html) +* [Uninitialized Memory](uninitialized.html) +* [Ownership-oriented resource management (RAII)](raii.html) +* [Concurrency](concurrency.html) +* [Interfacing with other languages (FFI)](ffi.html) +* [Eliminating the Runtime (no_std)](no_std.html) + ## A Tale Of Two Languages Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. diff --git a/no_std.md b/no_std.md new file mode 100644 index 0000000000000..e69de29bb2d1d From 02134464b0ac3cb64e221fd008b8b9e6bad1d932 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 10:52:41 -0700 Subject: [PATCH 008/104] progress --- ffi.md | 45 +++++++++++++++++++++++++ lifetimes.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++--- no_std.md | 2 ++ 3 files changed, 135 insertions(+), 5 deletions(-) diff --git a/ffi.md b/ffi.md index e69de29bb2d1d..668befb4bf5fb 100644 --- a/ffi.md +++ b/ffi.md @@ -0,0 +1,45 @@ +% Interfacing with other Languages (FFI) + +*Obviously* we'd all love to live in a **glorious** world where everything is +written in Rust, Rust, and More Rust. Tragically, programs have been written +in Not Rust for over 50 years. Crufty enterprises are doomed to +support ancient code bases, and greybeard programmers stuck in their ways +*insist* on writing programs in other languages, even to this day! + +In all seriousness, there's a myriad of reasons for your codebase to be a +hybrid of different languages, and Rust is well-designed to interface with +all of them as painlessly as possible. It does this through the tried and +true strategy of all languages: pretend to be C, and understand C. + +Thanks to Rust's minimal runtime and C-like semantics, this is about as +painless as FFI with C++. Obviously, most of Rust's features are completely +incompatible with other languages: tagged unions, zero-sized-types, dynamically- +sized types, destructors, methods, traits, references, and lifetimes are all +concepts that you won't be able to expose or accept in your foreign function +interface. + +All mapping through C will give you is functions, structs, globals, raw pointers, +and C-like enums. That's it. Rust's default data layouts are also incompatible +with the C layout. See [the section on data layout][data.html] for details. +Long story short: mark FFI structs and enums with `#[repr(C)]`, mark FFI +functions as `extern`. + +## Runtime + +Rust's runtime is sufficiently minimal that it requires *no* special handling. +You don't need to set anything up. You don't need to tear anything down. +Awesome. + +The only runtime detail you *really* need to worry about is unwinding. Rust's +unwinding model is not defined to be incompatible with any particular language. +That means that if you call Rust from another language and it unwinds into the +calling language, this will cause Undefined Behaviour. Similarly, if another +language unwinds into Rust, it will also cause Undefined Behaviour. + +Rust can't really do anything about other languages unwinding into it (FFI is unsafe +for a reason!), but you can be a good FFI citizen by catching panics in any +FFI functions you export. Rust provides `thread::catch_panic` for exactly this. +Unfortunately, this API is still unstable. + +## libc + diff --git a/lifetimes.md b/lifetimes.md index 42304681c206e..ebb74bd299b46 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -60,6 +60,7 @@ read-write lock. + ## Lifetimes Rust's static checks are managed by the *borrow checker* (borrowck), which tracks @@ -219,6 +220,77 @@ these are unstable due to their awkward nature and questionable utility. + +## Higher-Rank Lifetimes + +Generics in Rust generally allow types to be instantiated with arbitrary +associated lifetimes, but this fixes the lifetimes they work with once +instantiated. For almost all types, this is exactly the desired behaviour. +For example slice::Iter can work with arbitrary lifetimes, determined by the +slice that instantiates it. However *once* Iter is instantiated the lifetimes +it works with cannot be changed. It returns references that live for some +particular `'a`. + +However some types are more flexible than this. In particular, a single +instantiation of a function can process arbitrary lifetimes: + +```rust +fn identity(input: &u8) -> &u8 { input } +``` + +What is *the* lifetime that identity works with? There is none. If you think +this is "cheating" because functions are statically instantiated, then you need +only consider the equivalent closure: + +```rust +let identity = |input: &u8| input; +``` + +These functions are *higher ranked* over the lifetimes they work with. This means +that they're generic over what they handle *after instantiation*. For most things +this would pose a massive problem, but because lifetimes don't *exist* at runtime, +this is really just a compile-time mechanism. The Fn traits contain sugar that +allows higher-rank lifetimes to simply be expressed by simply omitting lifetimes: + + +```rust +fn main() { + foo(|input| input); +} + +fn foo(f: F) + // F is higher-ranked over the lifetime these references have + where F: Fn(&u8) -> &u8 +{ + f(&0); + f(&1); +} +``` + +The desugaring of this is actually unstable: + +``` +#![feature(unboxed_closures)] + +fn main() { + foo(|input| input); +} + +fn foo(f: F) + where F: for<'a> Fn<(&'a u8,), Output=&'a u8> +{ + f(&0); + f(&1); +} +``` + +`for<'a>` is how we declare a higher-ranked lifetime. Unfortunately higher-ranked +lifetimes are still fairly new, and are missing a few features to make them +maximally useful outside of the Fn traits. + + + + ## Subtyping and Variance Although Rust doesn't have any notion of inheritance, it *does* include subtyping. @@ -227,12 +299,15 @@ from scopes, we can partially order them based on an *outlives* relationship. We can even express this as a generic bound: `T: 'a` specifies that `T` *outlives* `'a`. We can then define subtyping on lifetimes in terms of lifetimes: `'a : 'b` implies -`'a <: b` -- if `'a' outlives `'b`, then `'a` is a subtype of `'b`. This is a very +`'a <: b` -- if `'a` outlives `'b`, then `'a` is a subtype of `'b`. This is a very large source of confusion, because a bigger scope is a *sub type* of a smaller scope. This does in fact make sense. The intuitive reason for this is that if you expect an `&'a u8`, then it's totally fine for me to hand you an `&'static u8`, in the same way that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. +(Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary +construct that some disagree with. I just find that it simplifies this analysis.) + Variance is where things get really harsh. Variance is a property that *type constructors* have. A type constructor in Rust @@ -278,7 +353,7 @@ fn overwrite(input: &mut T, new: &mut T) { The signature of `overwrite` is clearly valid: it takes mutable references to two values of the same type, and replaces one with the other. We have seen already that `&` is -covariant, and `'static` is a subtype of *any* `'a', so `&'static str` is a +covariant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a subtype of `&'a str`. Therefore, if `&mut` was *also* covariant, then the lifetime of the `&'static str` would successfully be "shrunk" down to the shorter lifetime of the string, and `replace` would be @@ -341,8 +416,16 @@ respectively. ## PhantomData and PhantomFn This is all well and good for the types the standard library provides, but -how is variance determined for type that *you* define? The variance of a type -over its generic arguments is determined by how they're stored. +how is variance determined for type that *you* define? A struct is, informally +speaking, covariant over all its fields (and an enum over its variants). This +basically means that it inherits the variance of its fields. If a struct `Foo` +has a generic argument `A` that is used in a field `a`, then Foo's variance +over `A` is exactly `a`'s variance. However this is complicated if `A` is used +in multiple fields. + +* If all uses of A are covariant, then Foo is covariant over A +* If all uses of A are contravariant, then Foo is contravariant over A +* Otherwise, Foo is invariant over A ```rust struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { @@ -360,7 +443,7 @@ struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { However when working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually -reachable. This most commonly occurs with lifetimes. For instance, the `Iter` +part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` for `&'a [T]` is (approximately) defined as follows: ``` diff --git a/no_std.md b/no_std.md index e69de29bb2d1d..8da5b78cadb40 100644 --- a/no_std.md +++ b/no_std.md @@ -0,0 +1,2 @@ +% Eliminating the Runtime (no_std) + From 74b398b93d647237acbc1c738e55e47ec13ea7b2 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 14:23:41 -0700 Subject: [PATCH 009/104] progress on lifetimes --- lifetimes.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 120 insertions(+), 12 deletions(-) diff --git a/lifetimes.md b/lifetimes.md index ebb74bd299b46..84bc7e2ef5947 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -1,4 +1,4 @@ -% Ownership +% Ownership and Lifetimes Ownership is the breakout feature of Rust. It allows Rust to be completely memory-safe and efficient, while avoiding garbage collection. Before getting @@ -58,6 +58,13 @@ a Cell is to copy the bits in or out. manages this through *runtime* checks. It is effectively a thread-unsafe read-write lock. +For more details see Dan Grossman's Existential Types for Imperative Languages: +* [paper][grossman-paper] (Advanced) +* [slides][grossman-slides] (Simple) + +[grossman-paper]: http://homes.cs.washington.edu/~djg/papers/exists_imp.pdf +[grossman-slides]: https://homes.cs.washington.edu/~djg/slides/esop02_talk.pdf + @@ -96,19 +103,49 @@ more than a local lint against incorrect usage of a value. ## Weird Lifetimes -Almost always, the mutability of a lifetime can be derived from the mutability -of the reference it is attached to. However this is not necessarily the case. -For instance in the following code: +Given the following code: ```rust -fn foo<'a>(input: &'a mut u8) -> &'a u8 { &* input } +struct Foo; + +impl Foo { + fn mutate_and_share(&mut self) -> &Self { &*self } + fn share(&self) {} +} + +fn main() { + let mut foo = Foo; + let loan = foo.mutate_and_share(); + foo.share(); +} +``` + +One might expect it to compile. We call `mutate_and_share`, which mutably borrows +`foo` *temporarily*, but then returns *only* a shared reference. Therefore we +would expect `foo.share()` to succeed as `foo` shouldn't be mutably borrowed. + +However when we try to compile it: + +```text +:11:5: 11:8 error: cannot borrow `foo` as immutable because it is also borrowed as mutable +:11 foo.share(); + ^~~ +:10:16: 10:19 note: previous borrow of `foo` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `foo` until the borrow ends +:10 let loan = foo.mutate_and_share(); + ^~~ +:12:2: 12:2 note: previous borrow ends here +:8 fn main() { +:9 let mut foo = Foo; +:10 let loan = foo.mutate_and_share(); +:11 foo.share(); +:12 } + ^ ``` -One would expect the output of foo to be an immutable lifetime. However we have -derived it from the input, which is a mutable lifetime. So although we have a -shared reference, it will have the much more limited aliasing rules of a mutable -reference. As a consequence, there is no expressive benefit in a method that -mutates returning a shared reference. +What happened? Well, the lifetime of `loan` is derived from a *mutable* borrow. +This makes the type system believe that `foo` is mutably borrowed as long as +`loan` exists, even though it's a shared reference. To my knowledge, this is not +a bug. @@ -413,7 +450,7 @@ respectively. -## PhantomData and PhantomFn +## PhantomData This is all well and good for the types the standard library provides, but how is variance determined for type that *you* define? A struct is, informally @@ -475,6 +512,8 @@ pub struct Iter<'a, T: 'a> { ``` + + ## Splitting Lifetimes The mutual exclusion property of mutable references can be very limiting when @@ -544,7 +583,76 @@ fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { ``` This is pretty plainly dangerous. We use transmute to duplicate the slice with an -*unbounded* lifetime, so that it +*unbounded* lifetime, so that it can be treated as disjoint from the other until +we unify them when we return. + +However more subtle is how iterators that yield mutable references work. +The iterator trait is defined as follows: + +```rust +trait Iterator { + type Item; + + fn next(&mut self) -> Option; +} +``` + +Given this definition, Self::Item has *no* connection to `self`. This means +that we can call `next` several times in a row, and hold onto all the results +*concurrently*. This is perfectly fine for by-value iterators, which have exactly +these semantics. It's also actually fine for shared references, as it's perfectly +fine to grab a huge pile of shared references to the same thing (although the +iterator needs to be a separate object from the thing being shared). But mutable +references make this a mess. At first glance, they might seem completely +incompatible with this API, as it would produce multiple mutable references to +the same object! + +However it actually *does* work, exactly because iterators are one-shot objects. +Everything an IterMut yields will be yielded *at most* once, so we don't *actually* +ever yield multiple mutable references to the same piece of data. + +In general all mutable iterators require *some* unsafe code *somewhere*, though. +Whether it's raw pointers, or safely composing on top of *another* IterMut. + +For instance, VecDeque's IterMut: + +```rust +pub struct IterMut<'a, T:'a> { + // The whole backing array. Some of these indices are initialized! + ring: &'a mut [T], + tail: usize, + head: usize, +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option<&'a mut T> { + if self.tail == self.head { + return None; + } + let tail = self.tail; + self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); + + unsafe { + // might as well do unchecked indexing since wrap_index has us + // in-bounds, and many of the "middle" indices are uninitialized + // anyway. + let elem = self.ring.get_unchecked_mut(tail); + + // round-trip through a raw pointer to unbound the lifetime from + // ourselves + Some(&mut *(elem as *mut _)) + } + } +} +``` +A very subtle but interesting detail in this design is that it *relies on +privacy to be sound*. Borrowck works on some very simple rules. One of those rules +is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut +Bar is *also* live. Since IterMut is always live when `next` can be called, if +`ring` were public then we could mutate `ring` while outstanding mutable borrows +to it exist! From c3c9d9140530a9709449fd32e830bf88f567845c Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 14:51:27 -0700 Subject: [PATCH 010/104] progress --- lifetimes.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/lifetimes.md b/lifetimes.md index 84bc7e2ef5947..02e307d57fc6d 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -447,15 +447,9 @@ The variance of `*const` and `*mut` is basically arbitrary as they're not at all type or memory safe, so their variance is determined in analogy to & and &mut respectively. - - - -## PhantomData - This is all well and good for the types the standard library provides, but -how is variance determined for type that *you* define? A struct is, informally -speaking, covariant over all its fields (and an enum over its variants). This -basically means that it inherits the variance of its fields. If a struct `Foo` +how is variance determined for type that *you* define? A struct informally +speaking inherits the variance of its fields. If a struct `Foo` has a generic argument `A` that is used in a field `a`, then Foo's variance over `A` is exactly `a`'s variance. However this is complicated if `A` is used in multiple fields. @@ -478,6 +472,17 @@ struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { } ``` + + + +## Dropck + +TODO + + +## PhantomData + + However when working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` @@ -511,6 +516,8 @@ pub struct Iter<'a, T: 'a> { } ``` +However PhantomData is also necessary to signal important information to +*dropck*. (TODO) From fabbd4e8630ca1087fb69dca978ab7916d2d1adf Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 15:41:39 -0700 Subject: [PATCH 011/104] progress --- lifetimes.md | 58 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 11 deletions(-) diff --git a/lifetimes.md b/lifetimes.md index 02e307d57fc6d..159a3b00074f1 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -474,16 +474,9 @@ struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { - -## Dropck - -TODO - - ## PhantomData - -However when working with unsafe code, we can often end up in a situation where +When working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` for `&'a [T]` is (approximately) defined as follows: @@ -498,7 +491,8 @@ pub struct Iter<'a, T: 'a> { However because `'a` is unused within the struct's body, it's *unbound*. Because of the troubles this has historically caused, unbound lifetimes and types are *illegal* in struct definitions. Therefore we must somehow refer -to these types in the body. +to these types in the body. Correctly doing this is necessary to have +correct variance and drop checking. We do this using *PhantomData*, which is a special marker type. PhantomData consumes no space, but simulates a field of the given type for the purpose of @@ -516,8 +510,50 @@ pub struct Iter<'a, T: 'a> { } ``` -However PhantomData is also necessary to signal important information to -*dropck*. (TODO) + + + +## Dropck + +When a type is going out of scope, Rust will try to Drop it. Drop executes +arbitrary code, and in fact allows us to "smuggle" arbitrary code execution +into many places. As such additional soundness checks (dropck) are necessary to +ensure that a type T can be safely instantiated and dropped. It turns out that we +*really* don't need to care about dropck in practice, as it often "just works". + +However the one exception is with PhantomData. Given a struct like Vec: + +``` +struct Vec { + data: *const T, // *const for covariance! + len: usize, + cap: usize, +} +``` + +dropck will generously determine that Vec does not contain any values of +type T. This will unfortunately allow people to construct unsound Drop +implementations that access data that has already been dropped. In order to +tell dropck that we *do* own values of type T and may call destructors of that +type, we must add extra PhantomData: + +``` +struct Vec { + data: *const T, // *const for covariance! + len: usize, + cap: usize, + _marker: marker::PhantomData, +} +``` + +Raw pointers that own an allocation is such a pervasive pattern that the +standard library made a utility for itself called `Unique` which: + +* wraps a `*const T`, +* includes a PhantomData, +* auto-derives Send/Sync as if T was contained +* marks the pointer as NonZero for the null-pointer optimization + From cb4f081b5e8278e0445ae67320fb80d274cd8e11 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 15:42:30 -0700 Subject: [PATCH 012/104] remove ffi and no_std, TRPL's got it --- ffi.md | 45 --------------------------------------------- intro.md | 2 -- no_std.md | 2 -- 3 files changed, 49 deletions(-) delete mode 100644 ffi.md delete mode 100644 no_std.md diff --git a/ffi.md b/ffi.md deleted file mode 100644 index 668befb4bf5fb..0000000000000 --- a/ffi.md +++ /dev/null @@ -1,45 +0,0 @@ -% Interfacing with other Languages (FFI) - -*Obviously* we'd all love to live in a **glorious** world where everything is -written in Rust, Rust, and More Rust. Tragically, programs have been written -in Not Rust for over 50 years. Crufty enterprises are doomed to -support ancient code bases, and greybeard programmers stuck in their ways -*insist* on writing programs in other languages, even to this day! - -In all seriousness, there's a myriad of reasons for your codebase to be a -hybrid of different languages, and Rust is well-designed to interface with -all of them as painlessly as possible. It does this through the tried and -true strategy of all languages: pretend to be C, and understand C. - -Thanks to Rust's minimal runtime and C-like semantics, this is about as -painless as FFI with C++. Obviously, most of Rust's features are completely -incompatible with other languages: tagged unions, zero-sized-types, dynamically- -sized types, destructors, methods, traits, references, and lifetimes are all -concepts that you won't be able to expose or accept in your foreign function -interface. - -All mapping through C will give you is functions, structs, globals, raw pointers, -and C-like enums. That's it. Rust's default data layouts are also incompatible -with the C layout. See [the section on data layout][data.html] for details. -Long story short: mark FFI structs and enums with `#[repr(C)]`, mark FFI -functions as `extern`. - -## Runtime - -Rust's runtime is sufficiently minimal that it requires *no* special handling. -You don't need to set anything up. You don't need to tear anything down. -Awesome. - -The only runtime detail you *really* need to worry about is unwinding. Rust's -unwinding model is not defined to be incompatible with any particular language. -That means that if you call Rust from another language and it unwinds into the -calling language, this will cause Undefined Behaviour. Similarly, if another -language unwinds into Rust, it will also cause Undefined Behaviour. - -Rust can't really do anything about other languages unwinding into it (FFI is unsafe -for a reason!), but you can be a good FFI citizen by catching panics in any -FFI functions you export. Rust provides `thread::catch_panic` for exactly this. -Unfortunately, this API is still unstable. - -## libc - diff --git a/intro.md b/intro.md index cb644c515f2ed..12b105db80677 100644 --- a/intro.md +++ b/intro.md @@ -15,8 +15,6 @@ stack or heap, we will not explain the syntax. * [Uninitialized Memory](uninitialized.html) * [Ownership-oriented resource management (RAII)](raii.html) * [Concurrency](concurrency.html) -* [Interfacing with other languages (FFI)](ffi.html) -* [Eliminating the Runtime (no_std)](no_std.html) ## A Tale Of Two Languages diff --git a/no_std.md b/no_std.md deleted file mode 100644 index 8da5b78cadb40..0000000000000 --- a/no_std.md +++ /dev/null @@ -1,2 +0,0 @@ -% Eliminating the Runtime (no_std) - From 7d41c950c4e73dee4d5b44022186aa65e4323375 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 15:45:49 -0700 Subject: [PATCH 013/104] fix data headers --- data.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/data.md b/data.md index 6fa63568862c5..9189209db5ee9 100644 --- a/data.md +++ b/data.md @@ -4,7 +4,7 @@ Low-level programming cares a lot about data layout. It's a big deal. It also pe influences the rest of the language, so we're going to start by digging into how data is represented in Rust. -# The `rust` repr +## The rust repr Rust gives you the following ways to lay out composite data: @@ -124,7 +124,7 @@ In principle enums can use fairly elaborate algorithms to cache bits throughout with special constrained representations. As such it is *especially* desirable that we leave enum layout unspecified today. -# Dynamically Sized Types (DSTs) +## Dynamically Sized Types (DSTs) Rust also supports types without a statically known size. On the surface, this is a bit nonsensical: Rust must know the size of something in order to @@ -212,12 +212,12 @@ struct Foo { For details as to *why* this is done, and how to make it not happen, check out [SOME OTHER SECTION]. -# Alternative representations +## Alternative representations Rust allows you to specify alternative data layout strategies from the default Rust one. -# repr(C) +### repr(C) This is the most important `repr`. It has fairly simple intent: do what C does. The order, size, and alignment of fields is exactly what you would expect from @@ -241,14 +241,14 @@ still consumes a byte of space. * This is equivalent to repr(u32) for enums (see below) -# repr(packed) +### repr(packed) `repr(packed)` forces rust to strip any padding it would normally apply. This may improve the memory footprint of a type, but will have negative side-effects from "field access is heavily penalized" to "completely breaks everything" based on target platform. -# repr(u8), repr(u16), repr(u32), repr(u64) +### repr(u8), repr(u16), repr(u32), repr(u64) These specify the size to make a c-like enum (one which has no values in its variants). From edb29ec53db18b8f119154a1b51009f35eeeeeb2 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 19 Jun 2015 15:52:21 -0700 Subject: [PATCH 014/104] futz with headers more --- concurrency.md | 27 ++++++++++++++------------- data.md | 30 ++++++++++++++++++++++++------ intro.md | 15 ++++++++++++--- lifetimes.md | 20 ++++++++++---------- raii.md | 2 +- 5 files changed, 61 insertions(+), 33 deletions(-) diff --git a/concurrency.md b/concurrency.md index c600644ba63e4..a382e4edf54cf 100644 --- a/concurrency.md +++ b/concurrency.md @@ -1,16 +1,8 @@ % Concurrency and Paralellism -```Not sure if I want this -Safe Rust features *a ton* of tooling to make concurrency and parallelism totally -safe, easy, and fearless. This is a case where we'll really just -[defer to TRPL][trpl-conc] for the basics. - -TL;DR: The `Send` and `Sync` traits in conjunction with Rust's ownership model and -normal generic bounds make using concurrent APIs really easy and painless for -a user of Safe Rust. -``` -## Data Races and Race Conditions + +# Data Races and Race Conditions Safe Rust guarantees an absence of data races, which are defined as: @@ -77,7 +69,10 @@ if idx.load(Ordering::SeqCst) < data.len() { } ``` -## Send and Sync + + + +# Send and Sync Not everything obeys inherited mutability, though. Some types allow you to multiply alias a location in memory while mutating it. Unless these types use synchronization @@ -153,7 +148,10 @@ into the collection. TODO: better explain what can or can't be Send or Sync. Sufficient to appeal only to data races? -## Atomics + + + +# Atomics Rust pretty blatantly just inherits LLVM's model for atomics, which in turn is largely based off of the C11 model for atomics. This is not due these models @@ -165,7 +163,10 @@ least, we can benefit from existing tooling and research around C's model. Trying to fully explain these models is fairly hopeless, so we're just going to drop that problem in LLVM's lap. -## Actually Doing Things Concurrently + + + +# Actually Doing Things Concurrently Rust as a language doesn't *really* have an opinion on how to do concurrency or parallelism. The standard library exposes OS threads and blocking sys-calls diff --git a/data.md b/data.md index 9189209db5ee9..110084824cfef 100644 --- a/data.md +++ b/data.md @@ -4,7 +4,10 @@ Low-level programming cares a lot about data layout. It's a big deal. It also pe influences the rest of the language, so we're going to start by digging into how data is represented in Rust. -## The rust repr + + + +# The rust repr Rust gives you the following ways to lay out composite data: @@ -124,7 +127,7 @@ In principle enums can use fairly elaborate algorithms to cache bits throughout with special constrained representations. As such it is *especially* desirable that we leave enum layout unspecified today. -## Dynamically Sized Types (DSTs) +# Dynamically Sized Types (DSTs) Rust also supports types without a statically known size. On the surface, this is a bit nonsensical: Rust must know the size of something in order to @@ -150,6 +153,9 @@ struct Foo { } ``` + + + # Zero Sized Types (ZSTs) Rust actually allows types to be specified that occupy *no* space: @@ -182,6 +188,9 @@ consequence of types with no size. In particular, pointer offsets are no-ops, an standard allocators (including jemalloc, the one used by Rust) generally consider passing in `0` as Undefined Behaviour. + + + # Drop Flags For unfortunate legacy implementation reasons, Rust as of 1.0.0 will do a nasty trick to @@ -212,12 +221,17 @@ struct Foo { For details as to *why* this is done, and how to make it not happen, check out [SOME OTHER SECTION]. -## Alternative representations + + + +# Alternative representations Rust allows you to specify alternative data layout strategies from the default Rust one. -### repr(C) + + +## repr(C) This is the most important `repr`. It has fairly simple intent: do what C does. The order, size, and alignment of fields is exactly what you would expect from @@ -241,14 +255,18 @@ still consumes a byte of space. * This is equivalent to repr(u32) for enums (see below) -### repr(packed) + + +## repr(packed) `repr(packed)` forces rust to strip any padding it would normally apply. This may improve the memory footprint of a type, but will have negative side-effects from "field access is heavily penalized" to "completely breaks everything" based on target platform. -### repr(u8), repr(u16), repr(u32), repr(u64) + + +## repr(u8), repr(u16), repr(u32), repr(u64) These specify the size to make a c-like enum (one which has no values in its variants). diff --git a/intro.md b/intro.md index 12b105db80677..7d3036fe5ec42 100644 --- a/intro.md +++ b/intro.md @@ -7,7 +7,10 @@ Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know the basics of the language and systems programming. We will not explain the stack or heap, we will not explain the syntax. -## Sections + + + +# Sections * [Data Layout](data.html) * [Ownership and Lifetimes](lifetimes.html) @@ -16,7 +19,10 @@ stack or heap, we will not explain the syntax. * [Ownership-oriented resource management (RAII)](raii.html) * [Concurrency](concurrency.html) -## A Tale Of Two Languages + + + +# A Tale Of Two Languages Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. Any time someone opines the guarantees of Rust, they are almost surely talking about @@ -60,7 +66,10 @@ The fact that Rust is written with a healthy spoonful of Unsafe Rust is no diffe However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of C to do the nasty things that need to get done. -## What does `unsafe` mean? + + + +# What does `unsafe` mean? Rust tries to model memory safety through the `unsafe` keyword. Interestingly, the meaning of `unsafe` largely revolves around what diff --git a/lifetimes.md b/lifetimes.md index 159a3b00074f1..4be895ff429b5 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -7,7 +7,7 @@ language-design problem. -## The Tagged Union Problem +# The Tagged Union Problem The core of the lifetime and mutability system derives from a simple problem: internal pointers to tagged unions. For instance, consider the following code: @@ -68,7 +68,7 @@ For more details see Dan Grossman's Existential Types for Imperative Languages: -## Lifetimes +# Lifetimes Rust's static checks are managed by the *borrow checker* (borrowck), which tracks mutability and outstanding loans. This analysis can in principle be done without @@ -101,7 +101,7 @@ more than a local lint against incorrect usage of a value. -## Weird Lifetimes +# Weird Lifetimes Given the following code: @@ -150,7 +150,7 @@ a bug. -## Lifetime Elision +# Lifetime Elision In order to make common patterns more ergonomic, Rust allows lifetimes to be *elided* in function, impl, and type signatures. @@ -217,7 +217,7 @@ fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded -## Unbounded Lifetimes +# Unbounded Lifetimes Unsafe code can often end up producing references or lifetimes out of thin air. Such lifetimes come into the world as *unbounded*. The most common source of this @@ -258,7 +258,7 @@ these are unstable due to their awkward nature and questionable utility. -## Higher-Rank Lifetimes +# Higher-Rank Lifetimes Generics in Rust generally allow types to be instantiated with arbitrary associated lifetimes, but this fixes the lifetimes they work with once @@ -328,7 +328,7 @@ maximally useful outside of the Fn traits. -## Subtyping and Variance +# Subtyping and Variance Although Rust doesn't have any notion of inheritance, it *does* include subtyping. In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are derived @@ -474,7 +474,7 @@ struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { -## PhantomData +# PhantomData When working with unsafe code, we can often end up in a situation where types or lifetimes are logically associated with a struct, but not actually @@ -513,7 +513,7 @@ pub struct Iter<'a, T: 'a> { -## Dropck +# Dropck When a type is going out of scope, Rust will try to Drop it. Drop executes arbitrary code, and in fact allows us to "smuggle" arbitrary code execution @@ -557,7 +557,7 @@ standard library made a utility for itself called `Unique` which: -## Splitting Lifetimes +# Splitting Lifetimes The mutual exclusion property of mutable references can be very limiting when working with a composite structure. Borrowck understands some basic stuff, but diff --git a/raii.md b/raii.md index 13a2bdf8fff7c..76363030b8481 100644 --- a/raii.md +++ b/raii.md @@ -176,4 +176,4 @@ 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 +[uninit]: uninitialized.html \ No newline at end of file From 8f531d9d7e058222cb13a9987a80431906d524b9 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sat, 20 Jun 2015 14:34:17 -0700 Subject: [PATCH 015/104] progress --- README.md | 4 +- conversions.md | 205 ++++++++++++++++++++++++++++----- intro.md | 164 +++++++++++++++++++++----- raii.md | 305 ++++++++++++++++++++++++++++++++++++++++++++----- 4 files changed, 593 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 4227beb19de14..e391c9a48ea3c 100644 --- a/README.md +++ b/README.md @@ -1 +1,3 @@ -# turpl +# The Unsafe Rust Programming Language (Book) + +[Start at the intro](http://www.cglab.ca/~abeinges/blah/turpl/intro.html) \ No newline at end of file diff --git a/conversions.md b/conversions.md index 4fe86284a31ef..ae3ce9e312552 100644 --- a/conversions.md +++ b/conversions.md @@ -5,8 +5,6 @@ are just there to help us use those bits right. Needing to reinterpret those pil of bits as different types is a common problem and Rust consequently gives you several ways to do that. -# Safe Rust - First we'll look at the ways that *Safe Rust* gives you to reinterpret values. The most trivial way to do this is to just destructure a value into its constituent parts and then build a new type out of them. e.g. @@ -31,42 +29,191 @@ fn reinterpret(foo: Foo) -> Bar { But this is, at best, annoying to do. For common conversions, rust provides more ergonomic alternatives. -## Auto-Deref + + + +# Auto-Deref + +(Maybe nix this in favour of receiver coercions) Deref is a trait that allows you to overload the unary `*` to specify a type you dereference to. This is largely only intended to be implemented by pointer types like `&`, `Box`, and `Rc`. The dot operator will automatically perform -automatic dereferencing, so that foo.bar() will work uniformly on `Foo`, `&Foo`, `&&Foo`, -`&Rc>>` and so-on. Search bottoms out on the *first* match, +automatic dereferencing, so that foo.bar() will work uniformly on `Foo`, `&Foo`, ` +&&Foo`, `&Rc>>` and so-on. Search bottoms out on the *first* match, so implementing methods on pointers is generally to be avoided, as it will shadow "actual" methods. -## Coercions -Types can implicitly be coerced to change in certain contexts. These changes are generally -just *weakening* of types, largely focused around pointers. They mostly exist to make -Rust "just work" in more cases. For instance -`&mut T` coerces to `&T`, and `&T` coerces to `*const T`. The most useful coercion you will -actually think about it is probably the general *Deref Coercion*: `&T` coerces to `&U` when -`T: Deref`. This enables us to pass an `&String` where an `&str` is expected, for instance. -## Casts -Casts are a superset of coercions: every coercion can be explicitly invoked via a cast, -but some changes require a cast. These "true casts" are generally regarded as dangerous or -problematic actions. True casts revolves around raw pointers and the primitive numeric -types. Here's an exhaustive list of all the true casts: +# Coercions + +Types can implicitly be coerced to change in certain contexts. These changes are +generally just *weakening* of types, largely focused around pointers and lifetimes. +They mostly exist to make Rust "just work" in more cases, and are largely harmless. + +Here's all the kinds of coercion: + + +Coercion is allowed between the following types: + +* `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) + of `U` (the 'identity' case); + +* `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` + (transitivity case); + +* `&mut T` to `&T`; + +* `*mut T` to `*const T`; + +* `&T` to `*const T`; + +* `&mut T` to `*mut T`; + +* `T` to `U` if `T` implements `CoerceUnsized` (see below) and `T = Foo<...>` + and `U = Foo<...>`; + +* From TyCtor(`T`) to TyCtor(coerce_inner(`T`)); + +where TyCtor(`T`) is one of `&T`, `&mut T`, `*const T`, `*mut T`, or `Box`. +And where coerce_inner is defined as + +* coerce_inner(`[T, ..n]`) = `[T]`; + +* coerce_inner(`T`) = `U` where `T` is a concrete type which implements the + trait `U`; + +* coerce_inner(`T`) = `U` where `T` is a sub-trait of `U`; + +* coerce_inner(`Foo<..., T, ...>`) = `Foo<..., coerce_inner(T), ...>` where + `Foo` is a struct and only the last field has type `T` and `T` is not part of + the type of any other fields; + +* coerce_inner(`(..., T)`) = `(..., coerce_inner(T))`. + +Coercions only occur at a *coercion site*. Exhaustively, the coercion sites +are: + +* In `let` statements where an explicit type is given: in `let _: U = e;`, `e` + is coerced to to have type `U`; + +* In statics and consts, similarly to `let` statements; + +* In argument position for function calls. The value being coerced is the actual + parameter and it is coerced to the type of the formal parameter. For example, + where `foo` is defined as `fn foo(x: U) { ... }` and is called with `foo(e);`, + `e` is coerced to have type `U`; + +* Where a field of a struct or variant is instantiated. E.g., where `struct Foo + { x: U }` and the instantiation is `Foo { x: e }`, `e` is coerced to to have + type `U`; + +* The result of a function, either the final line of a block if it is not semi- + colon terminated or any expression in a `return` statement. For example, for + `fn foo() -> U { e }`, `e` is coerced to to have type `U`; -TODO: gank the RFC for sweet casts +If the expression in one of these coercion sites is a coercion-propagating +expression, then the relevant sub-expressions in that expression are also +coercion sites. Propagation recurses from these new coercion sites. Propagating +expressions and their relevant sub-expressions are: -For number -> number casts, there are quite a few cases to consider: +* array literals, where the array has type `[U, ..n]`, each sub-expression in + the array literal is a coercion site for coercion to type `U`; + +* array literals with repeating syntax, where the array has type `[U, ..n]`, the + repeated sub-expression is a coercion site for coercion to type `U`; + +* tuples, where a tuple is a coercion site to type `(U_0, U_1, ..., U_n)`, each + sub-expression is a coercion site for the respective type, e.g., the zero-th + sub-expression is a coercion site to `U_0`; + +* the box expression, if the expression has type `Box`, the sub-expression is + a coercion site to `U`; + +* parenthesised sub-expressions (`(e)`), if the expression has type `U`, then + the sub-expression is a coercion site to `U`; + +* blocks, if a block has type `U`, then the last expression in the block (if it + is not semicolon-terminated) is a coercion site to `U`. This includes blocks + which are part of control flow statements, such as `if`/`else`, if the block + has a known type. + + +Note that we do not perform coercions when matching traits (except for +receivers, see below). If there is an impl for some type `U` and `T` coerces to +`U`, that does not constitute an implementation for `T`. For example, the +following will not type check, even though it is OK to coerce `t` to `&T` and +there is an impl for `&T`: + +``` +struct T; +trait Trait {} + +fn foo(t: X) {} + +impl<'a> Trait for &'a T {} + + +fn main() { + let t: &mut T = &mut T; + foo(t); //~ ERROR failed to find an implementation of trait Trait for &mut T +} +``` + +In a cast expression, `e as U`, the compiler will first attempt to coerce `e` to +`U`, only if that fails will the conversion rules for casts (see below) be +applied. + + + + +# Casts + +Casts are a superset of coercions: every coercion can be explicitly invoked via a +cast, but some conversions *require* a cast. These "true casts" are generally regarded +as dangerous or problematic actions. True casts revolve around raw pointers and +the primitive numeric types. True casts aren't checked. + +Here's an exhaustive list of all the true casts: + + * `e` has type `T` and `T` coerces to `U`; *coercion-cast* + * `e` has type `*T`, `U` is `*U_0`, and either `U_0: Sized` or + unsize_kind(`T`) = unsize_kind(`U_0`); *ptr-ptr-cast* + * `e` has type `*T` and `U` is a numeric type, while `T: Sized`; *ptr-addr-cast* + * `e` is an integer and `U` is `*U_0`, while `U_0: Sized`; *addr-ptr-cast* + * `e` has type `T` and `T` and `U` are any numeric types; *numeric-cast* + * `e` is a C-like enum and `U` is an integer type; *enum-cast* + * `e` has type `bool` or `char` and `U` is an integer; *prim-int-cast* + * `e` has type `u8` and `U` is `char`; *u8-char-cast* + * `e` has type `&[T; n]` and `U` is `*const T`; *array-ptr-cast* + * `e` is a function pointer type and `U` has type `*T`, + while `T: Sized`; *fptr-ptr-cast* + * `e` is a function pointer type and `U` is an integer; *fptr-addr-cast* + +where `&.T` and `*T` are references of either mutability, +and where unsize_kind(`T`) is the kind of the unsize info +in `T` - the vtable for a trait definition (e.g. `fmt::Display` or +`Iterator`, not `Iterator`) or a length (or `()` if `T: Sized`). + +Note that lengths are not adjusted when casting raw slices - +`T: *const [u16] as *const [u8]` creates a slice that only includes +half of the original memory. + +Casting is not transitive, that is, even if `e as U1 as U2` is a valid +expression, `e as U2` is not necessarily so (in fact it will only be valid if +`U1` coerces to `U2`). + +For numeric casts, there are quite a few cases to consider: * casting between two integers of the same size (e.g. i32 -> u32) is a no-op * casting from a smaller integer to a bigger integer (e.g. u32 -> u8) will truncate * casting from a larger integer to a smaller integer (e.g. u8 -> u32) will - * zero-extend if unsigned - * sign-extend if signed -* casting from a float to an integer will round the float towards zero. + * zero-extend if the target is unsigned + * sign-extend if the target is signed +* casting from a float to an integer will: + * round the float towards zero if finite * **NOTE: currently this will cause Undefined Behaviour if the rounded value cannot be represented by the target integer type**. This is a bug and will be fixed. @@ -86,18 +233,14 @@ well as interpret integers as addresses. However it is impossible to actually `unsafe`. -## Conversion Traits -For full formal specification of all the kinds of coercions and coercion sites, see: -https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md + +# Conversion Traits + +TODO -* Coercions -* Casts -* Conversion Traits (Into/As/...) -# Unsafe Rust +# Transmuting Types -* raw ptr casts -* mem::transmute diff --git a/intro.md b/intro.md index 7d3036fe5ec42..b955d78bd38ba 100644 --- a/intro.md +++ b/intro.md @@ -1,6 +1,11 @@ % The Unsafe Rust Programming Language -This document seeks to complement [The Rust Programming Language][] (TRPL). +**This document is about advanced functionality and low-level development practices +in the Rust Programming Language. Most of the things discussed won't matter +to the average Rust programmer. However if you wish to correctly write unsafe +code in Rust, this text contains invaluable information.** + +This document seeks to complement [The Rust Programming Language Book][] (TRPL). Where TRPL introduces the language and teaches the basics, TURPL dives deep into the specification of the language, and all the nasty bits necessary to write Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know @@ -10,7 +15,7 @@ stack or heap, we will not explain the syntax. -# Sections +# Chapters * [Data Layout](data.html) * [Ownership and Lifetimes](lifetimes.html) @@ -48,7 +53,6 @@ Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a action. In deciding to work with unchecked uninitialized memory, this does not suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, one does not have to suddenly worry about indexing out of bounds on `y`. - C and C++, by contrast, have pervasive unsafety baked into the language. Even the modern best practices like `unique_ptr` have various safety pitfalls. @@ -85,17 +89,19 @@ To be more concrete, Rust cares about preventing the following things: * Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell) * Invoking Undefined Behaviour (in e.g. compiler intrinsics) * Producing invalid primitive values: - * dangling/null references - * a `bool` that isn't 0 or 1 - * an undefined `enum` discriminant - * a `char` larger than char::MAX - * A non-utf8 `str` + * dangling/null references + * a `bool` that isn't 0 or 1 + * an undefined `enum` discriminant + * a `char` larger than char::MAX + * A non-utf8 `str` * Unwinding into an FFI function * Causing a data race -However libraries are free to declare arbitrary requirements if they could transitively -cause memory safety issues. However Rust is otherwise quite permisive with respect to -other dubious operations. Rust considers it "safe" to: +That's it. That's all the Undefined Behaviour in Rust. Libraries are free to +declare arbitrary requirements if they could transitively cause memory safety +issues, but it all boils down to the above actions. Rust is otherwise +quite permisive with respect to other dubious operations. Rust considers it +"safe" to: * Deadlock * Leak memory @@ -106,27 +112,27 @@ other dubious operations. Rust considers it "safe" to: However any program that does such a thing is *probably* incorrect. Rust just isn't interested in modeling these problems, as they are much harder to prevent in general, -and it's basically impossible to prevent incorrect programs from getting written. +and it's literally impossible to prevent incorrect programs from getting written. -Their are several places `unsafe` can appear in Rust today, which can largely be +There are several places `unsafe` can appear in Rust today, which can largely be grouped into two categories: * There are unchecked contracts here. To declare you understand this, I require you to write `unsafe` elsewhere: * On functions, `unsafe` is declaring the function to be unsafe to call. Users - of the function must check the documentation to determine what this means, - and then have to write `unsafe` somewhere to identify that they're aware of + of the function must check the documentation to determine what this means, + and then have to write `unsafe` somewhere to identify that they're aware of the danger. * On trait declarations, `unsafe` is declaring that *implementing* the trait - is an unsafe operation, as it has contracts that other unsafe code is free to - trust blindly. + is an unsafe operation, as it has contracts that other unsafe code is free to + trust blindly. * I am declaring that I have, to the best of my knowledge, adhered to the unchecked contracts: * On trait implementations, `unsafe` is declaring that the contract of the - `unsafe` trait has been upheld. + `unsafe` trait has been upheld. * On blocks, `unsafe` is declaring any unsafety from an unsafe - operation to be handled, and therefore the parent function is safe. + operation within to be handled, and therefore the parent function is safe. There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for historical reasons and is in the process of being phased out. See the section on @@ -135,21 +141,21 @@ destructors for details. Some examples of unsafe functions: * `slice::get_unchecked` will perform unchecked indexing, allowing memory -safety to be freely violated. + safety to be freely violated. * `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is -not "in bounds" as defined by LLVM (see the lifetimes section for details). + not "in bounds" as defined by LLVM (see the lifetimes section for details). * `mem::transmute` reinterprets some value as having the given type, -bypassing type safety in arbitrary ways. (see the conversions section for details) + bypassing type safety in arbitrary ways. (see the conversions section for details) * All FFI functions are `unsafe` because they can do arbitrary things. -C being an obvious culprit, but generally any language can do something -that Rust isn't happy about. (see the FFI section for details) + C being an obvious culprit, but generally any language can do something + that Rust isn't happy about. (see the FFI section for details) As of Rust 1.0 there are exactly two unsafe traits: * `Send` is a marker trait (it has no actual API) that promises implementors -are safe to send to another thread. + are safe to send to another thread. * `Sync` is a marker trait that promises that threads can safely share -implementors through a shared reference. + implementors through a shared reference. All other traits that declare any kind of contract *really* can't be trusted to adhere to their contract when memory-safety is at stake. For instance Rust has @@ -167,3 +173,109 @@ thread safety is a sort of fundamental thing that a program can't really guard against locally (even by-value message passing still requires a notion Send). + + +# Working with unsafe + +Rust generally only gives us the tools to talk about safety in a scoped and +binary manner. Unfortunately reality is significantly more complicated than that. +For instance, consider the following toy function: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx < arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +Clearly, this function is safe. We check that the index is in bounds, and if it +is, index into the array in an unchecked manner. But even in such a trivial +function, the scope of the unsafe block is questionable. Consider changing the +`<` to a `<=`: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx <= arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +This program is now unsound, an yet *we only modified safe code*. This is the +fundamental problem of safety: it's non-local. The soundness of our unsafe +operations necessarily depends on the state established by "safe" operations. +Although safety *is* modular (we *still* don't need to worry about about +unrelated safety issues like uninitialized memory), it quickly contaminates the +surrounding code. + +Trickier than that is when we get into actual statefulness. Consider a simple +implementation of `Vec`: + +```rust +// Note this defintion is insufficient. See the section on lifetimes. +struct Vec { + ptr: *mut T, + len: usize, + cap: usize, +} + +// Note this implementation does not correctly handle zero-sized types. +// We currently live in a nice imaginary world of only postive fixed-size +// types. +impl Vec { + fn new() -> Self { + Vec { ptr: heap::EMPTY, len: 0, cap: 0 } + } + + fn push(&mut self, elem: T) { + if self.len == self.cap { + // not important for this example + self.reallocate(); + } + unsafe { + ptr::write(self.ptr.offset(len as isize), elem); + self.len += 1; + } + } + + fn pop(&mut self) -> Option { + if self.len > 0 { + self.len -= 1; + unsafe { + Some(ptr::read(self.ptr.offset(self.len as isize))) + } + } else { + None + } + } +} +``` + +This code is simple enough to reasonably audit and verify. Now consider +adding the following method: + +```rust + fn make_room(&mut self) { + // grow the capacity + self.cap += 1; + } +``` + +This code is safe, but it is also completely unsound. Changing the capacity +violates the invariants of Vec (that `cap` reflects the allocated space in the +Vec). This is not something the rest of `Vec` can guard against. It *has* to +trust the capacity field because there's no way to verify it. + +`unsafe` does more than pollute a whole function: it pollutes a whole *module*. +Generally, the only bullet-proof way to limit the scope of unsafe code is at the +module boundary with privacy. + diff --git a/raii.md b/raii.md index 76363030b8481..679c1dd3d5993 100644 --- a/raii.md +++ b/raii.md @@ -13,7 +13,12 @@ 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 + + + +# Constructors + +Unlike C++, Rust does not come with a slew of 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. @@ -25,20 +30,26 @@ 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 +moral equivalent of a 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 +implementation is just "copy the bits". Copy types *are* implicitly 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. +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). +aren't implicitly 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. +In concrete contexts, 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. + + + + + +# Destructors What the language *does* provide is full-blown automatic destructors through the `Drop` trait, which provides the following method: @@ -49,12 +60,19 @@ 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). +convenience feature so that you don't have to write "destructor boilerplate" to drop +children. If a struct has no special logic for being dropped other than dropping its +children, then it means `Drop` doesn't need to be implemented at all! + +**There is no way to prevent this behaviour in Rust 1.0**. + +Note that taking `&mut self` means that even if you *could* suppress 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 (they don't contain pointers to elsewhere). +* There's no additional state passed into drop to try to send things. +* `self` is about to be marked as uninitialized (and therefore inaccessible). For instance, a custom implementation of `Box` might write `Drop` like this: @@ -73,7 +91,7 @@ impl Drop for Box { 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. +the Box is immediately marked as uninitialized. However this wouldn't work: @@ -130,14 +148,14 @@ enum Link { } ``` -will have its inner Box field dropped *if and only if* a value stores the Next variant. +will have its inner Box field dropped *if and only if* an instance 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 +drops 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: +The classic safe solution to overriding recursive drop and allowing moving out +of Self during `drop` is to use an Option: ```rust struct Box{ ptr: *mut T } @@ -158,22 +176,255 @@ impl Drop for SuperBox { 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. + // field 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 +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 destructor. 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. +On balance this is an ok choice. Certainly what you should reach for by default. +However, in the future we expect there to be a first-class way to announce that +a field shouldn't be automatically dropped. + + + + +# Leaking + +Ownership based resource management is intended to simplify composition. You +acquire resources when you create the object, and you release the resources +when it gets destroyed. Since destruction is handled for you, it means you +can't forget to release the resources, and it happens as soon as possible! +Surely this is perfect and all of our problems are solved. + +Everything is terrible and we have new and exotic problems to try to solve. + +Many people like to believe that Rust eliminates resource leaks, but this +is absolutely not the case, no matter how you look at it. In the strictest +sense, "leaking" is so abstract as to be unpreventable. It's quite trivial +to initialize a collection at the start of a program, fill it with tons of +objects with destructors, and then enter an infinite event loop that never +refers to it. The collection will sit around uselessly, holding on to its +precious resources until the program terminates (at which point all those +resources would have been reclaimed by the OS anyway). + +We may consider a more restricted form of leak: failing to free memory that +is unreachable. Rust also doesn't prevent this. In fact Rust has a *function +for doing this*: `mem::forget`. This function consumes the value it is passed +*and then doesn't run its destructor*. + +In the past `mem::forget` was marked as unsafe as a sort of lint against using +it, since failing to call a destructor is generally not a well-behaved thing to +do (though useful for some special unsafe code). However this was generally +determined to be an untenable stance to take: there are *many* ways to fail to +call a destructor in safe code. The most famous example is creating a cycle +of reference counted pointers using interior mutability. + +It is reasonable for safe code to assume that destructor leaks do not happen, +as any program that leaks destructors is probably wrong. However *unsafe* code +cannot rely on destructors to be run to be *safe*. For most types this doesn't +matter: if you leak the destructor then the type is *by definition* inaccessible, +so it doesn't matter, right? e.g. if you leak a `Box` then you waste some +memory but that's hardly going to violate memory-safety. + +However where we must be careful with destructor leaks are *proxy* types. +These are types which manage access to a distinct object, but don't actually +own it. Proxy objects are quite rare. Proxy objects you'll need to care about +are even rarer. However we'll focus on two interesting examples in the +standard library: + +* `vec::Drain` +* `Rc` + + + + +## Drain + +`drain` is a collections API that moves data out of the container without +consuming the container. This enables us to reuse the allocation of a `Vec` +after claiming ownership over all of its contents. drain produces an iterator +(Drain) that returns the contents of the Vec by-value. + +Now, consider Drain in the middle of iteration: some values have been moved out, +and others haven't. This means that part of the Vec is now full of logically +uninitialized data! We could backshift all the elements in the Vec every time we +remove a value, but this would have pretty catastrophic performance consequences. + +Instead, we would like Drain to *fix* the Vec's backing storage when it is +dropped. It should run itself to completion, backshift any elements that weren't +removed (drain supports subranges), and then fix Vec's `len`. It's even +unwinding-safe! Easy! + +Now consider the following: + +``` +let mut vec = vec![Box::new(0); 4]; + +{ + // start draining, vec can no longer be accessed + let mut drainer = vec.drain(..); + + // pull out two elements and immediately drop them + drainer.next(); + drainer.next(); + + // get rid of drainer, but don't call its destructor + mem::forget(drainer); +} + +// Oops, vec[0] was dropped, we're reading a pointer into free'd memory! +println!("{}", vec[0]); +``` + +This is pretty clearly Not Good. Unfortunately, we're kind've stuck between +a rock and a hard place: maintaining consistent state at every step has +an enormous cost (and would negate any benefits of the API). Failing to maintain +consistent state gives us Undefined Behaviour in safe code (making the API +unsound). + +So what can we do? Well, we can pick a trivially consistent state: set the Vec's +len to be 0 when we *start* the iteration, and fix it up if necessary in the +destructor. That way, if everything executes like normal we get the desired +behaviour with minimal overhead. But if someone has the *audacity* to mem::forget +us in the middle of the iteration, all that does is *leak even more* (and possibly +leave the Vec in an *unexpected* but consistent state). Since we've +accepted that mem::forget is safe, this is definitely safe. We call leaks causing +more leaks a *leak amplification*. + + + + +## Rc + +Rc is an interesting case because at first glance it doesn't appear to be a +proxy value at all. After all, it manages the data it points to, and dropping +all the Rcs for a value will drop that value. leaking an Rc doesn't seem like +it would be particularly dangerous. It will leave the refcount permanently +incremented and prevent the data from being freed or dropped, but that seems +just like Box, right? + +Nope. + +Let's consider a simplified implementation of Rc: + +```rust +struct Rc { + ptr: *mut RcBox, +} + +struct RcBox { + data: T, + ref_count: usize, +} + +impl Rc { + fn new(data: T) -> Self { + unsafe { + // Wouldn't it be nice if heap::allocate worked like this? + let ptr = heap::allocate>(); + ptr::write(ptr, RcBox { + data: data, + ref_count: 1, + }); + Rc { ptr: ptr } + } + } + + fn clone(&self) -> Self { + unsafe { + (*self.ptr).ref_count += 1; + } + Rc { ptr: self.ptr } + } +} + +impl Drop for Rc { + fn drop(&mut self) { + unsafe { + let inner = &mut ; + (*self.ptr).ref_count -= 1; + if (*self.ptr).ref_count == 0 { + // drop the data and then free it + ptr::read(self.ptr); + heap::deallocate(self.ptr); + } + } + } +} +``` + +This code contains an implicit and subtle assumption: ref_count can fit in a +`usize`, because there can't be more than `usize::MAX` Rcs in memory. However +this itself assumes that the ref_count accurately reflects the number of Rcs +in memory, which we know is false with mem::forget. Using mem::forget we can +overflow the ref_count, and then get it down to 0 with outstanding Rcs. Then we +can happily use-after-free the inner data. Bad Bad Not Good. + +This can be solved by *saturating* the ref_count, which is sound because +decreasing the refcount by `n` still requires `n` Rcs simultaneously living +in memory. + + + + +## thread::scoped + +The thread::scoped API intends to allow threads to be spawned that reference +data on the stack without any synchronization over that data. Usage looked like: + +```rust +let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; +{ + let guards = vec![]; + for x in &mut data { + // Move the mutable reference into the closure, and execute + // it on a different thread. The closure has a lifetime bound + // by the lifetime of the mutable reference `x` we store in it. + // The guard that is returned is in turn assigned the lifetime + // of the closure, so it also mutably borrows `data` as `x` did. + // This means we cannot access `data` until the guard goes away. + let guard = thread::scoped(move || { + *x *= 2; + }); + // store the thread's guard for later + guards.push(guard); + } + // All guards are dropped here, forcing the threads to join + // (this thread blocks here until the others terminate). + // Once the threads join, the borrow expires and the data becomes + // accessible again in this thread. +} +// data is definitely mutated here. +``` + +In principle, this totally works! Rust's ownership system perfectly ensures it! +...except it relies on a destructor being called to be safe. + +``` +let mut data = Box::new(0); +{ + let guard = thread::scoped(|| { + // This is at best a data race. At worst, it's *also* a use-after-free. + *data += 1; + }); + // Because the guard is forgotten, expiring the loan without blocking this + // thread. + mem::forget(guard); +} +// So the Box is dropped here while the scoped thread may or may not be trying +// to access it. +``` -In the future, we expect there to be a first-class way to announce that a field -should be automatically dropped. +Dang. Here the destructor running was pretty fundamental to the API, and it had +to be scrapped in favour of a completely different design. [uninit]: uninitialized.html \ No newline at end of file From 069681a95327d8b49a26a8fd60aa6a9ecaaf52c4 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sat, 20 Jun 2015 23:15:48 -0700 Subject: [PATCH 016/104] vec exmaple maybe --- conversions.md | 43 +++++++++++---- intro.md | 16 +----- vec.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 174 insertions(+), 26 deletions(-) create mode 100644 vec.md diff --git a/conversions.md b/conversions.md index ae3ce9e312552..7467decb490b9 100644 --- a/conversions.md +++ b/conversions.md @@ -168,6 +168,8 @@ applied. +TODO: receiver coercions? + # Casts @@ -212,11 +214,10 @@ For numeric casts, there are quite a few cases to consider: * casting from a larger integer to a smaller integer (e.g. u8 -> u32) will * zero-extend if the target is unsigned * sign-extend if the target is signed -* casting from a float to an integer will: - * round the float towards zero if finite +* casting from a float to an integer will round the float towards zero * **NOTE: currently this will cause Undefined Behaviour if the rounded value cannot be represented by the target integer type**. This is a bug - and will be fixed. + and will be fixed. (TODO: figure out what Inf and NaN do) * casting from an integer to float will produce the floating point representation of the integer, rounded if necessary (rounding strategy unspecified). * casting from an f32 to an f64 is perfect and lossless. @@ -226,21 +227,41 @@ For numeric casts, there are quite a few cases to consider: is finite but larger or smaller than the largest or smallest finite value representable by f32**. This is a bug and will be fixed. -The casts involving rawptrs also allow us to completely bypass type-safety -by re-interpretting a pointer of T to a pointer of U for arbitrary types, as -well as interpret integers as addresses. However it is impossible to actually -*capitalize* on this violation in Safe Rust, because derefencing a raw ptr is -`unsafe`. - - # Conversion Traits -TODO +TODO? # Transmuting Types +Get out of our way type system! We're going to reinterpret these bits or die +trying! Even though this book is all about doing things that are unsafe, I really +can't emphasize that you should deeply think about finding Another Way than the +operations covered in this section. This is really, truly, the most horribly +unsafe thing you can do in Rust. The railguards here are dental floss. + +`mem::transmute` takes a value of type `T` and reinterprets it to have +type `U`. The only restriction is that the `T` and `U` are verified to have the +same size. The ways to cause Undefined Behaviour with this are mind boggling. + +* First and foremost, creating an instance of *any* type with an invalid state + is going to cause arbitrary chaos that can't really be predicted. +* Transmute has an overloaded return type. If you do not specify the return type + it may produce a surprising type to satisfy inference. +* Making a primitive with an invalid value is UB +* Transmuting between non-repr(C) types is UB +* Transmuting an & to &mut is UB +* Transmuting to a reference without an explicitly provided lifetime + produces an [unbound lifetime](lifetimes.html#unbounded-lifetimes) + +`mem::transmute_copy` somehow manages to be *even more* wildly unsafe than +this. It copies `size_of` bytes out of an `&T` and interprets them as a `U`. +The size check that `mem::transmute` has is gone (as it may be valid to copy +out a prefix), though it is Undefined Behaviour for `U` to be larger than `T`. + +Also of course you can get most of the functionality of these functions using +pointer casts. diff --git a/intro.md b/intro.md index b955d78bd38ba..f380f98a7dc0b 100644 --- a/intro.md +++ b/intro.md @@ -23,6 +23,7 @@ stack or heap, we will not explain the syntax. * [Uninitialized Memory](uninitialized.html) * [Ownership-oriented resource management (RAII)](raii.html) * [Concurrency](concurrency.html) +* [Example: Implementing Vec](vec.html) @@ -232,10 +233,6 @@ struct Vec { // We currently live in a nice imaginary world of only postive fixed-size // types. impl Vec { - fn new() -> Self { - Vec { ptr: heap::EMPTY, len: 0, cap: 0 } - } - fn push(&mut self, elem: T) { if self.len == self.cap { // not important for this example @@ -246,17 +243,6 @@ impl Vec { self.len += 1; } } - - fn pop(&mut self) -> Option { - if self.len > 0 { - self.len -= 1; - unsafe { - Some(ptr::read(self.ptr.offset(self.len as isize))) - } - } else { - None - } - } } ``` diff --git a/vec.md b/vec.md new file mode 100644 index 0000000000000..116626ffc39e4 --- /dev/null +++ b/vec.md @@ -0,0 +1,141 @@ +% Example: Implementing Vec + +To bring everything together, we're going to write `std::Vec` from scratch. +Because the all the best tools for writing unsafe code are unstable, this +project will only work on nightly (as of Rust 1.2.0). + +First off, we need to come up with the struct layout. Naively we want this +design: + +``` +struct Vec { + ptr: *mut T, + cap: usize, + len: usize, +} +``` + +And indeed this would compile. Unfortunately, it would be incorrect. The compiler +will give us too strict variance, so e.g. an `&Vec<&'static str>` couldn't be used +where an `&Vec<&'a str>` was expected. More importantly, it will give incorrect +ownership information to dropck, as it will conservatively assume we don't own +any values of type `T`. See [the chapter on ownership and lifetimes] +(lifetimes.html) for details. + +As we saw in the lifetimes chapter, we should use `Unique` in place of `*mut T` +when we have a raw pointer to an allocation we own: + + +``` +#![feature(unique)] + +use std::ptr::Unique; + +pub struct Vec { + ptr: Unique, + cap: usize, + len: usize, +} +``` + +As a recap, Unique is a wrapper around a raw pointer that declares that: + +* We own at least one value of type `T` +* We are Send/Sync iff `T` is Send/Sync +* Our pointer is never null (and therefore `Option` is null-pointer-optimized) + +That last point is subtle. First, it makes `Unique::new` unsafe to call, because +putting `null` inside of it is Undefined Behaviour. It also throws a +wrench in an important feature of Vec (and indeed all of the std collections): +an empty Vec doesn't actually allocate at all. So if we can't allocate, +but also can't put a null pointer in `ptr`, what do we do in +`Vec::new`? Well, we just put some other garbage in there! + +This is perfectly fine because we already have `cap == 0` as our sentinel for no +allocation. We don't even need to handle it specially in almost any code because +we usually need to check if `cap > len` or `len > 0` anyway. The traditional +Rust value to put here is `0x01`. The standard library actually exposes this +as `std::rt::heap::EMPTY`. There are quite a few places where we'll want to use +`heap::EMPTY` because there's no real allocation to talk about but `null` would +make the compiler angry. + +All of the `heap` API is totally unstable under the `alloc` feature, though. +We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of +the `heap` API anyway, so let's just get that dependency over with. + +So: + +```rust +#![feature(alloc)] + +use std::rt::heap::EMPTY; +use std::mem; + +impl Vec { + fn new() -> Self { + assert!(mem::size_of::() != 0, "We're not ready to handle ZSTs"); + unsafe { + // need to cast EMPTY to the actual ptr type we want, let + // inference handle it. + Vec { ptr: Unique::new(heap::EMPTY as *mut _), len: 0, cap: 0 } + } + } +} +``` + +I slipped in that assert there because zero-sized types will require some +special handling throughout our code, and I want to defer the issue for now. +Without this assert, some of our early drafts will do some Very Bad Things. + +Next we need to figure out what to actually do when we *do* want space. For that, +we'll need to use the rest of the heap APIs. These basically allow us to +talk directly to Rust's instance of jemalloc. + +We'll also need a way to handle out-of-memory conditions. The standard library +calls the `abort` intrinsic, but calling intrinsics from normal Rust code is a +pretty bad idea. Unfortunately, the `abort` exposed by the standard library +allocates. Not something we want to do during `oom`! Instead, we'll call +`std::process::exit`. + +```rust +fn oom() { + ::std::process::exit(-9999); +} +``` + +Okay, now we can write growing: + +```rust +fn grow(&mut self) { + unsafe { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } +} +``` + +There's nothing particularly tricky in here: if we're totally empty, we need +to do a fresh allocation. Otherwise, we need to reallocate the current pointer. +Although we have a subtle bug here with the multiply overflow. + +TODO: rest of this + + From 9c87b1f8dbc3105e3e9338b169d0884ce7a902af Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Sun, 21 Jun 2015 15:30:09 +0530 Subject: [PATCH 017/104] fix double "however" --- data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data.md b/data.md index 110084824cfef..1d4365dd75115 100644 --- a/data.md +++ b/data.md @@ -236,7 +236,7 @@ one. This is the most important `repr`. It has fairly simple intent: do what C does. The order, size, and alignment of fields is exactly what you would expect from C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, -as C is the lingua-franca of the programming world. However this is also necessary +as C is the lingua-franca of the programming world. This is also necessary to soundly do more elaborate tricks with data layout such as reintepretting values as a different type. From 709641bdf0c8778aab0f02b2f8cf631940fe7cbb Mon Sep 17 00:00:00 2001 From: Benjamin Herr Date: Sun, 21 Jun 2015 16:03:29 +0200 Subject: [PATCH 018/104] Tiny typo of "positive" --- intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/intro.md b/intro.md index f380f98a7dc0b..939ba4fa21294 100644 --- a/intro.md +++ b/intro.md @@ -230,7 +230,7 @@ struct Vec { } // Note this implementation does not correctly handle zero-sized types. -// We currently live in a nice imaginary world of only postive fixed-size +// We currently live in a nice imaginary world of only positive fixed-size // types. impl Vec { fn push(&mut self, elem: T) { From 74665906ab3f8a2808da7671022ac13f8fa12fbd Mon Sep 17 00:00:00 2001 From: Vadim Petrochenkov Date: Sun, 21 Jun 2015 18:54:41 +0300 Subject: [PATCH 019/104] Fix description of integer conversions --- conversions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/conversions.md b/conversions.md index 7467decb490b9..b35409553f740 100644 --- a/conversions.md +++ b/conversions.md @@ -210,10 +210,10 @@ expression, `e as U2` is not necessarily so (in fact it will only be valid if For numeric casts, there are quite a few cases to consider: * casting between two integers of the same size (e.g. i32 -> u32) is a no-op -* casting from a smaller integer to a bigger integer (e.g. u32 -> u8) will truncate -* casting from a larger integer to a smaller integer (e.g. u8 -> u32) will - * zero-extend if the target is unsigned - * sign-extend if the target is signed +* casting from a larger integer to a smaller integer (e.g. u32 -> u8) will truncate +* casting from a smaller integer to a larger integer (e.g. u8 -> u32) will + * zero-extend if the source is unsigned + * sign-extend if the source is signed * casting from a float to an integer will round the float towards zero * **NOTE: currently this will cause Undefined Behaviour if the rounded value cannot be represented by the target integer type**. This is a bug From 8e75c50729b6c0e4a88cdd2ab3a4a242412fda5d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 21 Jun 2015 09:41:45 -0700 Subject: [PATCH 020/104] community fixups --- data.md | 2 +- lifetimes.md | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/data.md b/data.md index 1d4365dd75115..f9163caa4e003 100644 --- a/data.md +++ b/data.md @@ -88,7 +88,7 @@ struct Foo { } ``` -The former case quite simply wastes space. An optimal use of space therefore requires +The latter case quite simply wastes space. An optimal use of space therefore requires different monomorphizations to *have different field orderings*. **Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0.0** diff --git a/lifetimes.md b/lifetimes.md index 4be895ff429b5..d6711e7df41b7 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -247,11 +247,11 @@ Of course, it might be bounded by the *wrong* lifetime, but this will usually just cause a compiler error, rather than allow memory safety to be trivially violated. -Within a function, bounding lifetimes is more error-prone. The safest route -is to just use a small function to ensure the lifetime is bound. However if -this is unacceptable, the reference can be placed in a location with a specific -lifetime. Unfortunately it's impossible to name all lifetimes involved in a -function. To get around this, you can in principle use `copy_lifetime`, though +Within a function, bounding lifetimes is more error-prone. The safest and easiest +way to bound a lifetime is to return it from a function with a bound lifetime. +However if this is unacceptable, the reference can be placed in a location with +a specific lifetime. Unfortunately it's impossible to name all lifetimes involved +in a function. To get around this, you can in principle use `copy_lifetime`, though these are unstable due to their awkward nature and questionable utility. @@ -425,7 +425,7 @@ must be invariant to avoid lifetime smuggling. `Fn` is the most confusing case, largely because contravariance is easily the most confusing kind of variance, and basically never comes up. To understand it, -consider a function that *takes* a function `len` that takes a function `F`. +consider a function `len` that takes a function `F`. ```rust fn len(func: F) -> usize @@ -435,8 +435,8 @@ fn len(func: F) -> usize } ``` -We require that F is a Fn that can take an `&'static str` and print a usize. Now -say we have a function that can take an `&'a str` (for *some* 'a). Such a function actually +We require that F is a Fn that can take an `&'static str` and returns a usize. Now +say we have a function that can take an `&'a str` (for *some* `'a`). Such a function actually accepts *more* inputs, since `&'static str` is a subtype of `&'a str`. Therefore `len` should happily accept such a function! @@ -643,8 +643,8 @@ trait Iterator { Given this definition, Self::Item has *no* connection to `self`. This means that we can call `next` several times in a row, and hold onto all the results *concurrently*. This is perfectly fine for by-value iterators, which have exactly -these semantics. It's also actually fine for shared references, as it's perfectly -fine to grab a huge pile of shared references to the same thing (although the +these semantics. It's also actually fine for shared references, as they admit +arbitrarily many references to the same thing (although the iterator needs to be a separate object from the thing being shared). But mutable references make this a mess. At first glance, they might seem completely incompatible with this API, as it would produce multiple mutable references to From bb3231522677c6cd2e3e667f488a06b71f097eb8 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 21 Jun 2015 09:57:44 -0700 Subject: [PATCH 021/104] fix paper link --- lifetimes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lifetimes.md b/lifetimes.md index d6711e7df41b7..fe4dc6270e194 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -58,7 +58,8 @@ a Cell is to copy the bits in or out. manages this through *runtime* checks. It is effectively a thread-unsafe read-write lock. -For more details see Dan Grossman's Existential Types for Imperative Languages: +For more details see Dan Grossman's *Existential Types for Imperative Languages*: + * [paper][grossman-paper] (Advanced) * [slides][grossman-slides] (Simple) From e5d39f7abe112cf7a4c73542841fa8c6784297cf Mon Sep 17 00:00:00 2001 From: Benjamin Herr Date: Tue, 23 Jun 2015 14:23:23 +0200 Subject: [PATCH 022/104] extra whitespace to render *-list as list This worked fine on github but isn't displayed as a bulleted list on http://www.cglab.ca/~abeinges/blah/turpl/concurrency.html#send-and-sync --- concurrency.md | 1 + 1 file changed, 1 insertion(+) diff --git a/concurrency.md b/concurrency.md index a382e4edf54cf..fc04bd83811af 100644 --- a/concurrency.md +++ b/concurrency.md @@ -97,6 +97,7 @@ Almost all primitives are Send and Sync, and as a consequence pretty much all types you'll ever interact with are Send and Sync. Major exceptions include: + * raw pointers are neither Send nor Sync (because they have no safety guards) * `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) * `Rc` isn't Send or Sync (because the refcount is shared and unsynchronized) From 328737216147b6107d6d28a405e3fd9cd1ded317 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 24 Jun 2015 10:59:30 -0700 Subject: [PATCH 023/104] so much Vec --- vec.md | 709 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 688 insertions(+), 21 deletions(-) diff --git a/vec.md b/vec.md index 116626ffc39e4..d38265b429e4b 100644 --- a/vec.md +++ b/vec.md @@ -1,17 +1,21 @@ % Example: Implementing Vec +TODO: audit for non-ZST offsets from heap::empty + To bring everything together, we're going to write `std::Vec` from scratch. Because the all the best tools for writing unsafe code are unstable, this project will only work on nightly (as of Rust 1.2.0). +# Layout + First off, we need to come up with the struct layout. Naively we want this design: ``` struct Vec { - ptr: *mut T, - cap: usize, - len: usize, + ptr: *mut T, + cap: usize, + len: usize, } ``` @@ -29,7 +33,7 @@ when we have a raw pointer to an allocation we own: ``` #![feature(unique)] -use std::ptr::Unique; +use std::ptr::{Unique, self}; pub struct Vec { ptr: Unique, @@ -63,6 +67,8 @@ All of the `heap` API is totally unstable under the `alloc` feature, though. We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of the `heap` API anyway, so let's just get that dependency over with. +# Allocating Memory + So: ```rust @@ -72,14 +78,14 @@ use std::rt::heap::EMPTY; use std::mem; impl Vec { - fn new() -> Self { - assert!(mem::size_of::() != 0, "We're not ready to handle ZSTs"); - unsafe { - // need to cast EMPTY to the actual ptr type we want, let - // inference handle it. - Vec { ptr: Unique::new(heap::EMPTY as *mut _), len: 0, cap: 0 } - } - } + fn new() -> Self { + assert!(mem::size_of::() != 0, "We're not ready to handle ZSTs"); + unsafe { + // need to cast EMPTY to the actual ptr type we want, let + // inference handle it. + Vec { ptr: Unique::new(heap::EMPTY as *mut _), len: 0, cap: 0 } + } + } } ``` @@ -103,10 +109,38 @@ fn oom() { } ``` -Okay, now we can write growing: +Okay, now we can write growing. Roughly, we want to have this logic: + +```text +if cap == 0: + allocate() + cap = 1 +else + reallocate + cap *= 2 +``` + +But Rust's only supported allocator API is so low level that we'll need to +do a fair bit of extra work, though. We also need to guard against some special +conditions that can occur with really large allocations. In particular, we index +into arrays using unsigned integers, but `ptr::offset` takes signed integers. This +means Bad Things will happen if we ever manage to grow to contain more than +`isize::MAX` elements. Thankfully, this isn't something we need to worry about +in most cases. + +On 64-bit targets we're artifically limited to only 48-bits, so we'll run out +of memory far before we reach that point. However on 32-bit targets, particularly +those with extensions to use more of the address space, it's theoretically possible +to successfully allocate more than `isize::MAX` bytes of memory. Still, we only +really need to worry about that if we're allocating elements that are a byte large. +Anything else will use up too much space. + +However since this is a tutorial, we're not going to be particularly optimal here, +and just unconditionally check, rather than use clever platform-specific `cfg`s. ```rust fn grow(&mut self) { + // this is all pretty delicate, so let's say it's all unsafe unsafe { let align = mem::min_align_of::(); let elem_size = mem::size_of::(); @@ -115,16 +149,31 @@ fn grow(&mut self) { let ptr = heap::allocate(elem_size, align); (1, ptr) } else { - let new_cap = 2 * self.cap; + // as an invariant, we can assume that `self.cap < isize::MAX`, + // so this doesn't need to be checked. + let new_cap = self.cap * 2; + // Similarly this can't overflow due to previously allocating this + let old_num_bytes = self.cap * elem_size; + + // check that the new allocation doesn't exceed `isize::MAX` at all + // regardless of the actual size of the capacity. This combines the + // `new_cap <= isize::MAX` and `new_num_bytes <= usize::MAX` checks + // we need to make. We lose the ability to allocate e.g. 2/3rds of + // the address space with a single Vec of i16's on 32-bit though. + // Alas, poor Yorick -- I knew him, Horatio. + assert!(old_num_bytes <= (::std::isize::MAX as usize) / 2, + "capacity overflow"); + + let new_num_bytes = old_num_bytes * 2; let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, + old_num_bytes, + new_num_bytes, align); (new_cap, ptr) }; // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } + if ptr.is_null() { oom(); } self.ptr = Unique::new(ptr as *mut _); self.cap = new_cap; @@ -132,10 +181,628 @@ fn grow(&mut self) { } ``` -There's nothing particularly tricky in here: if we're totally empty, we need -to do a fresh allocation. Otherwise, we need to reallocate the current pointer. -Although we have a subtle bug here with the multiply overflow. +Nothing particularly tricky here. Just computing sizes and alignments and doing +some careful multiplication checks. + +# Push and Pop + +Alright. We can initialize. We can allocate. Let's actually implement some +functionality! Let's start with `push`. All it needs to do is check if we're +full to grow, unconditionally write to the next index, and then increment our +length. + +To do the write we have to be careful not to evaluate the memory we want to write +to. At worst, it's truly uninitialized memory from the allocator. At best it's the +bits of some old value we popped off. Either way, we can't just index to the memory +and dereference it, because that will evaluate the memory as a valid instance of +T. Worse, `foo[idx] = x` will try to call `drop` on the old value of `foo[idx]`! + +The correct way to do this is with `ptr::write`, which just blindly overwrites the +target address with the bits of the value we provide. No evaluation involved. + +For `push`, if the old len (before push was called) is 0, then we want to write +to the 0th index. So we should offset by the old len. + +```rust +pub fn push(&mut self, elem: T) { + if self.len == self.cap { self.grow(); } + + unsafe { + ptr::write(self.ptr.offset(self.len as isize), elem); + } + + // Can't fail, we'll OOM first. + self.len += 1; +} +``` + +Easy! How about `pop`? Although this time the index we want to access is +initialized, Rust won't just let us dereference the location of memory to move +the value out, because that *would* leave the memory uninitialized! For this we +need `ptr::read`, which just copies out the bits from the target address and +intrprets it as a value of type T. This will leave the memory at this address +*logically* uninitialized, even though there is in fact a perfectly good instance +of T there. + +For `pop`, if the old len is 1, we want to read out of the 0th index. So we +should offset by the *new* len. + +```rust +pub fn pop(&mut self) -> Option { + if self.len == 0 { + None + } else { + self.len -= 1; + unsafe { + Some(ptr::read(self.ptr.offset(self.len as isize))) + } + } +} +``` + +# Deallocating + +Next we should implement Drop so that we don't massively leaks tons of resources. +The easiest way is to just call `pop` until it yields None, and then deallocate +our buffer. Note that calling `pop` is uneeded if `T: !Drop`. In theory we can +ask Rust if T needs_drop and omit the calls to `pop`. However in practice LLVM +is *really* good at removing simple side-effect free code like this, so I wouldn't +bother unless you notice it's not being stripped (in this case it is). + +We must not call `heap::deallocate` when `self.cap == 0`, as in this case we haven't +actually allocated any memory. + + +```rust +impl Drop for Vec { + fn drop(&mut self) { + if self.cap != 0 { + while let Some(_) = self.pop() { } + + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr, num_bytes, align); + } + } + } +} +``` + +# Deref + +Alright! We've got a decent minimal ArrayStack implemented. We can push, we can +pop, and we can clean up after ourselves. However there's a whole mess of functionality +we'd reasonably want. In particular, we have a proper array, but none of the slice +functionality. That's actually pretty easy to solve: we can implement `Deref`. +This will magically make our Vec coerce to and behave like a slice in all sorts of +conditions. + +All we need is `slice::from_raw_parts`. + +```rust +use std::ops::Deref; + +impl Deref for Vec { + type Target = [T]; + fn deref(&self) -> &[T] { + unsafe { + ::std::slice::from_raw_parts(*self.ptr, self.len) + } + } +} +``` + +And let's do DerefMut too: + +```rust +use std::ops::DerefMut; + +impl DerefMut for Vec { + fn deref_mut(&mut self) -> &mut [T] { + unsafe { + ::std::slice::from_raw_parts_mut(*self.ptr, self.len) + } + } +} +``` + +Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, `iter_mut`, +and all other sorts of bells and whistles provided by slice. Sweet! + +# Insert and Remove + +Something *not* provided but slice is `insert` and `remove`, so let's do those next. + +Insert needs to shift all the elements at the target index to the right by one. +To do this we need to use `ptr::copy`, which is our version of C's `memmove`. +This copies some chunk of memory from one location to another, correctly handling +the case where the source and destination overlap (which will definitely happen +here). + +If we insert at index `i`, we want to shift the `[i .. len]` to `[i+1 .. len+1]` +using the *old* len. + +```rust +pub fn insert(&mut self, index: usize, elem: T) { + // Note: `<=` because it's valid to insert after everything + // which would be equivalent to push. + assert!(index <= self.len, "index out of bounds"); + if self.cap == self.len { self.grow(); } + + unsafe { + if index < self.len { + // ptr::copy(src, dest, len): "copy from source to dest len elems" + ptr::copy(self.ptr.offset(index as isize), + self.ptr.offset(index as isize + 1), + len - index); + } + ptr::write(self.ptr.offset(index as isize), elem); + self.len += 1; + } +} +``` + +Remove behaves in the opposite manner. We need to shift all the elements from +`[i+1 .. len + 1]` to `[i .. len]` using the *new* len. + +```rust +pub fn remove(&mut self, index: usize) -> T { + // Note: `<` because it's *not* valid to remove after everything + assert!(index < self.len, "index out of bounds"); + unsafe { + self.len -= 1; + let result = ptr::read(self.ptr.offset(index as isize)); + ptr::copy(self.ptr.offset(index as isize + 1), + self.ptr.offset(index as isize), + len - index); + result + } +} +``` + +# IntoIter + +Let's move on to writing iterators. `iter` and `iter_mut` have already been +written for us thanks to The Magic of Deref. However there's two interesting +iterators that Vec provides that slices can't: `into_iter` and `drain`. + +IntoIter consumes the Vec by-value, and can consequently yield its elements +by-value. In order to enable this, IntoIter needs to take control of Vec's +allocation. + +IntoIter needs to be DoubleEnded as well, to enable reading from both ends. +Reading from the back could just be implemented as calling `pop`, but reading +from the front is harder. We could call `remove(0)` but that would be insanely +expensive. Instead we're going to just use ptr::read to copy values out of either +end of the Vec without mutating the buffer at all. + +To do this we're going to use a very common C idiom for array iteration. We'll +make two pointers; one that points to the start of the array, and one that points +to one-element past the end. When we want an element from one end, we'll read out +the value pointed to at that end and move the pointer over by one. When the two +pointers are equal, we know we're done. + +Note that the order of read and offset are reversed for `next` and `next_back` +For `next_back` the pointer is always *after* the element it wants to read next, +while for `next` the pointer is always *at* the element it wants to read next. +To see why this is, consider the case where every element but one has been yielded. + +The array looks like this: + +```text + S E +[X, X, X, O, X, X, X] +``` + +If E pointed directly at the element it wanted to yield next, it would be +indistinguishable from the case where there are no more elements to yield. + +So we're going to use the following struct: + +```rust +struct IntoIter { + buf: Unique, + cap: usize, + start: *const T, + end: *const T, +} +``` + +And initialize it like this: + +```rust +impl Vec { + fn into_iter(self) -> IntoIter { + // Can't destructure Vec since it's Drop + let ptr = self.ptr; + let cap = self.cap; + let len = self.len; + + // Make sure not to drop Vec since that will free the buffer + mem::forget(self); + + unsafe { + IntoIter { + buf: ptr, + cap: cap, + start: *ptr, + end: ptr.offset(len as isize), + } + } + } +} +``` + +Here's iterating forward: + +```rust +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = self.start.offset(1); + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let len = self.end as usize - self.start as usize; + (len, Some(len)) + } +} +``` + +And here's iterating backwards. + +```rust +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = self.end.offset(-1); + Some(ptr::read(self.end)) + } + } + } +} + +Because IntoIter takes ownership of its allocation, it needs to implement Drop +to free it. However it *also* wants to implement Drop to drop any elements it +contains that weren't yielded. + + +```rust +impl Drop for IntoIter { + fn drop(&mut self) { + if self.cap != 0 { + // drop any remaining elements + for _ in &mut *self {} + + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.buf as *mut _, num_bytes, align); + } + } + } +} +``` + +We've actually reached an interesting situation here: we've duplicated the logic +for specifying a buffer and freeing its memory. Now that we've implemented it and +identified *actual* logic duplication, this is a good time to perform some logic +compression. + +We're going to abstract out the `(ptr, cap)` pair and give them the logic for +allocating, growing, and freeing: + +```rust + +struct RawVec { + ptr: Unique, + cap: usize, +} + +impl RawVec { + fn new() -> Self { + assert!(mem::size_of::() != 0, "TODO: implement ZST support"); + unsafe { + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: 0 } + } + } + + // unchanged from Vec + fn grow(&mut self) { + unsafe { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + + +impl Drop for RawVec { + fn drop(&mut self) { + if self.cap != 0 { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +And change vec as follows: + +```rust +pub struct Vec { + buf: RawVec, + len: usize, +} + +impl Vec { + fn ptr(&self) -> *mut T { *self.buf.ptr } + + fn cap(&self) -> usize { self.buf.cap } + + pub fn new() -> Self { + Vec { buf: RawVec::new(), len: 0 } + } + + // push/pop/insert/remove largely unchanged: + // * `self.ptr -> self.ptr()` + // * `self.cap -> self.cap()` + // * `self.grow -> self.buf.grow()` +} + +impl Drop for Vec { + fn drop(&mut self) { + while let Some(_) = self.pop() {} + // deallocation is handled by RawVec + } +} +``` + +And finally we can really simplify IntoIter: + +```rust +struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + start: *const T, + end: *const T, +} + +// next and next_back litterally unchanged since they never referred to the buf + +impl Drop for IntoIter { + fn drop(&mut self) { + // only need to ensure all our elements are read; + // buffer will clean itself up afterwards. + for _ in &mut *self {} + } +} + +impl Vec { + pub fn into_iter(self) -> IntoIter { + unsafe { + // need to use ptr::read to unsafely move the buf out since it's + // not Copy. + let buf = ptr::read(&self.buf); + let len = self.len; + mem::forget(self); + + IntoIter { + start: *buf.ptr, + end: buf.ptr.offset(len as isize), + _buf: buf, + } + } + } +} +``` + +Much better. + +# Drain + +Let's move on to Drain. Drain is largely the same as IntoIter, except that +instead of consuming the Vec, it borrows the Vec and leaves its allocation +free. For now we'll only implement the "basic" full-range version. + +```rust,ignore +use std::marker::PhantomData; + +struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec> + start: *const T, + end: *const T, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None +``` + +-- wait, this is seeming familiar. Let's do some more compression. Both +IntoIter and Drain have the exact same structure, let's just factor it out. + +```rust +struct RawValIter { + start: *const T, + end: *const T, +} + +impl RawValIter { + // unsafe to construct because it has no associated lifetimes. + // This is necessary to store a RawValIter in the same struct as + // its actual allocation. OK since it's a private implementation + // detail. + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: slice.as_ptr().offset(slice.len() as isize), + } + } +} + +// Iterator and DoubleEndedIterator impls identical to IntoIter. +``` + +And IntoIter becomes the following: + +``` +pub struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + iter: RawValIter, +} + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { self.iter.next() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl Drop for IntoIter { + fn drop(&mut self) { + for _ in &mut self.iter {} + } +} + +impl Vec { + pub fn into_iter(self) -> IntoIter { + unsafe { + let iter = RawValIter::new(&self); + let buf = ptr::read(&self.buf); + mem::forget(self); + + IntoIter { + iter: iter, + _buf: buf, + } + } + } +} +``` + +Note that I've left a few quirks in this design to make upgrading Drain to work +with arbitrary subranges a bit easier. In particular we *could* have RawValIter +drain itself on drop, but that won't work right for a more complex Drain. +We also take a slice to simplify Drain initialization. + +Alright, now Drain is really easy: + +```rust +use std::marker::PhantomData; + +pub struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec>, + iter: RawValIter, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { self.iter.next_back() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl<'a, T> DoubleEndedIterator for Drain<'a, T> { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl<'a, T> Drop for Drain<'a, T> { + fn drop(&mut self) { + for _ in &mut self.iter {} + } +} + +impl Vec { + pub fn drain(&mut self) -> Drain { + // this is a mem::forget safety thing. If Drain is forgotten, we just + // leak the whole Vec's contents. Also we need to do this *eventually* + // anyway, so why not do it now? + self.len = 0; + + unsafe { + Drain { + iter: RawValIter::new(&self), + vec: PhantomData, + } + } + } +} +``` + + +# Handling Zero-Sized Types + +It's time. We're going to fight the spectre that is zero-sized types. Safe Rust +*never* needs to care about this, but Vec is very intensive on raw pointers and +raw allocations, which are exactly the *only* two things that care about +zero-sized types. We need to be careful of two things: + +* The raw allocator API has undefined behaviour if you pass in 0 for an + allocation size. +* raw pointer offsets are no-ops for zero-sized types, which will break our + C-style pointer iterator + +Thankfully we abstracted out pointer-iterators and allocating handling into +RawValIter and RawVec respectively. How mysteriously convenient. + + + +## Allocating Zero-Sized Types + +So if the allocator API doesn't support zero-sized allocations, what on earth +do we store as our allocation? Why, `heap::EMPTY` of course! Almost every operation +with a ZST is a no-op since ZSTs have exactly one value, and therefore no state needs +to be considered to store or load them. This actually extends to `ptr::read` and +`ptr::write`: they won't actually look at the pointer at all. As such we *never* need +to change the pointer. + +TODO + +## Iterating Zero-Sized Types + +TODO -TODO: rest of this +## Advanced Drain +TODO? Not clear if informative From af2fd1d53ee2013a8febcef0b064739d1ed7d76e Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 24 Jun 2015 12:15:45 -0700 Subject: [PATCH 024/104] rustbook support --- FiraSans-Medium.woff | Bin 0 -> 89883 bytes FiraSans-Regular.woff | Bin 0 -> 91946 bytes Heuristica-Italic.woff | Bin 0 -> 119956 bytes README.md | 255 +++++++++++++++++++++- SUMMARY.md | 9 + SourceCodePro-Regular.woff | Bin 0 -> 55472 bytes SourceCodePro-Semibold.woff | Bin 0 -> 55360 bytes SourceSerifPro-Bold.woff | Bin 0 -> 48720 bytes SourceSerifPro-Regular.woff | Bin 0 -> 49960 bytes intro.md | 267 ----------------------- rust.css | 407 ++++++++++++++++++++++++++++++++++++ vec.md | 5 +- 12 files changed, 672 insertions(+), 271 deletions(-) create mode 100644 FiraSans-Medium.woff create mode 100644 FiraSans-Regular.woff create mode 100644 Heuristica-Italic.woff create mode 100644 SUMMARY.md create mode 100644 SourceCodePro-Regular.woff create mode 100644 SourceCodePro-Semibold.woff create mode 100644 SourceSerifPro-Bold.woff create mode 100644 SourceSerifPro-Regular.woff delete mode 100644 intro.md create mode 100644 rust.css diff --git a/FiraSans-Medium.woff b/FiraSans-Medium.woff new file mode 100644 index 0000000000000000000000000000000000000000..5627227744ae5b2ffb83e632cb32b237428c8962 GIT binary patch literal 89883 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%0Dk_#%Y{EcU_rFP4oA@FKf8}T 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�*_BmXVd#S5mW8HYZxRlrC2S%~o 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 literal 0 HcmV?d00001 diff --git a/README.md b/README.md index e391c9a48ea3c..19fd3f232d3e7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,254 @@ -# The Unsafe Rust Programming Language (Book) +% The Unsafe Rust Programming Language + +**This document is about advanced functionality and low-level development practices +in the Rust Programming Language. Most of the things discussed won't matter +to the average Rust programmer. However if you wish to correctly write unsafe +code in Rust, this text contains invaluable information.** + +This document seeks to complement [The Rust Programming Language Book][trpl] (TRPL). +Where TRPL introduces the language and teaches the basics, TURPL dives deep into +the specification of the language, and all the nasty bits necessary to write +Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know +the basics of the language and systems programming. We will not explain the +stack or heap, we will not explain the syntax. + + +# A Tale Of Two Languages + +Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. +Any time someone opines the guarantees of Rust, they are almost surely talking about +Safe Rust. However Safe Rust is not sufficient to write every program. For that, +we need the Unsafe Rust superset. + +Most fundamentally, writing bindings to other languages +(such as the C exposed by your operating system) is never going to be safe. Rust +can't control what other languages do to program execution! However Unsafe Rust is +also necessary to construct fundamental abstractions where the type system is not +sufficient to automatically prove what you're doing is sound. + +Indeed, the Rust standard library is implemented in Rust, and it makes substantial +use of Unsafe Rust for implementing IO, memory allocation, collections, +synchronization, and other low-level computational primitives. + +Upon hearing this, many wonder why they would not simply just use C or C++ in place of +Rust (or just use a "real" safe language). If we're going to do unsafe things, why not +lean on these much more established languages? + +The most important difference between C++ and Rust is a matter of defaults: +Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular +action. In deciding to work with unchecked uninitialized memory, this does not +suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, +one does not have to suddenly worry about indexing out of bounds on `y`. +C and C++, by contrast, have pervasive unsafety baked into the language. Even the +modern best practices like `unique_ptr` have various safety pitfalls. + +It should also be noted that writing Unsafe Rust should be regarded as an exceptional +action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs +to make FFI bindings or define core abstractions. These fundamental libraries then expose +a *safe* interface for intermediate libraries and applications to build upon. And these +safe interfaces make an important promise: if your application segfaults, it's not your +fault. *They* have a bug. + +And really, how is that different from *any* safe language? Python, Ruby, and Java libraries +can internally do all sorts of nasty things. The languages themselves are no +different. Safe languages regularly have bugs that cause critical vulnerabilities. +The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different. +However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of +C to do the nasty things that need to get done. + + + + +# What does `unsafe` mean? + +Rust tries to model memory safety through the `unsafe` keyword. Interestingly, +the meaning of `unsafe` largely revolves around what +its *absence* means. If the `unsafe` keyword is absent from a program, it should +not be possible to violate memory safety under *any* conditions. The presence +of `unsafe` means that there are conditions under which this code *could* +violate memory safety. + +To be more concrete, Rust cares about preventing the following things: + +* Dereferencing null/dangling pointers +* Reading uninitialized memory +* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell) +* Invoking Undefined Behaviour (in e.g. compiler intrinsics) +* Producing invalid primitive values: + * dangling/null references + * a `bool` that isn't 0 or 1 + * an undefined `enum` discriminant + * a `char` larger than char::MAX + * A non-utf8 `str` +* Unwinding into an FFI function +* Causing a data race + +That's it. That's all the Undefined Behaviour in Rust. Libraries are free to +declare arbitrary requirements if they could transitively cause memory safety +issues, but it all boils down to the above actions. Rust is otherwise +quite permisive with respect to other dubious operations. Rust considers it +"safe" to: + +* Deadlock +* Leak memory +* Fail to call destructors +* Access private fields +* Overflow integers +* Delete the production database + +However any program that does such a thing is *probably* incorrect. Rust just isn't +interested in modeling these problems, as they are much harder to prevent in general, +and it's literally impossible to prevent incorrect programs from getting written. + +There are several places `unsafe` can appear in Rust today, which can largely be +grouped into two categories: + +* There are unchecked contracts here. To declare you understand this, I require +you to write `unsafe` elsewhere: + * On functions, `unsafe` is declaring the function to be unsafe to call. Users + of the function must check the documentation to determine what this means, + and then have to write `unsafe` somewhere to identify that they're aware of + the danger. + * On trait declarations, `unsafe` is declaring that *implementing* the trait + is an unsafe operation, as it has contracts that other unsafe code is free to + trust blindly. + +* I am declaring that I have, to the best of my knowledge, adhered to the +unchecked contracts: + * On trait implementations, `unsafe` is declaring that the contract of the + `unsafe` trait has been upheld. + * On blocks, `unsafe` is declaring any unsafety from an unsafe + operation within to be handled, and therefore the parent function is safe. + +There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for +historical reasons and is in the process of being phased out. See the section on +destructors for details. + +Some examples of unsafe functions: + +* `slice::get_unchecked` will perform unchecked indexing, allowing memory + safety to be freely violated. +* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is + not "in bounds" as defined by LLVM (see the lifetimes section for details). +* `mem::transmute` reinterprets some value as having the given type, + bypassing type safety in arbitrary ways. (see the conversions section for details) +* All FFI functions are `unsafe` because they can do arbitrary things. + C being an obvious culprit, but generally any language can do something + that Rust isn't happy about. (see the FFI section for details) + +As of Rust 1.0 there are exactly two unsafe traits: + +* `Send` is a marker trait (it has no actual API) that promises implementors + are safe to send to another thread. +* `Sync` is a marker trait that promises that threads can safely share + implementors through a shared reference. + +All other traits that declare any kind of contract *really* can't be trusted +to adhere to their contract when memory-safety is at stake. For instance Rust has +`PartialOrd` and `Ord` to differentiate between types which can "just" be +compared and those that implement a total ordering. However you can't actually +trust an implementor of `Ord` to actually provide a total ordering if failing to +do so causes you to e.g. index out of bounds. But if it just makes your program +do a stupid thing, then it's "fine" to rely on `Ord`. + +The reason this is the case is that `Ord` is safe to implement, and it should be +impossible for bad *safe* code to violate memory safety. Rust has traditionally +avoided making traits unsafe because it makes `unsafe` pervasive in the language, +which is not desirable. The only reason `Send` and `Sync` are unsafe is because +thread safety is a sort of fundamental thing that a program can't really guard +against locally (even by-value message passing still requires a notion Send). + + + + +# Working with unsafe + +Rust generally only gives us the tools to talk about safety in a scoped and +binary manner. Unfortunately reality is significantly more complicated than that. +For instance, consider the following toy function: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx < arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +Clearly, this function is safe. We check that the index is in bounds, and if it +is, index into the array in an unchecked manner. But even in such a trivial +function, the scope of the unsafe block is questionable. Consider changing the +`<` to a `<=`: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx <= arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +This program is now unsound, an yet *we only modified safe code*. This is the +fundamental problem of safety: it's non-local. The soundness of our unsafe +operations necessarily depends on the state established by "safe" operations. +Although safety *is* modular (we *still* don't need to worry about about +unrelated safety issues like uninitialized memory), it quickly contaminates the +surrounding code. + +Trickier than that is when we get into actual statefulness. Consider a simple +implementation of `Vec`: + +```rust +// Note this defintion is insufficient. See the section on lifetimes. +struct Vec { + ptr: *mut T, + len: usize, + cap: usize, +} + +// Note this implementation does not correctly handle zero-sized types. +// We currently live in a nice imaginary world of only positive fixed-size +// types. +impl Vec { + fn push(&mut self, elem: T) { + if self.len == self.cap { + // not important for this example + self.reallocate(); + } + unsafe { + ptr::write(self.ptr.offset(len as isize), elem); + self.len += 1; + } + } +} +``` + +This code is simple enough to reasonably audit and verify. Now consider +adding the following method: + +```rust + fn make_room(&mut self) { + // grow the capacity + self.cap += 1; + } +``` + +This code is safe, but it is also completely unsound. Changing the capacity +violates the invariants of Vec (that `cap` reflects the allocated space in the +Vec). This is not something the rest of `Vec` can guard against. It *has* to +trust the capacity field because there's no way to verify it. + +`unsafe` does more than pollute a whole function: it pollutes a whole *module*. +Generally, the only bullet-proof way to limit the scope of unsafe code is at the +module boundary with privacy. + +[trpl]: https://doc.rust-lang.org/book/ -[Start at the intro](http://www.cglab.ca/~abeinges/blah/turpl/intro.html) \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000000000..d136ebcebd4e8 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,9 @@ +# Summary + +* [Data Layout](data.md) +* [Ownership and Lifetimes](lifetimes.md) +* [Conversions](conversions.md) +* [Uninitialized Memory](uninitialized.md) +* [Ownership-oriented resource management (RAII)](raii.md) +* [Concurrency](concurrency.md) +* [Example: Implementing Vec](vec.md) \ No newline at end of file diff --git a/SourceCodePro-Regular.woff b/SourceCodePro-Regular.woff new file mode 100644 index 0000000000000000000000000000000000000000..5576670903aea90041f214624c8dd1176fdf6081 GIT binary patch literal 55472 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 N>i-Ak^d1HP005RYhx7md literal 0 HcmV?d00001 diff --git a/SourceCodePro-Semibold.woff b/SourceCodePro-Semibold.woff new file mode 100644 index 0000000000000000000000000000000000000000..ca972a11dc428209dd66212e382b884f168e83f7 GIT binary patch literal 55360 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

d?~=$y_z?$}zMRxO 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

-nf}~4k^lgCB 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 d&xU0F2O@Pp9zf@HhMqK>r}n002Tsb2$J2 literal 0 HcmV?d00001 diff --git a/SourceSerifPro-Bold.woff b/SourceSerifPro-Bold.woff new file mode 100644 index 0000000000000000000000000000000000000000..ac1b1b3a0bb7a673d52495743d8f86fd55188b44 GIT binary patch literal 48720 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�*_BmXVd#S5mW8HYZxRlrC2S%~o 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 diff --git a/SourceCodePro-Regular.woff b/SourceCodePro-Regular.woff deleted file mode 100644 index 5576670903aea90041f214624c8dd1176fdf6081..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 55472 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 N>i-Ak^d1HP005RYhx7md diff --git a/SourceCodePro-Semibold.woff b/SourceCodePro-Semibold.woff deleted file mode 100644 index ca972a11dc428209dd66212e382b884f168e83f7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 55360 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

d?~=$y_z?$}zMRxO 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

-nf}~4k^lgCB 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 d&xU0F2O@Pp9zf@HhMqK>r}n002Tsb2$J2 diff --git a/SourceSerifPro-Bold.woff b/SourceSerifPro-Bold.woff deleted file mode 100644 index ac1b1b3a0bb7a673d52495743d8f86fd55188b44..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 48720 zcmZ5mV{m3mw|?V^ZA_d@Y-3{Ewr$(CZQHi(iEZ1-&G~-bu6n9>uU_cg#&VGn76t$T zenPh_0O=t$CZDAC zdqrer6aavfKmY)B6#&pI?3QYs7Ew^*2LR%U0RXTcUa0YP{YelR1zH9G02tv%m&y-x zwV<2;23C5u0021751$DD0MXxI1+rn_?1&Elz-;{Rkp2fCMd%7+TN5h)0Q$!U5bzHi zz|}HYP4paoWaD;zcz*qd?{5HziKUw{0Dwpb02rkJ085<(T0t15MtX)nGKoJtEdK%M z>%nuD9{{v-TjaA>D`u|Y}lI%%XE~*31^$36jIr*UgW&-~H{Of;lzQZ@) zS3PJvNb(OaB;bEk0Kj$4K-W-LH~Yzk2n1x}>pS`zSB;b&AQTIfzyQdE1sD5I_(wM| z5x^7x2Ji$x{Lj))bNtYL>JR`50QygdvFCVWh+mSQUs=Q-e?PxIY<|XJdJOt;U?DZO zR5dl#v{Y4J`-{JmqX4jI8tG~nC>WTYv{dWQ_rcy?uBf@+qggQV2Axw(@S=a{=zst$ z=`eFYW$RkfvQ!kp7``<*@|F5!)zV({yM7|M`5a5FPpTPK3as)MwV;APelEYJM(ASz zm3acGy&03f6h5c{U3jc5kX-(-t4LxYYaj+TuRkKJ%0?a}ItJy*Ew9NjRnr>DZ9i#G zCu4)dQKsARCA)J?@ZpztWvxil?3L2+mGYXmxF;yKo#g3`v(Y4|Hf+g-+3+$YGLB+F zmRv_x{x@iG<0Kvdja-SBkk~u)rI$K}rtYQ~^Ez(5GxNSgVoMB#*_YuK9oCYWxcDke zwozwkZ;8dSv_J#2bIp%*O7#5Hbz@*0gf z8NcA@wl7(ao^Y?b(Cm>S?&RkzN&9(?9~teczlIMjtINoJ?xCU`Xj9fxCvGiiw&_!z z)i>A&O%NSCwot1wdeU+uIvt$pIor62H=tHK8y7_D%W*I9dkrz8HQ=7rW0#gOykn0*YAUx#3F7_TYRQ-l zVp=9VUf*mE^1M3cKt60*qA}j?X>j)cO4&H(xIa5#jH!#%ae3^iT;E^0tQ9((d~cL; zG`_DkQ#J*(4AH;%vz6|a->-$jMtkc{C5)eT&Wolg96Tk;cV{tFJ!rJe2<-{&ksb|f zm21|Lx>u76KdX;uW3bLt{5ES4Di9?MadfJ376xa^ z93ggVtvrl=O|Qeu%rlNIU#OE9o51tNUZiM{z%?dwQV22k zVla~FP3x4(l;Wsz19Vv>?wZlr+Oq+9B};q$w6@Y1#s3FoyZH4yRd{WVlXi?4}$gJFhFv6$9dyWoyvca$tXp(RJPf>h~TI%q~x-pTNH` zM6Re~ThQP8k39gf6q~{S=98o(H^oFHjNzPPIDGPP7II)l@B34LS#|3!lpi#WnYpo? zur*1#nYvlgKmRsjYs0+@#5(Y!a8~xC8SaP} z>SH(WA>7$wyk3khZHziyNJ10EO_>VQ2fLuC`jQjh5Z}9nhO}juxTd44jv{jn5KAX? zCDa9EKkV3LACltjvxC>tRM6vE&EXNzL2+VAB72>R*u2rDu-XBKZA`*ePI0h>++PSr z3BNgDuMwajo`hMS!~nTse$v4V7^URB{6fAZSiYsf4Hy5TVkB!lF64HDr>WU8nrV?r zK`$DsE!9@_OK^|5EiQ&0%)<@r5T}MM(d+7w^MNYLs z=p|Cqgr>4J%iH$*KQ*7!cFAqYK}ypFz3$acoxyFQ}DOdcjC9=BRPA{ zL_7az$E$0vQpw|S94C>fk*iRR!k@yUKP9Fh0Px~j6^$;9j)A;i`+b`b+A8|KlyUi{ za*D4thbt2`z(yH(({(9HBuR&B663<+-}$AZ+NM1=J$f?@to0g~?cAH$#=rGqYEmsY z%{cWYQmz%{f~^9m$5_T$8rj-gmF!&Y7WRgRjB`honLg!Di%?b?lqBCVbCKM_BViI} z{PJJOm;{;L^4OBbGzXP5iI`J|sikR9@3Cs`lVjzScw0OohG?ECoo4TaT^q6v!DCeJ(~^lj7@}G7_`Th_-k4ON?oq1g`$#Z zLLp#*(W}d~CeLKY@45tP#w{jdd)TJmm~l3cZy;F5SW7T&geor)PaoHDT~e{GR{FZ1kyJkMzw|ZaXI#RIt~Fp@Kd-O&}$DOJ@mGm z1QeY_7`Z}D&?8jP|FXD&THaNvMCZ4PZQl%Cse`oH@qiIdSGF}URU>4`hz1KXZX1QoaY-+TLYfj{%C zRxG#lARR)`2piP_xF}jYH6;pV%}JR&TbykAUve&3-uY_5Cpb|vQ%&3CJVq^=VBPqr z=6}PC*Hb6=4amM0NC#FgXnW8JFYl5&H9q(duXmkd_?gQ}*J7RZYz~%{urBkb>4tK= z;1L{Wu02uh%hxs<fgvn3aTlJ!CZ1-RmvskMKNb0b8lyL6hotuF}J=#5T98b{I}Mu z_vTL3hQ)=6W!NDzhHgw(mXZG%oa)W%$`XPd*Z()2ihfv335#S1<-`cmfWcB%-(X>* zD{EUdm1ujr)fbC^Qs*b<4kB;>KFk9sy+oq;+3TVJ7yx{LP(b|8H~cpe019XofCLN! zfCmozLDmmee|UaubNBm*VtD`nw(p1O4$9M;Sv_~1962-0Ce>=EP8MC<4e#0&lkA*R zlhrk(1c-=;gop;BgP|CR^n`Cjgoc8Ff`b?Y`-q6Qp+9;1h_|t>qJzIMuX9HB?-752 zR)1R_q}`F;Pv7IdW`Mc&nfEE>HPLAiQ>4?3L*e#EaRzhhgi8(8?cH|-cSI1DnTjTM zu6SRIS|X5LOI*o_Kg2g7*^Rl1RVPv)Cr>43i9-~vLVQ6$Fle%naJrlNvl3aMyWnp2{ftE)mpG(o)7B=kNo=r>$xMMCGq?-nFH}{zAperZ`7@1*IRtN%SFczm zf0o2NE=*GKK<;)J%TSC|URZ9Q#AhVOTqbXxwN_cY6uDLfS6*;t_t;?{B3wdmVG3Jd zXFM+z6V09Cw~PpEO*Ag}luHc3WO=)V|e98ZclF9kkE&Mw_eWHKgXFJ&?> z#}P7J1bqVTl%_NMaQJqqlh`wzi1)s(GR$`N-{w4pHsZdT7d6t95n1e9A~W5+P(1w!kvCY)wNOiTk~&q)vCG%{v5NQsypC72tY*ma7emno}iSvxRwD-Y=Ds+&QV`%<=${r zOpWO?HAaa#=jNTJn%lIeLcYcUD#B))0JCn(@ zt3i&etck3VYKj$&mG1MWrt3!&mu`=@sKcr7k%QN@AQx)KLpFHyL*cfUZ{t=}>xlJz z={CxmUdl&hcWUhrms!qTt-EY@+Ds*bEDW`!eRhMD-PZjR&?5^wx zUnV-#f0s#*(htV|s3C~dV4-Q-DRS$_Nuf&l@G<(5h_O&!C4mD{drOcE zkT{1iQeHum$SKTwX+ww0zH&M`RccZ&>E=?mzn^an+RLXs9?!NKavWy3Qx@zs*rRFh zTpYMc4q-CW8XO?nM%b*~uMIM*kUTRR?3Uw%z-x7VgBGHx@Q&GB4IJ9vVjM!dJTez- zPrmVv9mi2YJRoB1xu!99&6|>)&o(i=inGijtXwuQMZTS%53k*1F0MKZuH9z*q@l9d z0=u8~r=e*(W#4XNBxpNr?|?9{MTAFguaB?&U1+ZC-2&mb@F7f8giVJ4lz0Rnru2U$ zfZ#?9aMb-Xbm^QK6!Co0U}9^yhF5pnA*;`Kf6su!(^YaRzPE+yq@-Q%a4 zJ9dRxEjRtX%I~KxyL8O0->3IlLb^kkW_aF{)TbV2$`}!l-D@G`*}o^rP6%+(cDa_79kBkv%xk#@=lA3adCZZah-9WR2Vyl zF!daaggoWC$!0&LYX6WfXMlUuE0nCW$9fBID^~4;s^fIL834qcD4MF!X_(D@LnG`a zY$Grxh-u8!&w92+E^b_C*gxzM_{$Sd=%YCML+$gPHFIvA$Mc@wNv6#tB9<2A_}!rH z>s7z#%=?08PUWB1XSEjV1&u54v(~w|O{cE$(MOco%Fo%B&g%;3t+f@0l{#iV3gS>X ziXjqcm&R!a4I?kCbKoTg=u7G*UG7Hb2wIdZkREa4@mCMpanLwFC(>y~4XK;=z;MO0 zqC32HPuabf|JmY$8Zxqp6q!g3_VY}qRpfTYw%t;HbITPKz~3hIRsocV;Ykm}BeNq` z;}7U&+&xC`LY&AS>oknkQL_7ayJ--W%D@z^UNeGz9m2l?prp#t4nT(rx&CJP*#rOZ6MQK2!H$GNrBu$SO}dJdH2?TV?0M zHGBU&?dfvJU7EOZ@bSE5nSYZ$1?u?2rD4Ibf%?n;6dSLsd} z?lB!C0D*3UDK^l^QM}caR+u0OWiK%bxqlg_Mm`#Q`y4ln!@PF6lG5g|+fCJ$b?XP$ z<7~j$%kDgl-rMh*wJP2-==%E2|KStP3Q^%m;F=_sI0{RqGt$)b@71C^2gD(P$|DJ% zi-ku+iDN4QvVnX&p!1H{1vIL+bt-;$nt43hHkedY$aC78b^7GtJP|O3fEF$tyP!br z+FpNI9353}Zl6PLyb9lDua`{cBs`>jJaM7f2-kcA+?8524&9P&n8eH7hUoFDfnDi) zE94hQVd&)kZV)(_L7B?;I{Nu&Lo6o=p6w(Am7eZvg6rD(he(1ofcAl)vZq;3y{Kck zKm6Tg^O*60A^-Q9VdZ&j@{qJ0{MLLs8m9A_1%-P)oM%Dm*DB0xcRu_j0RcgC9^#T2 z3Ezl*Ltwwpz{BNgkGJ%&)bPkwn@qqFcmi*!8@8&Z&WLRE(Cf1qSB;_fObui3>M)Tp zr$(0ydNYS5j}wx^?2zt{wfpP46z{t{*MNg{VVy9N$-kCofH!7(Z5X@q%V8L|%vCf8 z9+Ey~+gvDAZhSAw>kQZ`4z7^uo zF3eSP@6@&U+_Q4d+;+~78YY8g8<}4;uF@l{A_eKk-l_)&ZvN-m0a^k;BA78 zzj!OItwUn$EG#c|ybIzBq-EeTBAk@`K5=#$aw(D^Yz%4N;6dAk%goCwCTI7{CbEti zHFb<5@QDuRd*wfkdyMlet~abD3%^5^7ZV@|V3*B5-2Tkbk>DUq<$qk5IUdn6!@;kC z=pLhB!_o7C!Z>j;fL!ma_48`~awPmR248Rl7Q_B^gnpdEt$Lm5W_Fwu@KiQaAdo_U z>@(|rN1(lsM&NL2cZ!{5_MmKm`_8KC!2{ep0{d3~XGXYJ09i30M)z-^eM&M?0Q>k- zdIko<*@Etjgq=xhmD@%VHf734y|oKk&yl7NhwG|eclT!sJe+oSPtA3&k*UD>g;mp9 zbAv{e!_7H6xi-KC#AEZ)i`Alp1w<=_BqxB8E0z4*S^pf8OQ{>Gz^UBW6S zHT#@Pk-ee0|11QnVQ6yWFVf7PcFlcW$(!xH<_U-R8x-QD%+ye)w32WjB`j-Z-|M>S zY7WCa(Gp^~dmsiQSSOGZ!3RXH)hC0BKS6k~k|g2x0b)?AAfY31zl z{aE8!ALR>pXPb(3OfH)BK*(^&_6w+-9#Pn&jqdycv03k;oeMLY59-={F5S{Fw$53; z!~`S|H6&OEz7@*ydkoTZ_+t2`pua2vSGYo@k-L%cw?hGizZ2BqLV7QV;DuzslH~Mo z&nZGgZGn^ujW>Ae=w}L^g~zjPNe&mleaGdzLn=>b+lI3*W>iEb`5b2xD#1g7eL*cE)k}(=ZmVWPL zT8H2(4-_yqDO=r|dOFtico7$E)BK8;%{jBk&Dbmw=G4qQj{yJlu}xa#kWC8rr*yt5 z{*WZXdFc6+0vE7h)^U>4palqM!gL~Bya`xXcDZ}+*&M<1F=bmK=X}87fj%s}yM2-B zB_wZGZxSQiN=A1(p@WyTC%Zx7+*MJ1#fdPaJP0{JubJv=X)c4oAE7M2fO`izn|TeJ6kpuT5eI` zfQargS{dsUoJxSaN|}PkScbv#Lf9qP=6e1)LymhE|XTKHUKINLst&4#9DI_v2xVq-;p!0>1!4o0EWlzLhU}r2PWu6 z7c{~%E=&*SBAQxh=AL_5Bzi0nmUTZTak1p<#i;N-b?f9rHu6m zdM)Q(G#HDDz2V;=IJ8}aYVeY}@$SZ$f?C7{;pZzH-I%3-yk~{&u0Icw<4ssK0 zog<>=R7;S?;AsWHIr4Y`yj*dZn>D>Jmusf;9u#x&i?~&L8ycp(nFK|b_%bmw@rAw% z^)8mHb-IEV7QLBq%ZOCKW zN9xH^tns}iAs-|Vx?t?tr#DHz?PqhBCYGF$w=>}a7b^C@==Oq&O)G3+9;Aav6GIT{A z=705Hfsj*sev|VLT(uUZ(qVIni45Lb?vu3uBV7nb)~)0r0eVyv9e z@@S?_LZelT>CX~sTP$;U82HcZ(658EsZt?C!NP|Z@h?|3oDmgJ2ZA%mi{fNHD;~Xn z^%1B>azu&%-Ta%O^+P4MWv!Vf)#5s$!yjQs{R;pArWmYu4LYm_iM#}cOK&P(B_iU> z0?U@%gn-SZ2Fi>LSh+xA0aLAOF*1O1oo9p@D`qL1iOmEde{L@Q_KST^99dJUJ6IAd z7JrSJ67|&WR>XlfcZ`86kkYAr#A#%I#$l@+F{%kMsH+nw5C|bt*uC-XGL3T{o`r~9 zjo+0Xl5vH55j#7QOH*g9uE4ib#3<~X)cmuf=Vbp2yefdeAjbDd9#SILL<`-@oHm-& zo)IEr_0;{JCajSgtSqylj7Lk1@%s?vND15&}hVDNp)K{;rnIPDy!!tjjVunxW0 zT)|A`XhN72KP_4Ne8RnJgWR+2n8qE?CwlOxq*}4MH&yLpL^Gaa!sa2hbn^4H(|U%` zf-VzH0yWBu12XB#7~BBR8|3T+3~-sNGd)*cDip+-pz5UG6fRzqidrt+z^0>L|KuLV z#iaaE!>zNRm%AOR78o~0k^gEcBPyy#tns>SosQ%$bSvviY$@>si1ejbWz~@WIMt@p zSmBAsA>6b?4}B86n|CjN*nZ4 zOhxY9QnT&uXc_~P@QQzfGUrCrTDl1V{cGfBPWg93>=(QUgu^#LzRIOPDkQ&t7vwF# zAUlcqKw5RON89!*Zz>Bt1R?$JjFomIF;U!KQLF}YsrH-Q(>kBnBVrLmK}){35SANx z*S44zB=y%e_A4y6YDU)`#_}}FLEk8h8_*}YHjWhqHaIS8g1l9jf^EB-O^3{AS?avf zb9}Bpe2Y%MzrfvCfmg^aleNGu2`kVli;yvKjnrW5$+{G$3~Ql&3pza^D!NoeZMwgq z-~0YU)1W5~298_s$ zt!ei0YOJv_EUdA4fM};1zz&u-NRsWss(QC7`kSxvFr6qb z0H#A~aQ61z@%Kq$V_jLOeRwG?ctNy#jqHx?z%nJ`RWM%sili9TwiI1E-bou?4c?#| z!I`+U`KffiUs1?In5ox*SYY^C{U|t&7SlRJj@LWlv4M>G5Cog0fUs7=-Q>g8hY{;7 z;9qrPktp*+fZze|NrZ<~$CD1uc2a-+Zy-TYd{$NWnH^TSsdBu0y9KN0(wBr$h*sAR%i$5-awHKc+dZN}9Zm(J$wct?Ex>ScqVLS3#DcGuC(fT4M*Ur9vCl&d4ejcMRJe#^Yq z<#Z&;d*(TKS%oV~4cl#Ij;KBS#y%NNS+thj6Z}0b38}N^VaErQOGqyPT*L9K(eba{ z9YbMSavFLAjgr0D>z7F>B__##kN3^lGBaL2->W{VR9~eyX<=0dbJIH9`ry5D(-rlZ z`Q$sjt5Fk}mzn2pL)_uq%+zC)bE@N+j*+Uk69xmXfu<0N*Tp8i+DLO_lM;7yS0Ggp zD+6rO4!9>9>{kBJ=m(!^+tkdg&3e#tYoDV}S7vrpL*VO_KqI5rF|h?<>c+$Hlj~(cxXniq*vM41 zZ?T|Dud4ayHJ{J*m~b#|2m;@BFGX{=W7clKzcRiYI<(WvbTI5o7>i~vn1<__!Jy9a z16NL1v~ae=lu!afucI#GeP5OzrvLepAw8_uRoavtz`w*3&S`Ki;1ogjz?;hNU+pL- z6Fbsp5Be5D-C&YU_$2t!$sV=! zUi?XN>mj2kFizru@L7g%rT6!w*kWCP&=RZ-CnWXAm@@ zsPDDssl4c%1si0G9lVYX%6o5NmiemuYvXHr^uDE zpA|IwT6bwCx%WVmbd`Tk!58@`mZ}1hd6xtiW{2BAZ8A}JS=5AVPlH<`fmFz0D74jC zb})5n4&>CR=yv~$Hs7(tiG^aa)=#dyAb%Gp9x6cu($ z64c1bu53pF_CP4-x}ICvfy(;6Rns`7wT`_`%2umUz#=qc$~q-tYNq)E${oZ9=mzzv z_aaGQ=+k1*+ljEZP*!{Zg+T&b_Zdn=uAp?+@89@XJix|wra723cZ@o3AVnJsO-gRX zmW`JQi#n)hmZfVy%OESKa9@~{Y^6yuAHCOIyVbm^l@li!g*ls}siGN^z=$5B#M#Mm z>Wi&9(Lhcq@gFFA@Nc2T1d}@<0#f7g%p^RVPYkt{J1!z)rrfYKK zZO{sjMheSDt@mGH!u>JC3BoKsI^#xWOQy2i9(sDU*Ewhj=QI!gr80?OBv6!0-=&u9f*iqO`aH8g2FDjU z8LTKKWWKp>FReUr&%Rgm4H*c`z~itR+?hR?NtggRzUk!l(4j;GPuIx7cVeZq!DSJJ zptgVJl(;M7qG1!*cFZu z7`(_^`+ToXGe1lZ@&U>>=XWF0N=Lk?cD|5@ zgq^ttowi+2-im%Aa~i)g7eA3&v-@0}cK=f1KC>L&)45gq-D;a^wW4N~`Tzc@0HzKa zuJB^Tn<}V{m^Y=HdSI7=Ag3Ind>|-@PDup3f*a5`2&1nSi)oHmeRT&N42G z%Wa!3=PIDzoG)@oyjr%#eOMkA7n}_2Y|84}undH(ryMly@9zs%qPqho!xo#&;07`? zVIZDqdMbOL|J;zb`=2mEZI}0EMWO>|>FmF;f#C`GOr|ZnMTc&QXA79m{<_kV41Qw3 zst(jJS|z?IfZCv$K=Zp+*pc?lKzUIHyV9}qQSKyk&`oQ~_lnxKtWXGfkb zpU$FPXbB!uQ#UtZdmM9|D1{p$`7bxcp`mh>&0jYWh)66*t!kxI)F&E#;#u40aYl-Ui%E z&u#8(pR(ZG>2hwNllEUn6Dm|w%ai&i8s2ABw}XTw1*_+jnt_3d7Gq{ccwU3@YROQT z1}Re^+SP>>b9PRv*;%s;#zWiBOTntcKy~JH?Xq&5I$QrX-te}KVqXl!4LO#wL(M(y{jtHtNN*e~3@A){2D-HqFb!R6qo&YH@nUnefJE6xkXi$Ju zTWX|;;Y?n$u&-VDE6O%_4w3@jR8oyAcfEwwZd@<*6jJME9pZ-7 zyTa?T)Sl~wyOKQ(dVLRVE6vcM8WemoLa-IDCv0SbUxi!3E|#7No#56idRehRR7z3N z-dSu@n`Eds>@*GL=)1%&b0JcCyOm*AbkC?UOlr)@YwB^AjjA;5l)$aeYhmMUzzOw0 z!YuRQ1MngW>?SQFa@2us$&H8liU)2XsDS!X0=xR_jrxHJb|nCg`k@DQ#gB&i0Rg4? z7Y_9!1&YgeM9jPy*faeg(#7tYbz

9E8XSY2)E(Vq?32Bxtg&VLnC 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 QJ&hM32>KVoT7vcf00b!O^8f$< diff --git a/SourceSerifPro-Regular.woff b/SourceSerifPro-Regular.woff deleted file mode 100644 index e8c43b852e10e1556268d6c17b47bd0644d6edec..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 49960 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%0AHnr$&HP)99eOG;&C)H59oX7tVW8CpZqiv(kJ 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 T#x!RM8#a#Gm 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 T`>xjor2he>K@jvWkwJRWB`#{9 diff --git a/rust.css b/rust.css deleted file mode 100644 index cd158283180a2..0000000000000 --- a/rust.css +++ /dev/null @@ -1,407 +0,0 @@ -/** - * Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT - * file at the top-level directory of this distribution and at - * http://rust-lang.org/COPYRIGHT. - * With elements taken from Bootstrap v3.0.2 (MIT licensed). - * - * Licensed under the Apache License, Version 2.0 or the MIT license - * , at your - * option. This file may not be copied, modified, or distributed - * except according to those terms. - */ -@font-face { - font-family: 'Fira Sans'; - font-style: normal; - font-weight: 400; - src: local('Fira Sans'), url("FiraSans-Regular.woff") format('woff'); -} -@font-face { - font-family: 'Fira Sans'; - font-style: normal; - font-weight: 500; - src: local('Fira Sans Medium'), url("FiraSans-Medium.woff") format('woff'); -} -@font-face { - font-family: 'Source Serif Pro'; - font-style: normal; - font-weight: 400; - src: local('Source Serif Pro'), url("SourceSerifPro-Regular.woff") format('woff'); -} -@font-face { - font-family: 'Source Serif Pro'; - font-style: italic; - font-weight: 400; - src: url("Heuristica-Italic.woff") format('woff'); -} -@font-face { - font-family: 'Source Serif Pro'; - font-style: normal; - font-weight: 700; - src: local('Source Serif Pro Bold'), url("SourceSerifPro-Bold.woff") format('woff'); -} -@font-face { - font-family: 'Source Code Pro'; - font-style: normal; - font-weight: 400; - src: local('Source Code Pro'), url("SourceCodePro-Regular.woff") format('woff'); -} - -*:not(body) { - -webkit-box-sizing: border-box; - -moz-box-sizing: border-box; - box-sizing: border-box; -} - -/* General structure */ - -body { - background-color: white; - margin: 0 auto; - padding: 0 15px; - font-family: "Source Serif Pro", Georgia, Times, "Times New Roman", serif; - font-size: 18px; - color: #333; - line-height: 1.428571429; - - -webkit-font-feature-settings: "kern", "liga"; - -moz-font-feature-settings: "kern", "liga"; - font-feature-settings: "kern", "liga"; -} -@media (min-width: 768px) { - body { - max-width: 750px; - } -} - -h1, h2, h3, h4, h5, h6, nav, #versioninfo { - font-family: "Fira Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; -} -h1, h2, h3, h4, h5, h6 { - color: black; - font-weight: 400; - line-height: 1.1; -} -h1, h2, h3 { - margin-top: 20px; - margin-bottom: 15px; -} -h1 { - margin-bottom: 20px; -} -h4, h5, h6 { - margin-top: 12px; - margin-bottom: 10px; - padding: 5px 10px; -} -h5, h6 { - text-decoration: underline; -} - -h1 { - font-size: 28px; - font-weight: 500; - padding: .1em .4em; - border-bottom: 2px solid #ddd; -} -h1.title { - line-height: 1.5em; -} -h2 { - font-size: 26px; - padding: .2em .5em; - border-bottom: 1px solid #ddd; -} -h3 { - font-size: 24px; - padding: .2em .7em; - border-bottom: 1px solid #DDE8FC; -} -h4 { - font-size: 22px; -} -h5 { - font-size: 20px; -} -h6 { - font-size: 18px; -} -@media (min-width: 992px) { - h1 { - font-size: 36px; - } - h2 { - font-size: 30px; - } - h3 { - font-size: 26px; - } -} - -nav { - column-count: 2; - -moz-column-count: 2; - -webkit-column-count: 2; - font-size: 15px; - margin: 0 0 1em 0; -} -p { - margin: 0 0 1em 0; -} - -strong { - font-weight: bold; -} - -em { - font-style: italic; -} - -footer { - border-top: 1px solid #ddd; - font-size: 14.3px; - font-style: italic; - padding-top: 5px; - margin-top: 3em; - margin-bottom: 1em; -} - -/* Links layout */ - -a { - text-decoration: none; - color: #428BCA; - background: transparent; -} -a:hover, a:focus { - color: #2A6496; - text-decoration: underline; -} -a:focus { - outline: thin dotted #333; - outline: 5px auto -webkit-focus-ring-color; - outline-offset: -2px; -} -a:hover, a:active { - outline: 0; -} - -h1 a:link, h1 a:visited, h2 a:link, h2 a:visited, -h3 a:link, h3 a:visited, h4 a:link, h4 a:visited, -h5 a:link, h5 a:visited {color: black;} -h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, -h5 a:hover {text-decoration: none;} - -/* Code */ - -pre, code { - font-family: "Source Code Pro", Menlo, Monaco, Consolas, "DejaVu Sans Mono", monospace; - word-wrap: break-word; -} -pre { - border-left: 2px solid #eee; - white-space: pre-wrap; - padding: 14px; - padding-right: 0; - margin: 20px 0; - font-size: 13px; - word-break: break-all; -} -code { - padding: 0 2px; - color: #8D1A38; -} -pre code { - padding: 0; - font-size: inherit; - color: inherit; -} - -a > code { - color: #428BCA; -} - -/* Code highlighting */ -pre.rust .kw { color: #8959A8; } -pre.rust .kw-2, pre.rust .prelude-ty { color: #4271AE; } -pre.rust .number, pre.rust .string { color: #718C00; } -pre.rust .self, pre.rust .boolval, pre.rust .prelude-val, -pre.rust .attribute, pre.rust .attribute .ident { color: #C82829; } -pre.rust .comment { color: #8E908C; } -pre.rust .doccomment { color: #4D4D4C; } -pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; } -pre.rust .lifetime { color: #B76514; } - -/* The rest */ - -#versioninfo { - text-align: center; - margin: 0.5em; - font-size: 1.1em; -} -@media (min-width: 992px) { - #versioninfo { - font-size: 0.8em; - position: fixed; - bottom: 0px; - right: 0px; - } - .white-sticker { - background-color: #fff; - margin: 2px; - padding: 0 2px; - border-radius: .2em; - } -} -#versioninfo a.hash { - color: gray; - font-size: 80%; -} - -blockquote { - color: #000; - margin: 20px 0; - padding: 15px 20px; - background-color: #f2f7f9; - border-top: .1em solid #e5eef2; - border-bottom: .1em solid #e5eef2; -} -blockquote p { - font-size: 17px; - font-weight: 300; - line-height: 1.4; -} -blockquote p:last-child { - margin-bottom: 0; -} - -ul, ol { - padding-left: 25px; -} -ul ul, ol ul, ul ol, ol ol { - margin-bottom: 0; -} -dl { - margin-bottom: 20px; -} -dd { - margin-left: 0; -} - -nav ul { - list-style-type: none; - margin: 0; - padding-left: 0px; -} - -/* Only display one level of hierarchy in the TOC */ -nav ul ul { - display: none; -} - -sub, -sup { - font-size: 75%; - line-height: 0; - position: relative; -} - -hr { - margin-top: 20px; - margin-bottom: 20px; - border: 0; - border-top: 1px solid #eeeeee; -} - -table { - border-collapse: collapse; - border-spacing: 0; - overflow-x: auto; - display: block; -} - -table tr.odd { - background: #eee; -} - -table td, -table th { - border: 1px solid #ddd; - padding: 5px; -} - -/* Code snippets */ - -.rusttest { display: none; } -pre.rust { position: relative; } -.test-arrow { - display: inline-block; - position: absolute; - top: 0; - right: 10px; - font-size: 150%; - -webkit-transform: scaleX(-1); - transform: scaleX(-1); -} - -.unstable-feature { - border: 2px solid red; - padding: 5px; -} - -@media (min-width: 1170px) { - pre { - font-size: 15px; - } -} - -@media print { - * { - text-shadow: none !important; - color: #000 !important; - background: transparent !important; - box-shadow: none !important; - } - a, a:visited { - text-decoration: underline; - } - p a[href]:after { - content: " (" attr(href) ")"; - } - footer a[href]:after { - content: ""; - } - a[href^="javascript:"]:after, a[href^="#"]:after { - content: ""; - } - pre, blockquote { - border: 1px solid #999; - page-break-inside: avoid; - } - @page { - margin: 2cm .5cm; - } - h1:not(.title), h2, h3 { - border-bottom: 0px none; - } - p, h2, h3 { - orphans: 3; - widows: 3; - } - h2, h3 { - page-break-after: avoid; - } - table { - border-collapse: collapse !important; - } - table td, table th { - background-color: #fff !important; - } -} - -#keyword-table-marker + table thead { display: none; } -#keyword-table-marker + table td { border: none; } -#keyword-table-marker + table { - margin-left: 2em; - margin-bottom: 1em; -} From a54e64b3c41103c4f6ab840d8ddd3a56ec6b5da8 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 23:14:57 -0700 Subject: [PATCH 069/104] move everything to tarpl --- README.md => src/doc/tarpl/README.md | 0 SUMMARY.md => src/doc/tarpl/SUMMARY.md | 0 arc-and-mutex.md => src/doc/tarpl/arc-and-mutex.md | 0 atomics.md => src/doc/tarpl/atomics.md | 0 casts.md => src/doc/tarpl/casts.md | 0 checked-uninit.md => src/doc/tarpl/checked-uninit.md | 0 coercions.md => src/doc/tarpl/coercions.md | 0 concurrency.md => src/doc/tarpl/concurrency.md | 0 constructors.md => src/doc/tarpl/constructors.md | 0 conversions.md => src/doc/tarpl/conversions.md | 0 data.md => src/doc/tarpl/data.md | 0 destructors.md => src/doc/tarpl/destructors.md | 0 dot-operator.md => src/doc/tarpl/dot-operator.md | 0 drop-flags.md => src/doc/tarpl/drop-flags.md | 0 exception-safety.md => src/doc/tarpl/exception-safety.md | 0 exotic-sizes.md => src/doc/tarpl/exotic-sizes.md | 0 hrtb.md => src/doc/tarpl/hrtb.md | 0 leaking.md => src/doc/tarpl/leaking.md | 0 lifetime-elision.md => src/doc/tarpl/lifetime-elision.md | 0 lifetime-misc.md => src/doc/tarpl/lifetime-misc.md | 0 lifetime-mismatch.md => src/doc/tarpl/lifetime-mismatch.md | 0 lifetimes.md => src/doc/tarpl/lifetimes.md | 0 meet-safe-and-unsafe.md => src/doc/tarpl/meet-safe-and-unsafe.md | 0 other-reprs.md => src/doc/tarpl/other-reprs.md | 0 ownership.md => src/doc/tarpl/ownership.md | 0 poisoning.md => src/doc/tarpl/poisoning.md | 0 races.md => src/doc/tarpl/races.md | 0 raii.md => src/doc/tarpl/raii.md | 0 references.md => src/doc/tarpl/references.md | 0 repr-rust.md => src/doc/tarpl/repr-rust.md | 0 safe-unsafe-meaning.md => src/doc/tarpl/safe-unsafe-meaning.md | 0 send-and-sync.md => src/doc/tarpl/send-and-sync.md | 0 subtyping.md => src/doc/tarpl/subtyping.md | 0 transmutes.md => src/doc/tarpl/transmutes.md | 0 unbounded-lifetimes.md => src/doc/tarpl/unbounded-lifetimes.md | 0 unchecked-uninit.md => src/doc/tarpl/unchecked-uninit.md | 0 uninitialized.md => src/doc/tarpl/uninitialized.md | 0 unwinding.md => src/doc/tarpl/unwinding.md | 0 vec-alloc.md => src/doc/tarpl/vec-alloc.md | 0 vec-dealloc.md => src/doc/tarpl/vec-dealloc.md | 0 vec-deref.md => src/doc/tarpl/vec-deref.md | 0 vec-drain.md => src/doc/tarpl/vec-drain.md | 0 vec-final.md => src/doc/tarpl/vec-final.md | 0 vec-insert-remove.md => src/doc/tarpl/vec-insert-remove.md | 0 vec-into-iter.md => src/doc/tarpl/vec-into-iter.md | 0 vec-layout.md => src/doc/tarpl/vec-layout.md | 0 vec-push-pop.md => src/doc/tarpl/vec-push-pop.md | 0 vec.md => src/doc/tarpl/vec.md | 0 working-with-unsafe.md => src/doc/tarpl/working-with-unsafe.md | 0 49 files changed, 0 insertions(+), 0 deletions(-) rename README.md => src/doc/tarpl/README.md (100%) rename SUMMARY.md => src/doc/tarpl/SUMMARY.md (100%) rename arc-and-mutex.md => src/doc/tarpl/arc-and-mutex.md (100%) rename atomics.md => src/doc/tarpl/atomics.md (100%) rename casts.md => src/doc/tarpl/casts.md (100%) rename checked-uninit.md => src/doc/tarpl/checked-uninit.md (100%) rename coercions.md => src/doc/tarpl/coercions.md (100%) rename concurrency.md => src/doc/tarpl/concurrency.md (100%) rename constructors.md => src/doc/tarpl/constructors.md (100%) rename conversions.md => src/doc/tarpl/conversions.md (100%) rename data.md => src/doc/tarpl/data.md (100%) rename destructors.md => src/doc/tarpl/destructors.md (100%) rename dot-operator.md => src/doc/tarpl/dot-operator.md (100%) rename drop-flags.md => src/doc/tarpl/drop-flags.md (100%) rename exception-safety.md => src/doc/tarpl/exception-safety.md (100%) rename exotic-sizes.md => src/doc/tarpl/exotic-sizes.md (100%) rename hrtb.md => src/doc/tarpl/hrtb.md (100%) rename leaking.md => src/doc/tarpl/leaking.md (100%) rename lifetime-elision.md => src/doc/tarpl/lifetime-elision.md (100%) rename lifetime-misc.md => src/doc/tarpl/lifetime-misc.md (100%) rename lifetime-mismatch.md => src/doc/tarpl/lifetime-mismatch.md (100%) rename lifetimes.md => src/doc/tarpl/lifetimes.md (100%) rename meet-safe-and-unsafe.md => src/doc/tarpl/meet-safe-and-unsafe.md (100%) rename other-reprs.md => src/doc/tarpl/other-reprs.md (100%) rename ownership.md => src/doc/tarpl/ownership.md (100%) rename poisoning.md => src/doc/tarpl/poisoning.md (100%) rename races.md => src/doc/tarpl/races.md (100%) rename raii.md => src/doc/tarpl/raii.md (100%) rename references.md => src/doc/tarpl/references.md (100%) rename repr-rust.md => src/doc/tarpl/repr-rust.md (100%) rename safe-unsafe-meaning.md => src/doc/tarpl/safe-unsafe-meaning.md (100%) rename send-and-sync.md => src/doc/tarpl/send-and-sync.md (100%) rename subtyping.md => src/doc/tarpl/subtyping.md (100%) rename transmutes.md => src/doc/tarpl/transmutes.md (100%) rename unbounded-lifetimes.md => src/doc/tarpl/unbounded-lifetimes.md (100%) rename unchecked-uninit.md => src/doc/tarpl/unchecked-uninit.md (100%) rename uninitialized.md => src/doc/tarpl/uninitialized.md (100%) rename unwinding.md => src/doc/tarpl/unwinding.md (100%) rename vec-alloc.md => src/doc/tarpl/vec-alloc.md (100%) rename vec-dealloc.md => src/doc/tarpl/vec-dealloc.md (100%) rename vec-deref.md => src/doc/tarpl/vec-deref.md (100%) rename vec-drain.md => src/doc/tarpl/vec-drain.md (100%) rename vec-final.md => src/doc/tarpl/vec-final.md (100%) rename vec-insert-remove.md => src/doc/tarpl/vec-insert-remove.md (100%) rename vec-into-iter.md => src/doc/tarpl/vec-into-iter.md (100%) rename vec-layout.md => src/doc/tarpl/vec-layout.md (100%) rename vec-push-pop.md => src/doc/tarpl/vec-push-pop.md (100%) rename vec.md => src/doc/tarpl/vec.md (100%) rename working-with-unsafe.md => src/doc/tarpl/working-with-unsafe.md (100%) diff --git a/README.md b/src/doc/tarpl/README.md similarity index 100% rename from README.md rename to src/doc/tarpl/README.md diff --git a/SUMMARY.md b/src/doc/tarpl/SUMMARY.md similarity index 100% rename from SUMMARY.md rename to src/doc/tarpl/SUMMARY.md diff --git a/arc-and-mutex.md b/src/doc/tarpl/arc-and-mutex.md similarity index 100% rename from arc-and-mutex.md rename to src/doc/tarpl/arc-and-mutex.md diff --git a/atomics.md b/src/doc/tarpl/atomics.md similarity index 100% rename from atomics.md rename to src/doc/tarpl/atomics.md diff --git a/casts.md b/src/doc/tarpl/casts.md similarity index 100% rename from casts.md rename to src/doc/tarpl/casts.md diff --git a/checked-uninit.md b/src/doc/tarpl/checked-uninit.md similarity index 100% rename from checked-uninit.md rename to src/doc/tarpl/checked-uninit.md diff --git a/coercions.md b/src/doc/tarpl/coercions.md similarity index 100% rename from coercions.md rename to src/doc/tarpl/coercions.md diff --git a/concurrency.md b/src/doc/tarpl/concurrency.md similarity index 100% rename from concurrency.md rename to src/doc/tarpl/concurrency.md diff --git a/constructors.md b/src/doc/tarpl/constructors.md similarity index 100% rename from constructors.md rename to src/doc/tarpl/constructors.md diff --git a/conversions.md b/src/doc/tarpl/conversions.md similarity index 100% rename from conversions.md rename to src/doc/tarpl/conversions.md diff --git a/data.md b/src/doc/tarpl/data.md similarity index 100% rename from data.md rename to src/doc/tarpl/data.md diff --git a/destructors.md b/src/doc/tarpl/destructors.md similarity index 100% rename from destructors.md rename to src/doc/tarpl/destructors.md diff --git a/dot-operator.md b/src/doc/tarpl/dot-operator.md similarity index 100% rename from dot-operator.md rename to src/doc/tarpl/dot-operator.md diff --git a/drop-flags.md b/src/doc/tarpl/drop-flags.md similarity index 100% rename from drop-flags.md rename to src/doc/tarpl/drop-flags.md diff --git a/exception-safety.md b/src/doc/tarpl/exception-safety.md similarity index 100% rename from exception-safety.md rename to src/doc/tarpl/exception-safety.md diff --git a/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md similarity index 100% rename from exotic-sizes.md rename to src/doc/tarpl/exotic-sizes.md diff --git a/hrtb.md b/src/doc/tarpl/hrtb.md similarity index 100% rename from hrtb.md rename to src/doc/tarpl/hrtb.md diff --git a/leaking.md b/src/doc/tarpl/leaking.md similarity index 100% rename from leaking.md rename to src/doc/tarpl/leaking.md diff --git a/lifetime-elision.md b/src/doc/tarpl/lifetime-elision.md similarity index 100% rename from lifetime-elision.md rename to src/doc/tarpl/lifetime-elision.md diff --git a/lifetime-misc.md b/src/doc/tarpl/lifetime-misc.md similarity index 100% rename from lifetime-misc.md rename to src/doc/tarpl/lifetime-misc.md diff --git a/lifetime-mismatch.md b/src/doc/tarpl/lifetime-mismatch.md similarity index 100% rename from lifetime-mismatch.md rename to src/doc/tarpl/lifetime-mismatch.md diff --git a/lifetimes.md b/src/doc/tarpl/lifetimes.md similarity index 100% rename from lifetimes.md rename to src/doc/tarpl/lifetimes.md diff --git a/meet-safe-and-unsafe.md b/src/doc/tarpl/meet-safe-and-unsafe.md similarity index 100% rename from meet-safe-and-unsafe.md rename to src/doc/tarpl/meet-safe-and-unsafe.md diff --git a/other-reprs.md b/src/doc/tarpl/other-reprs.md similarity index 100% rename from other-reprs.md rename to src/doc/tarpl/other-reprs.md diff --git a/ownership.md b/src/doc/tarpl/ownership.md similarity index 100% rename from ownership.md rename to src/doc/tarpl/ownership.md diff --git a/poisoning.md b/src/doc/tarpl/poisoning.md similarity index 100% rename from poisoning.md rename to src/doc/tarpl/poisoning.md diff --git a/races.md b/src/doc/tarpl/races.md similarity index 100% rename from races.md rename to src/doc/tarpl/races.md diff --git a/raii.md b/src/doc/tarpl/raii.md similarity index 100% rename from raii.md rename to src/doc/tarpl/raii.md diff --git a/references.md b/src/doc/tarpl/references.md similarity index 100% rename from references.md rename to src/doc/tarpl/references.md diff --git a/repr-rust.md b/src/doc/tarpl/repr-rust.md similarity index 100% rename from repr-rust.md rename to src/doc/tarpl/repr-rust.md diff --git a/safe-unsafe-meaning.md b/src/doc/tarpl/safe-unsafe-meaning.md similarity index 100% rename from safe-unsafe-meaning.md rename to src/doc/tarpl/safe-unsafe-meaning.md diff --git a/send-and-sync.md b/src/doc/tarpl/send-and-sync.md similarity index 100% rename from send-and-sync.md rename to src/doc/tarpl/send-and-sync.md diff --git a/subtyping.md b/src/doc/tarpl/subtyping.md similarity index 100% rename from subtyping.md rename to src/doc/tarpl/subtyping.md diff --git a/transmutes.md b/src/doc/tarpl/transmutes.md similarity index 100% rename from transmutes.md rename to src/doc/tarpl/transmutes.md diff --git a/unbounded-lifetimes.md b/src/doc/tarpl/unbounded-lifetimes.md similarity index 100% rename from unbounded-lifetimes.md rename to src/doc/tarpl/unbounded-lifetimes.md diff --git a/unchecked-uninit.md b/src/doc/tarpl/unchecked-uninit.md similarity index 100% rename from unchecked-uninit.md rename to src/doc/tarpl/unchecked-uninit.md diff --git a/uninitialized.md b/src/doc/tarpl/uninitialized.md similarity index 100% rename from uninitialized.md rename to src/doc/tarpl/uninitialized.md diff --git a/unwinding.md b/src/doc/tarpl/unwinding.md similarity index 100% rename from unwinding.md rename to src/doc/tarpl/unwinding.md diff --git a/vec-alloc.md b/src/doc/tarpl/vec-alloc.md similarity index 100% rename from vec-alloc.md rename to src/doc/tarpl/vec-alloc.md diff --git a/vec-dealloc.md b/src/doc/tarpl/vec-dealloc.md similarity index 100% rename from vec-dealloc.md rename to src/doc/tarpl/vec-dealloc.md diff --git a/vec-deref.md b/src/doc/tarpl/vec-deref.md similarity index 100% rename from vec-deref.md rename to src/doc/tarpl/vec-deref.md diff --git a/vec-drain.md b/src/doc/tarpl/vec-drain.md similarity index 100% rename from vec-drain.md rename to src/doc/tarpl/vec-drain.md diff --git a/vec-final.md b/src/doc/tarpl/vec-final.md similarity index 100% rename from vec-final.md rename to src/doc/tarpl/vec-final.md diff --git a/vec-insert-remove.md b/src/doc/tarpl/vec-insert-remove.md similarity index 100% rename from vec-insert-remove.md rename to src/doc/tarpl/vec-insert-remove.md diff --git a/vec-into-iter.md b/src/doc/tarpl/vec-into-iter.md similarity index 100% rename from vec-into-iter.md rename to src/doc/tarpl/vec-into-iter.md diff --git a/vec-layout.md b/src/doc/tarpl/vec-layout.md similarity index 100% rename from vec-layout.md rename to src/doc/tarpl/vec-layout.md diff --git a/vec-push-pop.md b/src/doc/tarpl/vec-push-pop.md similarity index 100% rename from vec-push-pop.md rename to src/doc/tarpl/vec-push-pop.md diff --git a/vec.md b/src/doc/tarpl/vec.md similarity index 100% rename from vec.md rename to src/doc/tarpl/vec.md diff --git a/working-with-unsafe.md b/src/doc/tarpl/working-with-unsafe.md similarity index 100% rename from working-with-unsafe.md rename to src/doc/tarpl/working-with-unsafe.md From 04578f6611ca5da47b23fa0d10381f7858b3a325 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 23:31:52 -0700 Subject: [PATCH 070/104] update build to make tarpl --- mk/docs.mk | 9 ++++++++- mk/tests.mk | 3 ++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/mk/docs.mk b/mk/docs.mk index 617c3ddf8dec1..3acc3c68b8fd1 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -77,7 +77,7 @@ ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE) D := $(S)src/doc -DOC_TARGETS := trpl style error-index +DOC_TARGETS := trpl tarpl style error-index COMPILER_DOC_TARGETS := DOC_L10N_TARGETS := @@ -287,6 +287,13 @@ doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/ $(Q)rm -rf doc/book $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book +tarpl: doc/adv-book/index.html + +doc/adv-book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/tarpl/*.md) | doc/ + @$(call E, rustbook: $@) + $(Q)rm -rf doc/adv-book + $(Q)$(RUSTBOOK) build $(S)src/doc/tarpl doc/adv-book + style: doc/style/index.html doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/ diff --git a/mk/tests.mk b/mk/tests.mk index 185cc9b2f4c58..c0962a1b0e78b 100644 --- a/mk/tests.mk +++ b/mk/tests.mk @@ -162,7 +162,8 @@ $(foreach doc,$(DOCS), \ $(eval $(call DOCTEST,md-$(doc),$(S)src/doc/$(doc).md))) $(foreach file,$(wildcard $(S)src/doc/trpl/*.md), \ $(eval $(call DOCTEST,$(file:$(S)src/doc/trpl/%.md=trpl-%),$(file)))) - +$(foreach file,$(wildcard $(S)src/doc/tarpl/*.md), \ + $(eval $(call DOCTEST,$(file:$(S)src/doc/tarpl/%.md=tarpl-%),$(file)))) ###################################################################### # Main test targets ###################################################################### From dba548d3634d1f69b6210b642e700c2c41e69ce9 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 14 Jul 2015 00:26:08 -0700 Subject: [PATCH 071/104] fix via mdinger --- src/doc/tarpl/repr-rust.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/tarpl/repr-rust.md index caf60bed8c53b..a1f5f29f8d85e 100644 --- a/src/doc/tarpl/repr-rust.md +++ b/src/doc/tarpl/repr-rust.md @@ -109,7 +109,7 @@ struct FooRepr { And indeed this is approximately how it would be laid out in general (modulo the size and position of `tag`). However there are several cases where -such a representation is ineffiecient. The classic case of this is Rust's +such a representation is inefficient. The classic case of this is Rust's "null pointer optimization". Given a pointer that is known to not be null (e.g. `&u32`), an enum can *store* a discriminant bit *inside* the pointer by using null as a special value. The net result is that @@ -121,4 +121,4 @@ nested enums pooling their tags into a single descriminant, as they are by definition known to have a limited range of valid values. In principle enums can use fairly elaborate algorithms to cache bits throughout nested types with special constrained representations. As such it is *especially* desirable that -we leave enum layout unspecified today. \ No newline at end of file +we leave enum layout unspecified today. From 58f6f2d57a4d0a62f17003facd0d2406da75a035 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 14 Jul 2015 09:56:10 -0700 Subject: [PATCH 072/104] nits and realigning --- src/doc/tarpl/README.md | 6 +- src/doc/tarpl/arc-and-mutex.md | 2 +- src/doc/tarpl/atomics.md | 161 +++++++++++------------ src/doc/tarpl/casts.md | 27 ++-- src/doc/tarpl/checked-uninit.md | 56 ++++---- src/doc/tarpl/constructors.md | 30 +++-- src/doc/tarpl/conversions.md | 16 +-- src/doc/tarpl/destructors.md | 127 +++++++++--------- src/doc/tarpl/drop-flags.md | 56 ++++---- src/doc/tarpl/exception-safety.md | 13 +- src/doc/tarpl/exotic-sizes.md | 52 ++++---- src/doc/tarpl/leaking.md | 211 +++++++++++++++--------------- src/doc/tarpl/other-reprs.md | 54 ++++---- src/doc/tarpl/references.md | 108 +++++++-------- src/doc/tarpl/send-and-sync.md | 63 ++++----- 15 files changed, 501 insertions(+), 481 deletions(-) diff --git a/src/doc/tarpl/README.md b/src/doc/tarpl/README.md index 874f6f2ac6121..0b627737138ad 100644 --- a/src/doc/tarpl/README.md +++ b/src/doc/tarpl/README.md @@ -34,6 +34,6 @@ Due to the nature of advanced Rust programming, we will be spending a lot of tim talking about *safety* and *guarantees*. In particular, a significant portion of the book will be dedicated to correctly writing and understanding Unsafe Rust. -[trpl]: https://doc.rust-lang.org/book/ -[The stack and heap]: https://doc.rust-lang.org/book/the-stack-and-the-heap.html -[Basic Rust]: https://doc.rust-lang.org/book/syntax-and-semantics.html +[trpl]: ../book/ +[The stack and heap]: ../book/the-stack-and-the-heap.html +[Basic Rust]: ../book/syntax-and-semantics.html diff --git a/src/doc/tarpl/arc-and-mutex.md b/src/doc/tarpl/arc-and-mutex.md index d28180fa9cf58..fcafe55e409b8 100644 --- a/src/doc/tarpl/arc-and-mutex.md +++ b/src/doc/tarpl/arc-and-mutex.md @@ -1,6 +1,6 @@ % Implementing Arc and Mutex -Knowing the theory is all fine and good, but the *best* was to understand +Knowing the theory is all fine and good, but the *best* way to understand something is to use it. To better understand atomics and interior mutability, we'll be implementing versions of the standard library's Arc and Mutex types. diff --git a/src/doc/tarpl/atomics.md b/src/doc/tarpl/atomics.md index 82e69dd2e13fc..8395b22c8d8e8 100644 --- a/src/doc/tarpl/atomics.md +++ b/src/doc/tarpl/atomics.md @@ -2,21 +2,22 @@ Rust pretty blatantly just inherits C11's memory model for atomics. This is not due this model being particularly excellent or easy to understand. Indeed, this -model is quite complex and known to have [several flaws][C11-busted]. Rather, -it is a pragmatic concession to the fact that *everyone* is pretty bad at modeling +model is quite complex and known to have [several flaws][C11-busted]. Rather, it +is a pragmatic concession to the fact that *everyone* is pretty bad at modeling atomics. At very least, we can benefit from existing tooling and research around C. Trying to fully explain the model in this book is fairly hopeless. It's defined -in terms of madness-inducing causality graphs that require a full book to properly -understand in a practical way. If you want all the nitty-gritty details, you -should check out [C's specification (Section 7.17)][C11-model]. Still, we'll try -to cover the basics and some of the problems Rust developers face. +in terms of madness-inducing causality graphs that require a full book to +properly understand in a practical way. If you want all the nitty-gritty +details, you should check out [C's specification (Section 7.17)][C11-model]. +Still, we'll try to cover the basics and some of the problems Rust developers +face. -The C11 memory model is fundamentally about trying to bridge the gap between -the semantics we want, the optimizations compilers want, and the inconsistent -chaos our hardware wants. *We* would like to just write programs and have them -do exactly what we said but, you know, *fast*. Wouldn't that be great? +The C11 memory model is fundamentally about trying to bridge the gap between the +semantics we want, the optimizations compilers want, and the inconsistent chaos +our hardware wants. *We* would like to just write programs and have them do +exactly what we said but, you know, *fast*. Wouldn't that be great? @@ -41,13 +42,14 @@ x = 2; y = 3; ``` -This has inverted the order of events *and* completely eliminated one event. From -a single-threaded perspective this is completely unobservable: after all the -statements have executed we are in exactly the same state. But if our program is -multi-threaded, we may have been relying on `x` to *actually* be assigned to 1 before -`y` was assigned. We would *really* like the compiler to be able to make these kinds -of optimizations, because they can seriously improve performance. On the other hand, -we'd really like to be able to depend on our program *doing the thing we said*. +This has inverted the order of events *and* completely eliminated one event. +From a single-threaded perspective this is completely unobservable: after all +the statements have executed we are in exactly the same state. But if our +program is multi-threaded, we may have been relying on `x` to *actually* be +assigned to 1 before `y` was assigned. We would *really* like the compiler to be +able to make these kinds of optimizations, because they can seriously improve +performance. On the other hand, we'd really like to be able to depend on our +program *doing the thing we said*. @@ -55,19 +57,20 @@ we'd really like to be able to depend on our program *doing the thing we said*. # Hardware Reordering On the other hand, even if the compiler totally understood what we wanted and -respected our wishes, our *hardware* might instead get us in trouble. Trouble comes -from CPUs in the form of memory hierarchies. There is indeed a global shared memory -space somewhere in your hardware, but from the perspective of each CPU core it is -*so very far away* and *so very slow*. Each CPU would rather work with its local -cache of the data and only go through all the *anguish* of talking to shared -memory *only* when it doesn't actually have that memory in cache. +respected our wishes, our *hardware* might instead get us in trouble. Trouble +comes from CPUs in the form of memory hierarchies. There is indeed a global +shared memory space somewhere in your hardware, but from the perspective of each +CPU core it is *so very far away* and *so very slow*. Each CPU would rather work +with its local cache of the data and only go through all the *anguish* of +talking to shared memory *only* when it doesn't actually have that memory in +cache. After all, that's the whole *point* of the cache, right? If every read from the cache had to run back to shared memory to double check that it hadn't changed, what would the point be? The end result is that the hardware doesn't guarantee -that events that occur in the same order on *one* thread, occur in the same order -on *another* thread. To guarantee this, we must issue special instructions to -the CPU telling it to be a bit less smart. +that events that occur in the same order on *one* thread, occur in the same +order on *another* thread. To guarantee this, we must issue special instructions +to the CPU telling it to be a bit less smart. For instance, say we convince the compiler to emit this logic: @@ -82,27 +85,27 @@ x = 1; y *= 2; Ideally this program has 2 possible final states: -* `y = 3`: (thread 2 did the check before thread 1 completed) -* `y = 6`: (thread 2 did the check after thread 1 completed) +* `y = 3`: (thread 2 did the check before thread 1 completed) y = 6`: (thread 2 +* `did the check after thread 1 completed) However there's a third potential state that the hardware enables: * `y = 2`: (thread 2 saw `x = 2`, but not `y = 3`, and then overwrote `y = 3`) It's worth noting that different kinds of CPU provide different guarantees. It -is common to seperate hardware into two categories: strongly-ordered and weakly- -ordered. Most notably x86/64 provides strong ordering guarantees, while ARM and -provides weak ordering guarantees. This has two consequences for -concurrent programming: +is common to separate hardware into two categories: strongly-ordered and weakly- +ordered. Most notably x86/64 provides strong ordering guarantees, while ARM +provides weak ordering guarantees. This has two consequences for concurrent +programming: * Asking for stronger guarantees on strongly-ordered hardware may be cheap or even *free* because they already provide strong guarantees unconditionally. Weaker guarantees may only yield performance wins on weakly-ordered hardware. -* Asking for guarantees that are *too* weak on strongly-ordered hardware - is more likely to *happen* to work, even though your program is strictly - incorrect. If possible, concurrent algorithms should be tested on - weakly-ordered hardware. +* Asking for guarantees that are *too* weak on strongly-ordered hardware is + more likely to *happen* to work, even though your program is strictly + incorrect. If possible, concurrent algorithms should be tested on weakly- + ordered hardware. @@ -110,58 +113,54 @@ concurrent programming: # Data Accesses -The C11 memory model attempts to bridge the gap by allowing us to talk about -the *causality* of our program. Generally, this is by establishing a -*happens before* relationships between parts of the program and the threads -that are running them. This gives the hardware and compiler room to optimize the -program more aggressively where a strict happens-before relationship isn't -established, but forces them to be more careful where one *is* established. -The way we communicate these relationships are through *data accesses* and -*atomic accesses*. +The C11 memory model attempts to bridge the gap by allowing us to talk about the +*causality* of our program. Generally, this is by establishing a *happens +before* relationships between parts of the program and the threads that are +running them. This gives the hardware and compiler room to optimize the program +more aggressively where a strict happens-before relationship isn't established, +but forces them to be more careful where one *is* established. The way we +communicate these relationships are through *data accesses* and *atomic +accesses*. Data accesses are the bread-and-butter of the programming world. They are fundamentally unsynchronized and compilers are free to aggressively optimize -them. In particular, data accesses are free to be reordered by the compiler -on the assumption that the program is single-threaded. The hardware is also free -to propagate the changes made in data accesses to other threads -as lazily and inconsistently as it wants. Mostly critically, data accesses are -how data races happen. Data accesses are very friendly to the hardware and -compiler, but as we've seen they offer *awful* semantics to try to -write synchronized code with. Actually, that's too weak. *It is literally -impossible to write correct synchronized code using only data accesses*. +them. In particular, data accesses are free to be reordered by the compiler on +the assumption that the program is single-threaded. The hardware is also free to +propagate the changes made in data accesses to other threads as lazily and +inconsistently as it wants. Mostly critically, data accesses are how data races +happen. Data accesses are very friendly to the hardware and compiler, but as +we've seen they offer *awful* semantics to try to write synchronized code with. +Actually, that's too weak. *It is literally impossible to write correct +synchronized code using only data accesses*. Atomic accesses are how we tell the hardware and compiler that our program is -multi-threaded. Each atomic access can be marked with -an *ordering* that specifies what kind of relationship it establishes with -other accesses. In practice, this boils down to telling the compiler and hardware -certain things they *can't* do. For the compiler, this largely revolves -around re-ordering of instructions. For the hardware, this largely revolves -around how writes are propagated to other threads. The set of orderings Rust -exposes are: - -* Sequentially Consistent (SeqCst) -* Release -* Acquire -* Relaxed +multi-threaded. Each atomic access can be marked with an *ordering* that +specifies what kind of relationship it establishes with other accesses. In +practice, this boils down to telling the compiler and hardware certain things +they *can't* do. For the compiler, this largely revolves around re-ordering of +instructions. For the hardware, this largely revolves around how writes are +propagated to other threads. The set of orderings Rust exposes are: + +* Sequentially Consistent (SeqCst) Release Acquire Relaxed (Note: We explicitly do not expose the C11 *consume* ordering) -TODO: negative reasoning vs positive reasoning? -TODO: "can't forget to synchronize" +TODO: negative reasoning vs positive reasoning? TODO: "can't forget to +synchronize" # Sequentially Consistent Sequentially Consistent is the most powerful of all, implying the restrictions -of all other orderings. Intuitively, a sequentially consistent operation *cannot* -be reordered: all accesses on one thread that happen before and after it *stay* -before and after it. A data-race-free program that uses only sequentially consistent -atomics and data accesses has the very nice property that there is a single global -execution of the program's instructions that all threads agree on. This execution -is also particularly nice to reason about: it's just an interleaving of each thread's -individual executions. This *does not* hold if you start using the weaker atomic -orderings. +of all other orderings. Intuitively, a sequentially consistent operation +*cannot* be reordered: all accesses on one thread that happen before and after a +SeqCst access *stay* before and after it. A data-race-free program that uses +only sequentially consistent atomics and data accesses has the very nice +property that there is a single global execution of the program's instructions +that all threads agree on. This execution is also particularly nice to reason +about: it's just an interleaving of each thread's individual executions. This +*does not* hold if you start using the weaker atomic orderings. The relative developer-friendliness of sequential consistency doesn't come for free. Even on strongly-ordered platforms sequential consistency involves @@ -173,26 +172,26 @@ confident about the other memory orders. Having your program run a bit slower than it needs to is certainly better than it running incorrectly! It's also *mechanically* trivial to downgrade atomic operations to have a weaker consistency later on. Just change `SeqCst` to e.g. `Relaxed` and you're done! Of -course, proving that this transformation is *correct* is whole other matter. +course, proving that this transformation is *correct* is a whole other matter. # Acquire-Release -Acquire and Release are largely intended to be paired. Their names hint at -their use case: they're perfectly suited for acquiring and releasing locks, -and ensuring that critical sections don't overlap. +Acquire and Release are largely intended to be paired. Their names hint at their +use case: they're perfectly suited for acquiring and releasing locks, and +ensuring that critical sections don't overlap. Intuitively, an acquire access ensures that every access after it *stays* after it. However operations that occur before an acquire are free to be reordered to occur after it. Similarly, a release access ensures that every access before it -*stays* before it. However operations that occur after a release are free to -be reordered to occur before it. +*stays* before it. However operations that occur after a release are free to be +reordered to occur before it. When thread A releases a location in memory and then thread B subsequently acquires *the same* location in memory, causality is established. Every write -that happened *before* A's release will be observed by B *after* it's release. +that happened *before* A's release will be observed by B *after* its release. However no causality is established with any other threads. Similarly, no causality is established if A and B access *different* locations in memory. diff --git a/src/doc/tarpl/casts.md b/src/doc/tarpl/casts.md index 730d8499acfea..cbcf81d837121 100644 --- a/src/doc/tarpl/casts.md +++ b/src/doc/tarpl/casts.md @@ -1,12 +1,13 @@ % Casts -Casts are a superset of coercions: every coercion can be explicitly invoked via a -cast, but some conversions *require* a cast. These "true casts" are generally regarded -as dangerous or problematic actions. True casts revolve around raw pointers and -the primitive numeric types. True casts aren't checked. +Casts are a superset of coercions: every coercion can be explicitly invoked via +a cast, but some conversions *require* a cast. These "true casts" are generally +regarded as dangerous or problematic actions. True casts revolve around raw +pointers and the primitive numeric types. True casts aren't checked. Here's an exhaustive list of all the true casts. For brevity, we will use `*` -to denote either a `*const` or `*mut`, and `integer` to denote any integral primitive: +to denote either a `*const` or `*mut`, and `integer` to denote any integral +primitive: * `*T as *U` where `T, U: Sized` * `*T as *U` TODO: explain unsized situation @@ -37,19 +38,21 @@ expression, `e as U2` is not necessarily so (in fact it will only be valid if For numeric casts, there are quite a few cases to consider: * casting between two integers of the same size (e.g. i32 -> u32) is a no-op -* casting from a larger integer to a smaller integer (e.g. u32 -> u8) will truncate +* casting from a larger integer to a smaller integer (e.g. u32 -> u8) will + truncate * casting from a smaller integer to a larger integer (e.g. u8 -> u32) will * zero-extend if the source is unsigned * sign-extend if the source is signed * casting from a float to an integer will round the float towards zero * **NOTE: currently this will cause Undefined Behaviour if the rounded - value cannot be represented by the target integer type**. This is a bug - and will be fixed. (TODO: figure out what Inf and NaN do) -* casting from an integer to float will produce the floating point representation - of the integer, rounded if necessary (rounding strategy unspecified). -* casting from an f32 to an f64 is perfect and lossless. + value cannot be represented by the target integer type**. This includes + Inf and NaN. This is a bug and will be fixed. +* casting from an integer to float will produce the floating point + representation of the integer, rounded if necessary (rounding strategy + unspecified) +* casting from an f32 to an f64 is perfect and lossless * casting from an f64 to an f32 will produce the closest possible value - (rounding strategy unspecified). + (rounding strategy unspecified) * **NOTE: currently this will cause Undefined Behaviour if the value is finite but larger or smaller than the largest or smallest finite value representable by f32**. This is a bug and will be fixed. diff --git a/src/doc/tarpl/checked-uninit.md b/src/doc/tarpl/checked-uninit.md index 8896fc9de0199..667afe012d557 100644 --- a/src/doc/tarpl/checked-uninit.md +++ b/src/doc/tarpl/checked-uninit.md @@ -1,13 +1,13 @@ % Checked Uninitialized Memory -Like C, all stack variables in Rust are uninitialized until a -value is explicitly assigned to them. Unlike C, Rust statically prevents you -from ever reading them until you do: +Like C, all stack variables in Rust are 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); + let x: i32; + println!("{}", x); } ``` @@ -25,13 +25,13 @@ or anything like that. So this compiles: ```rust fn main() { - let x: i32; + let x: i32; - if true { - x = 1; - } else { - x = 2; - } + if true { + x = 1; + } else { + x = 2; + } println!("{}", x); } @@ -41,30 +41,30 @@ but this doesn't: ```rust fn main() { - let x: i32; - if true { - x = 1; - } - println!("{}", x); + 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); +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 + 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 } ``` @@ -73,10 +73,10 @@ 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 is now logically uninitialized because Box isn't Copy + let x = 0; + let y = Box::new(0); + let z1 = x; // x is still valid because i32 is Copy + let z2 = y; // y is now logically uninitialized because Box isn't Copy } ``` diff --git a/src/doc/tarpl/constructors.md b/src/doc/tarpl/constructors.md index 99bcf5e283ee3..023dea08444a4 100644 --- a/src/doc/tarpl/constructors.md +++ b/src/doc/tarpl/constructors.md @@ -5,31 +5,31 @@ and initialize all its fields at once: ```rust struct Foo { - a: u8, - b: u32, - c: bool, + a: u8, + b: u32, + c: bool, } enum Bar { - X(u32), - Y(bool), + X(u32), + Y(bool), } -struct Empty; +struct Unit; let foo = Foo { a: 0, b: 1, c: false }; let bar = Bar::X(0); -let empty = Empty; +let empty = Unit; ``` That's it. Every other way you make an instance of a type is just calling a totally vanilla function that does some stuff and eventually bottoms out to The One True Constructor. -Unlike C++, Rust does not come with a slew of built in kinds of constructor. +Unlike C++, Rust does not come with a slew of built-in kinds of constructor. There are no Copy, Default, Assignment, Move, or whatever constructors. The -reasons for this are varied, but it largely boils down to Rust's philosophy -of *being explicit*. +reasons for this are varied, but it largely boils down to 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 @@ -37,9 +37,9 @@ 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 *only* semantics in Rust. At most `x = y` just moves the bits of y into the x -variable. Rust *does* provide two facilities for providing C++'s copy-oriented -semantics: `Copy` and `Clone`. Clone is our moral equivalent of a copy +are the *only* semantics in Rust. At most `x = y` just moves the bits of y into +the x variable. Rust *does* provide two facilities for providing C++'s copy- +oriented semantics: `Copy` and `Clone`. Clone is our moral equivalent of a 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 "copy the bits". Copy types *are* implicitly @@ -53,3 +53,7 @@ only useful for generic programming. In concrete contexts, 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. + +TODO: talk about "placement new"? + +[uninit]: uninitialized.html diff --git a/src/doc/tarpl/conversions.md b/src/doc/tarpl/conversions.md index 388516fc7e9e2..56c050072b976 100644 --- a/src/doc/tarpl/conversions.md +++ b/src/doc/tarpl/conversions.md @@ -1,13 +1,13 @@ % Type Conversions -At the end of the day, everything is just a pile of bits somewhere, and type systems -are just there to help us use those bits right. Needing to reinterpret those piles -of bits as different types is a common problem and Rust consequently gives you -several ways to do that. +At the end of the day, everything is just a pile of bits somewhere, and type +systems are just there to help us use those bits right. Needing to reinterpret +those piles of bits as different types is a common problem and Rust consequently +gives you several ways to do that. -First we'll look at the ways that *Safe Rust* gives you to reinterpret values. The -most trivial way to do this is to just destructure a value into its constituent -parts and then build a new type out of them. e.g. +First we'll look at the ways that *Safe Rust* gives you to reinterpret values. +The most trivial way to do this is to just destructure a value into its +constituent parts and then build a new type out of them. e.g. ```rust struct Foo { @@ -26,6 +26,6 @@ fn reinterpret(foo: Foo) -> Bar { } ``` -But this is, at best, annoying to do. For common conversions, rust provides +But this is, at best, annoying to do. For common conversions, Rust provides more ergonomic alternatives. diff --git a/src/doc/tarpl/destructors.md b/src/doc/tarpl/destructors.md index 3bc75c132bf69..cf6378c3e25a3 100644 --- a/src/doc/tarpl/destructors.md +++ b/src/doc/tarpl/destructors.md @@ -1,23 +1,24 @@ % Destructors -What the language *does* provide is full-blown automatic destructors through the `Drop` trait, -which provides the following method: +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 `self`**. This is a -convenience feature so that you don't have to write "destructor boilerplate" to drop -children. If a struct has no special logic for being dropped other than dropping its -children, then it means `Drop` doesn't need to be implemented at all! +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 `self`**. +This is a convenience feature so that you don't have to write "destructor +boilerplate" to drop children. If a struct has no special logic for being +dropped other than dropping its children, then it means `Drop` doesn't need to +be implemented at all! -**There is no stable way to prevent this behaviour in Rust 1.0**. +**There is no stable way to prevent this behaviour in Rust 1.0. -Note that taking `&mut self` means that even if you *could* suppress recursive Drop, -Rust will prevent you from e.g. moving fields out of self. For most types, this -is totally fine. +Note that taking `&mut self` means that even if you *could* suppress recursive +Drop, Rust will prevent you from e.g. moving fields out of self. For most types, +this is totally fine. For instance, a custom implementation of `Box` might write `Drop` like this: @@ -25,18 +26,18 @@ For instance, a custom implementation of `Box` might write `Drop` like this: struct Box{ ptr: *mut T } impl Drop for Box { - fn drop(&mut self) { - unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); - } - } + 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 immediately marked as uninitialized. +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 immediately marked as uninitialized. However this wouldn't work: @@ -44,24 +45,24 @@ However this wouldn't work: struct Box{ ptr: *mut T } impl Drop for Box { - fn drop(&mut self) { - unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); - } - } + 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); - } - } + fn drop(&mut self) { + unsafe { + // Hyper-optimized: deallocate the box's contents for it + // without `drop`ing the contents + heap::deallocate(self.box.ptr); + } + } } ``` @@ -74,9 +75,9 @@ regardless of whether they implement Drop. Therefore something like ```rust struct Boxy { - data1: Box, - data2: Box, - info: u32, + data1: Box, + data2: Box, + info: u32, } ``` @@ -88,16 +89,18 @@ Similarly, ```rust enum Link { - Next(Box), - None, + Next(Box), + None, } ``` -will have its inner Box field dropped *if and only if* an instance stores the Next variant. +will have its inner Box field dropped *if and only if* an instance stores the +Next variant. -In general this works really nice because you don't need to worry about adding/removing -drops when you refactor your data layout. Still there's certainly many valid usecases for -needing to do trickier things with destructors. +In general this works really nice because you don't need to worry about +adding/removing drops 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 overriding recursive drop and allowing moving out of Self during `drop` is to use an Option: @@ -106,35 +109,35 @@ of Self during `drop` is to use an Option: struct Box{ ptr: *mut T } impl Drop for Box { - fn drop(&mut self) { - unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); - } - } + 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` - // field as `None` to prevent Rust from trying to Drop it. - heap::deallocate(self.box.take().unwrap().ptr); - } - } + fn drop(&mut self) { + unsafe { + // Hyper-optimized: deallocate the box's contents for it + // without `drop`ing the contents. Need to set the `box` + // field 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 destructor. 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 +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 destructor. 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 what you should reach for by default. However, in the future we expect there to be a first-class way to announce that -a field shouldn't be automatically dropped. \ No newline at end of file +a field shouldn't be automatically dropped. diff --git a/src/doc/tarpl/drop-flags.md b/src/doc/tarpl/drop-flags.md index 2d5bae6dcfe9c..68f7ffc77b006 100644 --- a/src/doc/tarpl/drop-flags.md +++ b/src/doc/tarpl/drop-flags.md @@ -3,43 +3,43 @@ The examples in the previous section introduce an interesting problem for Rust. We have seen that's possible to conditionally initialize, deinitialize, and *reinitialize* locations of memory totally safely. For Copy types, this isn't -particularly notable since they're just a random pile of bits. However types with -destructors are a different story: Rust needs to know whether to call a destructor -whenever a variable is assigned to, or a variable goes out of scope. How can it -do this with conditional initialization? +particularly notable since they're just a random pile of bits. However types +with destructors are a different story: Rust needs to know whether to call a +destructor whenever a variable is assigned to, or a variable goes out of scope. +How can it do this with conditional initialization? -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 toggled. When a variable *might* need to be dropped, this flag -is evaluated to determine if it *should* be dropped. +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 toggled. When a variable *might* need to be dropped, this +flag is evaluated to determine if it *should* be dropped. Of course, it is *often* the case that a value's initialization state can be *statically* known at every point in the program. If this is the case, then the -compiler can theoretically generate more effecient code! For instance, -straight-line code has such *static drop semantics*: +compiler can theoretically generate more effecient code! For instance, straight- +line code has such *static drop semantics*: ```rust -let mut x = Box::new(0); // x was uninit -let mut y = x; // y was uninit -x = Box::new(0); // x was uninit -y = x; // y was init; Drop y! - // y was init; Drop y! - // x was uninit +let mut x = Box::new(0); // x was uninit; just overwrite. +let mut y = x; // y was uninit; just overwrite and make x uninit. +x = Box::new(0); // x was uninit; just overwrite. +y = x; // y was init; Drop y, overwrite it, and make x uninit! + // y was init; Drop y! + // x was uninit; do nothing. ``` And even branched code where all branches have the same behaviour with respect to initialization: ```rust -let mut x = Box::new(0); // x was uninit +let mut x = Box::new(0); // x was uninit; just overwrite. if condition { - drop(x) // x gets moved out + drop(x) // x gets moved out; make x uninit. } else { - println!("{}", x); - drop(x) // x gets moved out + println!("{}", x); + drop(x) // x gets moved out; make x uninit. } -x = Box::new(0); // x was uninit - // x was init; Drop x! +x = Box::new(0); // x was uninit; just overwrite. + // x was init; Drop x! ``` However code like this *requires* runtime information to correctly Drop: @@ -47,18 +47,18 @@ However code like this *requires* runtime information to correctly Drop: ```rust let x; if condition { - x = Box::new(0); // x was uninit - println!("{}", x); + x = Box::new(0); // x was uninit; just overwrite. + println!("{}", x); } - // x might be uninit; check the flag! + // x *might* be uninit; check the flag! ``` Of course, in this case it's trivial to retrieve static drop semantics: ```rust if condition { - let x = Box::new(0); - println!("{}", x); + let x = Box::new(0); + println!("{}", x); } ``` @@ -75,4 +75,4 @@ as it requires fairly substantial changes to the compiler. Regardless, 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 -you can work with them in Safe Rust, but you're *never* in danger. \ No newline at end of file +you can work with them in Safe Rust, but you're *never* in danger. diff --git a/src/doc/tarpl/exception-safety.md b/src/doc/tarpl/exception-safety.md index 12e000b5ef6e4..ca33109781127 100644 --- a/src/doc/tarpl/exception-safety.md +++ b/src/doc/tarpl/exception-safety.md @@ -7,7 +7,7 @@ if it overflows. Unless you are very careful and tightly control what code runs, pretty much everything can unwind, and you need to be ready for it. Being ready for unwinding is often referred to as *exception safety* -in the broader programming world. In Rust, their are two levels of exception +in the broader programming world. In Rust, there are two levels of exception safety that one may concern themselves with: * In unsafe code, we *must* be exception safe to the point of not violating @@ -58,16 +58,17 @@ impl Vec { We bypass `push` in order to avoid redundant capacity and `len` checks on the Vec that we definitely know has capacity. The logic is totally correct, except there's a subtle problem with our code: it's not exception-safe! `set_len`, -`offset`, and `write` are all fine, but *clone* is the panic bomb we over-looked. +`offset`, and `write` are all fine, but *clone* is the panic bomb we over- +looked. -Clone is completely out of our control, and is totally free to panic. If it does, -our function will exit early with the length of the Vec set too large. If +Clone is completely out of our control, and is totally free to panic. If it +does, our function will exit early with the length of the Vec set too large. If the Vec is looked at or dropped, uninitialized memory will be read! The fix in this case is fairly simple. If we want to guarantee that the values we *did* clone are dropped we can set the len *in* the loop. If we just want to -guarantee that uninitialized memory can't be observed, we can set the len *after* -the loop. +guarantee that uninitialized memory can't be observed, we can set the len +*after* the loop. diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md index ea8dc86d1f0ac..5eeb4850d876e 100644 --- a/src/doc/tarpl/exotic-sizes.md +++ b/src/doc/tarpl/exotic-sizes.md @@ -9,18 +9,19 @@ is not always the case, however. # Dynamically Sized Types (DSTs) -Rust also supports types without a statically known size. On the surface, -this is a bit nonsensical: Rust *must* know the size of something in order to -work with it! DSTs are generally produced as views, or through type-erasure -of types that *do* have a known size. Due to their lack of a statically known -size, these types can only exist *behind* some kind of pointer. They consequently -produce a *fat* pointer consisting of the pointer and the information that -*completes* them. - -For instance, the slice type, `[T]`, is some statically unknown number of elements -stored contiguously. `&[T]` consequently consists of a `(&T, usize)` pair that specifies -where the slice starts, and how many elements it contains. Similarly, Trait Objects -support interface-oriented type erasure through a `(data_ptr, vtable_ptr)` pair. +Rust also supports types without a statically known size. On the surface, this +is a bit nonsensical: Rust *must* know the size of something in order to work +with it! DSTs are generally produced as views, or through type-erasure of types +that *do* have a known size. Due to their lack of a statically known size, these +types can only exist *behind* some kind of pointer. They consequently produce a +*fat* pointer consisting of the pointer and the information that *completes* +them. + +For instance, the slice type, `[T]`, is some statically unknown number of +elements stored contiguously. `&[T]` consequently consists of a `(&T, usize)` +pair that specifies where the slice starts, and how many elements it contains. +Similarly, Trait Objects support interface-oriented type erasure through a +`(data_ptr, vtable_ptr)` pair. Structs can actually store a single DST directly as their last field, but this makes them a DST as well: @@ -50,38 +51,39 @@ struct Foo; // No fields = no size // All fields have no size = no size struct Baz { foo: Foo, - qux: (), // empty tuple has no size + qux: (), // empty tuple has no size baz: [u8; 0], // empty array has no size } ``` -On their own, ZSTs are, for obvious reasons, pretty useless. However -as with many curious layout choices in Rust, their potential is realized in a generic +On their own, ZSTs are, for obvious reasons, pretty useless. However as with +many curious layout choices in Rust, their potential is realized in a generic context. -Rust largely understands that any operation that produces or stores a ZST -can be reduced to a no-op. For instance, a `HashSet` can be effeciently implemented -as a thin wrapper around `HashMap` because all the operations `HashMap` normally -does to store and retrieve keys will be completely stripped in monomorphization. +Rust largely understands that any operation that produces or stores a ZST can be +reduced to a no-op. For instance, a `HashSet` can be effeciently implemented +as a thin wrapper around `HashMap` because all the operations `HashMap` +normally does to store and retrieve keys will be completely stripped in +monomorphization. Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. Safe code need not worry about ZSTs, but *unsafe* code must be careful about the -consequence of types with no size. In particular, pointer offsets are no-ops, and -standard allocators (including jemalloc, the one used by Rust) generally consider -passing in `0` as Undefined Behaviour. +consequence of types with no size. In particular, pointer offsets are no-ops, +and standard allocators (including jemalloc, the one used by Rust) generally +consider passing in `0` as Undefined Behaviour. -# Void Types +# Empty Types Rust also enables types to be declared that *cannot even be instantiated*. These types can only be talked about at the type level, and never at the value level. ```rust -enum Foo { } // No variants = VOID +enum Foo { } // No variants = EMPTY ``` -TODO: WHY?! \ No newline at end of file +TODO: WHY?! diff --git a/src/doc/tarpl/leaking.md b/src/doc/tarpl/leaking.md index 5d66b1a424c45..1e1e95a243dd4 100644 --- a/src/doc/tarpl/leaking.md +++ b/src/doc/tarpl/leaking.md @@ -1,46 +1,46 @@ % Leaking -Ownership based resource management is intended to simplify composition. You -acquire resources when you create the object, and you release the resources -when it gets destroyed. Since destruction is handled for you, it means you -can't forget to release the resources, and it happens as soon as possible! -Surely this is perfect and all of our problems are solved. +Ownership-based resource management is intended to simplify composition. You +acquire resources when you create the object, and you release the resources when +it gets destroyed. Since destruction is handled for you, it means you can't +forget to release the resources, and it happens as soon as possible! Surely this +is perfect and all of our problems are solved. Everything is terrible and we have new and exotic problems to try to solve. -Many people like to believe that Rust eliminates resource leaks, but this -is absolutely not the case, no matter how you look at it. In the strictest -sense, "leaking" is so abstract as to be unpreventable. It's quite trivial -to initialize a collection at the start of a program, fill it with tons of -objects with destructors, and then enter an infinite event loop that never -refers to it. The collection will sit around uselessly, holding on to its -precious resources until the program terminates (at which point all those -resources would have been reclaimed by the OS anyway). +Many people like to believe that Rust eliminates resource leaks, but this is +absolutely not the case, no matter how you look at it. In the strictest sense, +"leaking" is so abstract as to be unpreventable. It's quite trivial to +initialize a collection at the start of a program, fill it with tons of objects +with destructors, and then enter an infinite event loop that never refers to it. +The collection will sit around uselessly, holding on to its precious resources +until the program terminates (at which point all those resources would have been +reclaimed by the OS anyway). -We may consider a more restricted form of leak: failing to drop a value that -is unreachable. Rust also doesn't prevent this. In fact Rust has a *function -for doing this*: `mem::forget`. This function consumes the value it is passed -*and then doesn't run its destructor*. +We may consider a more restricted form of leak: failing to drop a value that is +unreachable. Rust also doesn't prevent this. In fact Rust has a *function for +doing this*: `mem::forget`. This function consumes the value it is passed *and +then doesn't run its destructor*. In the past `mem::forget` was marked as unsafe as a sort of lint against using it, since failing to call a destructor is generally not a well-behaved thing to do (though useful for some special unsafe code). However this was generally determined to be an untenable stance to take: there are *many* ways to fail to -call a destructor in safe code. The most famous example is creating a cycle -of reference counted pointers using interior mutability. +call a destructor in safe code. The most famous example is creating a cycle of +reference-counted pointers using interior mutability. -It is reasonable for safe code to assume that destructor leaks do not happen, -as any program that leaks destructors is probably wrong. However *unsafe* code +It is reasonable for safe code to assume that destructor leaks do not happen, as +any program that leaks destructors is probably wrong. However *unsafe* code cannot rely on destructors to be run to be *safe*. For most types this doesn't -matter: if you leak the destructor then the type is *by definition* inaccessible, -so it doesn't matter, right? For instance, if you leak a `Box` then you -waste some memory but that's hardly going to violate memory-safety. +matter: if you leak the destructor then the type is *by definition* +inaccessible, so it doesn't matter, right? For instance, if you leak a `Box` +then you waste some memory but that's hardly going to violate memory-safety. -However where we must be careful with destructor leaks are *proxy* types. -These are types which manage access to a distinct object, but don't actually -own it. Proxy objects are quite rare. Proxy objects you'll need to care about -are even rarer. However we'll focus on three interesting examples in the -standard library: +However where we must be careful with destructor leaks are *proxy* types. These +are types which manage access to a distinct object, but don't actually own it. +Proxy objects are quite rare. Proxy objects you'll need to care about are even +rarer. However we'll focus on three interesting examples in the standard +library: * `vec::Drain` * `Rc` @@ -58,7 +58,8 @@ after claiming ownership over all of its contents. It produces an iterator Now, consider Drain in the middle of iteration: some values have been moved out, and others haven't. This means that part of the Vec is now full of logically uninitialized data! We could backshift all the elements in the Vec every time we -remove a value, but this would have pretty catastrophic performance consequences. +remove a value, but this would have pretty catastrophic performance +consequences. Instead, we would like Drain to *fix* the Vec's backing storage when it is dropped. It should run itself to completion, backshift any elements that weren't @@ -71,35 +72,35 @@ Now consider the following: let mut vec = vec![Box::new(0); 4]; { - // start draining, vec can no longer be accessed - let mut drainer = vec.drain(..); + // start draining, vec can no longer be accessed + let mut drainer = vec.drain(..); - // pull out two elements and immediately drop them - drainer.next(); - drainer.next(); + // pull out two elements and immediately drop them + drainer.next(); + drainer.next(); - // get rid of drainer, but don't call its destructor - mem::forget(drainer); + // get rid of drainer, but don't call its destructor + mem::forget(drainer); } // Oops, vec[0] was dropped, we're reading a pointer into free'd memory! println!("{}", vec[0]); ``` -This is pretty clearly Not Good. Unfortunately, we're kind've stuck between -a rock and a hard place: maintaining consistent state at every step has -an enormous cost (and would negate any benefits of the API). Failing to maintain +This is pretty clearly Not Good. Unfortunately, we're kind've stuck between a +rock and a hard place: maintaining consistent state at every step has an +enormous cost (and would negate any benefits of the API). Failing to maintain consistent state gives us Undefined Behaviour in safe code (making the API unsound). So what can we do? Well, we can pick a trivially consistent state: set the Vec's len to be 0 when we *start* the iteration, and fix it up if necessary in the destructor. That way, if everything executes like normal we get the desired -behaviour with minimal overhead. But if someone has the *audacity* to mem::forget -us in the middle of the iteration, all that does is *leak even more* (and possibly -leave the Vec in an *unexpected* but consistent state). Since we've -accepted that mem::forget is safe, this is definitely safe. We call leaks causing -more leaks a *leak amplification*. +behaviour with minimal overhead. But if someone has the *audacity* to +mem::forget us in the middle of the iteration, all that does is *leak even more* +(and possibly leave the Vec in an *unexpected* but consistent state). Since +we've accepted that mem::forget is safe, this is definitely safe. We call leaks +causing more leaks a *leak amplification*. @@ -108,8 +109,8 @@ more leaks a *leak amplification*. Rc is an interesting case because at first glance it doesn't appear to be a proxy value at all. After all, it manages the data it points to, and dropping -all the Rcs for a value will drop that value. leaking an Rc doesn't seem like -it would be particularly dangerous. It will leave the refcount permanently +all the Rcs for a value will drop that value. Leaking an Rc doesn't seem like it +would be particularly dangerous. It will leave the refcount permanently incremented and prevent the data from being freed or dropped, but that seems just like Box, right? @@ -119,47 +120,47 @@ Let's consider a simplified implementation of Rc: ```rust struct Rc { - ptr: *mut RcBox, + ptr: *mut RcBox, } struct RcBox { - data: T, - ref_count: usize, + data: T, + ref_count: usize, } impl Rc { - fn new(data: T) -> Self { - unsafe { - // Wouldn't it be nice if heap::allocate worked like this? - let ptr = heap::allocate>(); - ptr::write(ptr, RcBox { - data: data, - ref_count: 1, - }); - Rc { ptr: ptr } - } - } - - fn clone(&self) -> Self { - unsafe { - (*self.ptr).ref_count += 1; - } - Rc { ptr: self.ptr } - } + fn new(data: T) -> Self { + unsafe { + // Wouldn't it be nice if heap::allocate worked like this? + let ptr = heap::allocate>(); + ptr::write(ptr, RcBox { + data: data, + ref_count: 1, + }); + Rc { ptr: ptr } + } + } + + fn clone(&self) -> Self { + unsafe { + (*self.ptr).ref_count += 1; + } + Rc { ptr: self.ptr } + } } impl Drop for Rc { - fn drop(&mut self) { - unsafe { - let inner = &mut ; - (*self.ptr).ref_count -= 1; - if (*self.ptr).ref_count == 0 { - // drop the data and then free it - ptr::read(self.ptr); - heap::deallocate(self.ptr); - } - } - } + fn drop(&mut self) { + unsafe { + let inner = &mut ; + (*self.ptr).ref_count -= 1; + if (*self.ptr).ref_count == 0 { + // drop the data and then free it + ptr::read(self.ptr); + heap::deallocate(self.ptr); + } + } + } } ``` @@ -185,24 +186,24 @@ data on the stack without any synchronization over that data. Usage looked like: ```rust let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; { - let guards = vec![]; - for x in &mut data { - // Move the mutable reference into the closure, and execute - // it on a different thread. The closure has a lifetime bound - // by the lifetime of the mutable reference `x` we store in it. - // The guard that is returned is in turn assigned the lifetime - // of the closure, so it also mutably borrows `data` as `x` did. - // This means we cannot access `data` until the guard goes away. - let guard = thread::scoped(move || { - *x *= 2; - }); - // store the thread's guard for later - guards.push(guard); - } - // All guards are dropped here, forcing the threads to join - // (this thread blocks here until the others terminate). - // Once the threads join, the borrow expires and the data becomes - // accessible again in this thread. + let guards = vec![]; + for x in &mut data { + // Move the mutable reference into the closure, and execute + // it on a different thread. The closure has a lifetime bound + // by the lifetime of the mutable reference `x` we store in it. + // The guard that is returned is in turn assigned the lifetime + // of the closure, so it also mutably borrows `data` as `x` did. + // This means we cannot access `data` until the guard goes away. + let guard = thread::scoped(move || { + *x *= 2; + }); + // store the thread's guard for later + guards.push(guard); + } + // All guards are dropped here, forcing the threads to join + // (this thread blocks here until the others terminate). + // Once the threads join, the borrow expires and the data becomes + // accessible again in this thread. } // data is definitely mutated here. ``` @@ -213,17 +214,17 @@ In principle, this totally works! Rust's ownership system perfectly ensures it! ``` let mut data = Box::new(0); { - let guard = thread::scoped(|| { - // This is at best a data race. At worst, it's *also* a use-after-free. - *data += 1; - }); - // Because the guard is forgotten, expiring the loan without blocking this - // thread. - mem::forget(guard); + let guard = thread::scoped(|| { + // This is at best a data race. At worst, it's *also* a use-after-free. + *data += 1; + }); + // Because the guard is forgotten, expiring the loan without blocking this + // thread. + mem::forget(guard); } // So the Box is dropped here while the scoped thread may or may not be trying // to access it. ``` Dang. Here the destructor running was pretty fundamental to the API, and it had -to be scrapped in favour of a completely different design. \ No newline at end of file +to be scrapped in favour of a completely different design. diff --git a/src/doc/tarpl/other-reprs.md b/src/doc/tarpl/other-reprs.md index 829a15e6355b2..d4c6134c5432b 100644 --- a/src/doc/tarpl/other-reprs.md +++ b/src/doc/tarpl/other-reprs.md @@ -8,30 +8,31 @@ Rust allows you to specify alternative data layout strategies from the default. # repr(C) This is the most important `repr`. It has fairly simple intent: do what C does. -The order, size, and alignment of fields is exactly what you would expect from -C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, -as C is the lingua-franca of the programming world. This is also necessary -to soundly do more elaborate tricks with data layout such as reintepretting values -as a different type. +The order, size, and alignment of fields is exactly what you would expect from C +or C++. Any type you expect to pass through an FFI boundary should have +`repr(C)`, as C is the lingua-franca of the programming world. This is also +necessary to soundly do more elaborate tricks with data layout such as +reintepretting values as a different type. -However, the interaction with Rust's more exotic data layout features must be kept -in mind. Due to its dual purpose as "for FFI" and "for layout control", `repr(C)` -can be applied to types that will be nonsensical or problematic if passed through -the FFI boundary. +However, the interaction with Rust's more exotic data layout features must be +kept in mind. Due to its dual purpose as "for FFI" and "for layout control", +`repr(C)` can be applied to types that will be nonsensical or problematic if +passed through the FFI boundary. -* ZSTs are still zero-sized, even though this is not a standard behaviour - in C, and is explicitly contrary to the behaviour of an empty type in C++, which - still consumes a byte of space. +* ZSTs are still zero-sized, even though this is not a standard behaviour in +C, and is explicitly contrary to the behaviour of an empty type in C++, which +still consumes a byte of space. * DSTs, tuples, and tagged unions are not a concept in C and as such are never - FFI safe. +FFI safe. * **The [drop flag][] will still be added** * This is equivalent to one of `repr(u*)` (see the next section) for enums. The - chosen size is the default enum size for the target platform's C ABI. Note that - enum representation in C is undefined, and this may be incorrect when the C - code is compiled with certain flags. +chosen size is the default enum size for the target platform's C ABI. Note that +enum representation in C is implementation defined, so this is really a "best +guess". In particular, this may be incorrect when the C code of interest is +compiled with certain flags. @@ -40,10 +41,11 @@ the FFI boundary. These specify the size to make a C-like enum. If the discriminant overflows the integer it has to fit in, it will be an error. You can manually ask Rust to allow this by setting the overflowing element to explicitly be 0. However Rust -will not allow you to create an enum where two variants have the same discriminant. +will not allow you to create an enum where two variants have the same +discriminant. -On non-C-like enums, this will inhibit certain optimizations like the null-pointer -optimization. +On non-C-like enums, this will inhibit certain optimizations like the null- +pointer optimization. These reprs have no affect on a struct. @@ -53,15 +55,15 @@ These reprs have no affect on a struct. # repr(packed) `repr(packed)` forces rust to strip any padding, and only align the type to a -byte. This may improve the memory footprint, but will likely have other -negative side-effects. +byte. This may improve the memory footprint, but will likely have other negative +side-effects. In particular, most architectures *strongly* prefer values to be aligned. This -may mean the unaligned loads are penalized (x86), or even fault (some ARM chips). -For simple cases like directly loading or storing a packed field, the compiler -might be able to paper over alignment issues with shifts and masks. However if -you take a reference to a packed field, it's unlikely that the compiler will be -able to emit code to avoid an unaligned load. +may mean the unaligned loads are penalized (x86), or even fault (some ARM +chips). For simple cases like directly loading or storing a packed field, the +compiler might be able to paper over alignment issues with shifts and masks. +However if you take a reference to a packed field, it's unlikely that the +compiler will be able to emit code to avoid an unaligned load. `repr(packed)` is not to be used lightly. Unless you have extreme requirements, this should not be used. diff --git a/src/doc/tarpl/references.md b/src/doc/tarpl/references.md index 24c6b607840d8..993e2a52aebfa 100644 --- a/src/doc/tarpl/references.md +++ b/src/doc/tarpl/references.md @@ -2,13 +2,11 @@ There are two kinds of reference: -* Shared reference: `&` -* Mutable reference: `&mut` +* Shared reference: `&` Mutable reference: `&mut` Which obey the following rules: -* A reference cannot outlive its referent -* A mutable reference cannot be aliased +* A reference cannot outlive its referent A mutable reference cannot be aliased To define aliasing, we must define the notion of *paths* and *liveness*. @@ -17,60 +15,66 @@ To define aliasing, we must define the notion of *paths* and *liveness*. # Paths -If all Rust had were values, then every value would be uniquely owned -by a variable or composite structure. From this we naturally derive a *tree* -of ownership. The stack itself is the root of the tree, with every variable -as its direct children. Each variable's direct children would be their fields -(if any), and so on. +If all Rust had were values, then every value would be uniquely owned by a +variable or composite structure. From this we naturally derive a *tree* of +ownership. The stack itself is the root of the tree, with every variable as its +direct children. Each variable's direct children would be their fields (if any), +and so on. -From this view, every value in Rust has a unique *path* in the tree of ownership. -References to a value can subsequently be interpreted as a path in this tree. -Of particular interest are *ancestors* and *descendants*: if `x` owns `y`, then -`x` is an *ancestor* of `y`, and `y` is a *descendant* of `x`. Note that this is -an inclusive relationship: `x` is a descendant and ancestor of itself. +From this view, every value in Rust has a unique *path* in the tree of +ownership. References to a value can subsequently be interpreted as a path in +this tree. Of particular interest are *ancestors* and *descendants*: if `x` owns +`y`, then `x` is an *ancestor* of `y`, and `y` is a *descendant* of `x`. Note +that this is an inclusive relationship: `x` is a descendant and ancestor of +itself. -Tragically, plenty of data doesn't reside on the stack, and we must also accommodate this. -Globals and thread-locals are simple enough to model as residing at the bottom -of the stack (though we must be careful with mutable globals). Data on -the heap poses a different problem. +Tragically, plenty of data doesn't reside on the stack, and we must also +accommodate this. Globals and thread-locals are simple enough to model as +residing at the bottom of the stack (though we must be careful with mutable +globals). Data on the heap poses a different problem. If all Rust had on the heap was data uniquely owned by a pointer on the stack, -then we can just treat that pointer as a struct that owns the value on -the heap. Box, Vec, String, and HashMap, are examples of types which uniquely -own data on the heap. +then we can just treat that pointer as a struct that owns the value on the heap. +Box, Vec, String, and HashMap, are examples of types which uniquely own data on +the heap. Unfortunately, data on the heap is not *always* uniquely owned. Rc for instance introduces a notion of *shared* ownership. Shared ownership means there is no -unique path. A value with no unique path limits what we can do with it. In general, only -shared references can be created to these values. However mechanisms which ensure -mutual exclusion may establish One True Owner temporarily, establishing a unique path -to that value (and therefore all its children). +unique path. A value with no unique path limits what we can do with it. In +general, only shared references can be created to these values. However +mechanisms which ensure mutual exclusion may establish One True Owner +temporarily, establishing a unique path to that value (and therefore all its +children). The most common way to establish such a path is through *interior mutability*, in contrast to the *inherited mutability* that everything in Rust normally uses. -Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. These -types provide exclusive access through runtime restrictions. However it is also -possible to establish unique ownership without interior mutability. For instance, -if an Rc has refcount 1, then it is safe to mutate or move its internals. +Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. +These types provide exclusive access through runtime restrictions. However it is +also possible to establish unique ownership without interior mutability. For +instance, if an Rc has refcount 1, then it is safe to mutate or move its +internals. In order to correctly communicate to the type system that a variable or field of a struct can have interior mutability, it must be wrapped in an UnsafeCell. This -does not in itself make it safe to perform interior mutability operations on that -value. You still must yourself ensure that mutual exclusion is upheld. +does not in itself make it safe to perform interior mutability operations on +that value. You still must yourself ensure that mutual exclusion is upheld. # Liveness +Note: Liveness is not the same thing as a *lifetime*, which will be explained +in detail in the next section of this chapter. + Roughly, a reference is *live* at some point in a program if it can be -dereferenced. Shared references are always live unless they are literally unreachable -(for instance, they reside in freed or leaked memory). Mutable references can be -reachable but *not* live through the process of *reborrowing*. +dereferenced. Shared references are always live unless they are literally +unreachable (for instance, they reside in freed or leaked memory). Mutable +references can be reachable but *not* live through the process of *reborrowing*. A mutable reference can be reborrowed to either a shared or mutable reference to one of its descendants. A reborrowed reference will only be live again once all -reborrows derived from it expire. For instance, a mutable reference can be reborrowed -to point to a field of its referent: +reborrows derived from it expire. For instance, a mutable reference can be +reborrowed to point to a field of its referent: ```rust let x = &mut (1, 2); @@ -110,18 +114,18 @@ to make such a borrow*, just that Rust isn't as smart as you want. To simplify things, we can model variables as a fake type of reference: *owned* references. Owned references have much the same semantics as mutable references: -they can be re-borrowed in a mutable or shared manner, which makes them no longer -live. Live owned references have the unique property that they can be moved -out of (though mutable references *can* be swapped out of). This power is +they can be re-borrowed in a mutable or shared manner, which makes them no +longer live. Live owned references have the unique property that they can be +moved out of (though mutable references *can* be swapped out of). This power is only given to *live* owned references because moving its referent would of course invalidate all outstanding references prematurely. As a local lint against inappropriate mutation, only variables that are marked as `mut` can be borrowed mutably. -It is interesting to note that Box behaves exactly like an owned -reference. It can be moved out of, and Rust understands it sufficiently to -reason about its paths like a normal variable. +It is interesting to note that Box behaves exactly like an owned reference. It +can be moved out of, and Rust understands it sufficiently to reason about its +paths like a normal variable. @@ -130,21 +134,21 @@ reason about its paths like a normal variable. With liveness and paths defined, we can now properly define *aliasing*: -**A mutable reference is aliased if there exists another live reference to one of -its ancestors or descendants.** +**A mutable reference is aliased if there exists another live reference to one +of its ancestors or descendants.** (If you prefer, you may also say the two live references alias *each other*. This has no semantic consequences, but is probably a more useful notion when verifying the soundness of a construct.) -That's it. Super simple right? Except for the fact that it took us two pages -to define all of the terms in that definition. You know: Super. Simple. +That's it. Super simple right? Except for the fact that it took us two pages to +define all of the terms in that definition. You know: Super. Simple. -Actually it's a bit more complicated than that. In addition to references, -Rust has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent -ownership or aliasing semantics. As a result, Rust makes absolutely no effort -to track that they are used correctly, and they are wildly unsafe. +Actually it's a bit more complicated than that. In addition to references, Rust +has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent +ownership or aliasing semantics. As a result, Rust makes absolutely no effort to +track that they are used correctly, and they are wildly unsafe. **It is an open question to what degree raw pointers have alias semantics. -However it is important for these definitions to be sound that the existence -of a raw pointer does not imply some kind of live path.** +However it is important for these definitions to be sound that the existence of +a raw pointer does not imply some kind of live path.** diff --git a/src/doc/tarpl/send-and-sync.md b/src/doc/tarpl/send-and-sync.md index 0ac14a85f847f..6045d3d0378ad 100644 --- a/src/doc/tarpl/send-and-sync.md +++ b/src/doc/tarpl/send-and-sync.md @@ -1,38 +1,40 @@ % Send and Sync -Not everything obeys inherited mutability, though. Some types allow you to multiply -alias a location in memory while mutating it. Unless these types use synchronization -to manage this access, they are absolutely not thread safe. Rust captures this with -through the `Send` and `Sync` traits. +Not everything obeys inherited mutability, though. Some types allow you to +multiply alias a location in memory while mutating it. Unless these types use +synchronization to manage this access, they are absolutely not thread safe. Rust +captures this with through the `Send` and `Sync` traits. -* A type is Send if it is safe to send it to another thread. -* A type is Sync if it is safe to share between threads (`&T` is Send). +* A type is Send if it is safe to send it to another thread. A type is Sync if +* it is safe to share between threads (`&T` is Send). Send and Sync are *very* fundamental to Rust's concurrency story. As such, a substantial amount of special tooling exists to make them work right. First and -foremost, they're *unsafe traits*. This means that they are unsafe *to implement*, -and other unsafe code can *trust* that they are correctly implemented. Since -they're *marker traits* (they have no associated items like methods), correctly -implemented simply means that they have the intrinsic properties an implementor -should have. Incorrectly implementing Send or Sync can cause Undefined Behaviour. - -Send and Sync are also what Rust calls *opt-in builtin traits*. -This means that, unlike every other trait, they are *automatically* derived: -if a type is composed entirely of Send or Sync types, then it is Send or Sync. -Almost all primitives are Send and Sync, and as a consequence pretty much -all types you'll ever interact with are Send and Sync. +foremost, they're *unsafe traits*. This means that they are unsafe *to +implement*, and other unsafe code can *trust* that they are correctly +implemented. Since they're *marker traits* (they have no associated items like +methods), correctly implemented simply means that they have the intrinsic +properties an implementor should have. Incorrectly implementing Send or Sync can +cause Undefined Behaviour. + +Send and Sync are also what Rust calls *opt-in builtin traits*. This means that, +unlike every other trait, they are *automatically* derived: if a type is +composed entirely of Send or Sync types, then it is Send or Sync. Almost all +primitives are Send and Sync, and as a consequence pretty much all types you'll +ever interact with are Send and Sync. Major exceptions include: * raw pointers are neither Send nor Sync (because they have no safety guards) -* `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) -* `Rc` isn't Send or Sync (because the refcount is shared and unsynchronized) +* `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) `Rc` isn't +* Send or Sync (because the refcount is shared and unsynchronized) `Rc` and `UnsafeCell` are very fundamentally not thread-safe: they enable -unsynchronized shared mutable state. However raw pointers are, strictly speaking, -marked as thread-unsafe as more of a *lint*. Doing anything useful +unsynchronized shared mutable state. However raw pointers are, strictly +speaking, marked as thread-unsafe as more of a *lint*. Doing anything useful with a raw pointer requires dereferencing it, which is already unsafe. In that -sense, one could argue that it would be "fine" for them to be marked as thread safe. +sense, one could argue that it would be "fine" for them to be marked as thread +safe. However it's important that they aren't thread safe to prevent types that *contain them* from being automatically marked as thread safe. These types have @@ -60,17 +62,16 @@ impl !Send for SpecialThreadToken {} impl !Sync for SpecialThreadToken {} ``` -Note that *in and of itself* it is impossible to incorrectly derive Send and Sync. -Only types that are ascribed special meaning by other unsafe code can possible cause -trouble by being incorrectly Send or Sync. +Note that *in and of itself* it is impossible to incorrectly derive Send and +Sync. Only types that are ascribed special meaning by other unsafe code can +possible cause trouble by being incorrectly Send or Sync. Most uses of raw pointers should be encapsulated behind a sufficient abstraction that Send and Sync can be derived. For instance all of Rust's standard -collections are Send and Sync (when they contain Send and Sync types) -in spite of their pervasive use raw pointers to -manage allocations and complex ownership. Similarly, most iterators into these -collections are Send and Sync because they largely behave like an `&` or `&mut` -into the collection. +collections are Send and Sync (when they contain Send and Sync types) in spite +of their pervasive use raw pointers to manage allocations and complex ownership. +Similarly, most iterators into these collections are Send and Sync because they +largely behave like an `&` or `&mut` into the collection. TODO: better explain what can or can't be Send or Sync. Sufficient to appeal -only to data races? \ No newline at end of file +only to data races? From 7aee8448ea461a598075065491e98f941a570fea Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 14 Jul 2015 11:07:00 -0700 Subject: [PATCH 073/104] fix all the doc tests --- src/doc/tarpl/checked-uninit.md | 4 +- src/doc/tarpl/coercions.md | 2 +- src/doc/tarpl/destructors.md | 61 +++++++++++++++++++++------- src/doc/tarpl/drop-flags.md | 3 ++ src/doc/tarpl/exception-safety.md | 2 +- src/doc/tarpl/hrtb.md | 6 +-- src/doc/tarpl/leaking.md | 8 ++-- src/doc/tarpl/lifetime-elision.md | 6 +-- src/doc/tarpl/lifetime-misc.md | 18 ++++---- src/doc/tarpl/lifetimes.md | 12 +++--- src/doc/tarpl/ownership.md | 4 +- src/doc/tarpl/repr-rust.md | 2 +- src/doc/tarpl/send-and-sync.md | 2 + src/doc/tarpl/subtyping.md | 22 +++++----- src/doc/tarpl/unbounded-lifetimes.md | 2 +- src/doc/tarpl/unchecked-uninit.md | 39 +++++++++--------- src/doc/tarpl/vec-alloc.md | 4 +- src/doc/tarpl/vec-dealloc.md | 4 +- src/doc/tarpl/vec-deref.md | 4 +- src/doc/tarpl/vec-drain.md | 16 ++++---- src/doc/tarpl/vec-final.md | 8 ++-- src/doc/tarpl/vec-insert-remove.md | 6 +-- src/doc/tarpl/vec-into-iter.md | 26 ++++++------ src/doc/tarpl/vec-layout.md | 6 ++- src/doc/tarpl/vec-push-pop.md | 6 +-- src/doc/tarpl/working-with-unsafe.md | 24 +++++++---- 26 files changed, 176 insertions(+), 121 deletions(-) diff --git a/src/doc/tarpl/checked-uninit.md b/src/doc/tarpl/checked-uninit.md index 667afe012d557..65bffd7d09fea 100644 --- a/src/doc/tarpl/checked-uninit.md +++ b/src/doc/tarpl/checked-uninit.md @@ -4,7 +4,7 @@ Like C, all stack variables in Rust are uninitialized until a value is explicitly assigned to them. Unlike C, Rust statically prevents you from ever reading them until you do: -```rust +```rust,ignore fn main() { let x: i32; println!("{}", x); @@ -39,7 +39,7 @@ fn main() { but this doesn't: -```rust +```rust,ignore fn main() { let x: i32; if true { diff --git a/src/doc/tarpl/coercions.md b/src/doc/tarpl/coercions.md index fad9b09c3c38d..df0fdfa57ca13 100644 --- a/src/doc/tarpl/coercions.md +++ b/src/doc/tarpl/coercions.md @@ -51,7 +51,7 @@ receivers, see below). If there is an impl for some type `U` and `T` coerces to following will not type check, even though it is OK to coerce `t` to `&T` and there is an impl for `&T`: -```rust +```rust,ignore trait Trait {} fn foo(t: X) {} diff --git a/src/doc/tarpl/destructors.md b/src/doc/tarpl/destructors.md index cf6378c3e25a3..e146ae4a1dac3 100644 --- a/src/doc/tarpl/destructors.md +++ b/src/doc/tarpl/destructors.md @@ -3,7 +3,7 @@ What the language *does* provide is full-blown automatic destructors through the `Drop` trait, which provides the following method: -```rust +```rust,ignore fn drop(&mut self); ``` @@ -23,13 +23,22 @@ this is totally fine. For instance, a custom implementation of `Box` might write `Drop` like this: ```rust -struct Box{ ptr: *mut T } +#![feature(heap_api, core_intrinsics, unique)] + +use std::rt::heap; +use std::ptr::Unique; +use std::intrinsics::drop_in_place; +use std::mem; + +struct Box{ ptr: Unique } impl Drop for Box { fn drop(&mut self) { unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); + drop_in_place(*self.ptr); + heap::deallocate((*self.ptr) as *mut u8, + mem::size_of::(), + mem::align_of::()); } } } @@ -42,25 +51,36 @@ after-free the `ptr` because the Box is immediately marked as uninitialized. However this wouldn't work: ```rust -struct Box{ ptr: *mut T } +#![feature(heap_api, core_intrinsics, unique)] + +use std::rt::heap; +use std::ptr::Unique; +use std::intrinsics::drop_in_place; +use std::mem; + +struct Box{ ptr: Unique } impl Drop for Box { fn drop(&mut self) { unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); + drop_in_place(*self.ptr); + heap::deallocate((*self.ptr) as *mut u8, + mem::size_of::(), + mem::align_of::()); } } } -struct SuperBox { box: Box } +struct SuperBox { my_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); + heap::deallocate((*self.my_box.ptr) as *mut u8, + mem::size_of::(), + mem::align_of::()); } } } @@ -106,18 +126,27 @@ The classic safe solution to overriding recursive drop and allowing moving out of Self during `drop` is to use an Option: ```rust -struct Box{ ptr: *mut T } +#![feature(heap_api, core_intrinsics, unique)] + +use std::rt::heap; +use std::ptr::Unique; +use std::intrinsics::drop_in_place; +use std::mem; + +struct Box{ ptr: Unique } impl Drop for Box { fn drop(&mut self) { unsafe { - (*self.ptr).drop(); - heap::deallocate(self.ptr); + drop_in_place(*self.ptr); + heap::deallocate((*self.ptr) as *mut u8, + mem::size_of::(), + mem::align_of::()); } } } -struct SuperBox { box: Option> } +struct SuperBox { my_box: Option> } impl Drop for SuperBox { fn drop(&mut self) { @@ -125,7 +154,11 @@ impl Drop for SuperBox { // Hyper-optimized: deallocate the box's contents for it // without `drop`ing the contents. Need to set the `box` // field as `None` to prevent Rust from trying to Drop it. - heap::deallocate(self.box.take().unwrap().ptr); + let my_box = self.my_box.take().unwrap(); + heap::deallocate((*my_box.ptr) as *mut u8, + mem::size_of::(), + mem::align_of::()); + mem::forget(my_box); } } } diff --git a/src/doc/tarpl/drop-flags.md b/src/doc/tarpl/drop-flags.md index 68f7ffc77b006..e8c331cd05659 100644 --- a/src/doc/tarpl/drop-flags.md +++ b/src/doc/tarpl/drop-flags.md @@ -31,6 +31,7 @@ And even branched code where all branches have the same behaviour with respect to initialization: ```rust +# let condition = true; let mut x = Box::new(0); // x was uninit; just overwrite. if condition { drop(x) // x gets moved out; make x uninit. @@ -45,6 +46,7 @@ x = Box::new(0); // x was uninit; just overwrite. However code like this *requires* runtime information to correctly Drop: ```rust +# let condition = true; let x; if condition { x = Box::new(0); // x was uninit; just overwrite. @@ -56,6 +58,7 @@ if condition { Of course, in this case it's trivial to retrieve static drop semantics: ```rust +# let condition = true; if condition { let x = Box::new(0); println!("{}", x); diff --git a/src/doc/tarpl/exception-safety.md b/src/doc/tarpl/exception-safety.md index ca33109781127..9a31934090340 100644 --- a/src/doc/tarpl/exception-safety.md +++ b/src/doc/tarpl/exception-safety.md @@ -156,7 +156,7 @@ way to do this is to store the algorithm's state in a separate struct with a destructor for the "finally" logic. Whether we panic or not, that destructor will run and clean up after us. -```rust +```rust,ignore struct Hole<'a, T: 'a> { data: &'a mut [T], /// `elt` is always `Some` from new until drop. diff --git a/src/doc/tarpl/hrtb.md b/src/doc/tarpl/hrtb.md index c3f25026ef48c..640742f9b1499 100644 --- a/src/doc/tarpl/hrtb.md +++ b/src/doc/tarpl/hrtb.md @@ -28,7 +28,7 @@ fn main() { If we try to naively desugar this code in the same way that we did in the lifetimes section, we run into some trouble: -```rust +```rust,ignore struct Closure { data: (u8, u16), func: F, @@ -60,7 +60,7 @@ we enter the body of `call`! Also, that isn't some fixed lifetime; call works wi This job requires The Magic of Higher-Rank Trait Bounds. The way we desugar this is as follows: -```rust +```rust,ignore where for<'a> F: Fn(&'a (u8, u16)) -> &'a u8, ``` @@ -69,4 +69,4 @@ where for<'a> F: Fn(&'a (u8, u16)) -> &'a u8, `for<'a>` can be read as "for all choices of `'a`", and basically produces an *inifinite list* of trait bounds that F must satisfy. Intense. There aren't many places outside of the Fn traits where we encounter HRTBs, and even for those we -have a nice magic sugar for the common cases. \ No newline at end of file +have a nice magic sugar for the common cases. diff --git a/src/doc/tarpl/leaking.md b/src/doc/tarpl/leaking.md index 1e1e95a243dd4..bb6f7bb4bda09 100644 --- a/src/doc/tarpl/leaking.md +++ b/src/doc/tarpl/leaking.md @@ -68,7 +68,7 @@ unwinding-safe! Easy! Now consider the following: -``` +```rust,ignore let mut vec = vec![Box::new(0); 4]; { @@ -118,7 +118,7 @@ Nope. Let's consider a simplified implementation of Rc: -```rust +```rust,ignore struct Rc { ptr: *mut RcBox, } @@ -183,7 +183,7 @@ in memory. The thread::scoped API intends to allow threads to be spawned that reference data on the stack without any synchronization over that data. Usage looked like: -```rust +```rust,ignore let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; { let guards = vec![]; @@ -211,7 +211,7 @@ let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; In principle, this totally works! Rust's ownership system perfectly ensures it! ...except it relies on a destructor being called to be safe. -``` +```rust,ignore let mut data = Box::new(0); { let guard = thread::scoped(|| { diff --git a/src/doc/tarpl/lifetime-elision.md b/src/doc/tarpl/lifetime-elision.md index eac24330911f4..41014f46dd953 100644 --- a/src/doc/tarpl/lifetime-elision.md +++ b/src/doc/tarpl/lifetime-elision.md @@ -5,7 +5,7 @@ In order to make common patterns more ergonomic, Rust allows lifetimes to be A *lifetime position* is anywhere you can write a lifetime in a type: -```rust +```rust,ignore &'a T &'a mut T T<'a> @@ -38,7 +38,7 @@ Elision rules are as follows: Examples: -```rust +```rust,ignore fn print(s: &str); // elided fn print<'a>(s: &'a str); // expanded @@ -61,4 +61,4 @@ fn args<'a, 'b, T:ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command // exp fn new(buf: &mut [u8]) -> BufWriter; // elided fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded -``` \ No newline at end of file +``` diff --git a/src/doc/tarpl/lifetime-misc.md b/src/doc/tarpl/lifetime-misc.md index faf7f9a1f60b0..bd44bb6964af5 100644 --- a/src/doc/tarpl/lifetime-misc.md +++ b/src/doc/tarpl/lifetime-misc.md @@ -10,8 +10,8 @@ types or lifetimes are logically associated with a struct, but not actually part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` for `&'a [T]` is (approximately) defined as follows: -```rust -pub struct Iter<'a, T: 'a> { +```rust,ignore +struct Iter<'a, T: 'a> { ptr: *const T, end: *const T, } @@ -33,7 +33,9 @@ Iter logically contains `&'a T`, so this is exactly what we tell the PhantomData to simulate: ``` -pub struct Iter<'a, T: 'a> { +use std::marker; + +struct Iter<'a, T: 'a> { ptr: *const T, end: *const T, _marker: marker::PhantomData<&'a T>, @@ -68,6 +70,8 @@ tell dropck that we *do* own values of type T, and may call destructors of that type, we must add extra PhantomData: ``` +use std::marker; + struct Vec { data: *const T, // *const for covariance! len: usize, @@ -115,7 +119,7 @@ println!("{} {} {} {}", a, b, c, c2); However borrowck doesn't understand arrays or slices in any way, so this doesn't work: -```rust +```rust,ignore let x = [1, 2, 3]; let a = &mut x[0]; let b = &mut x[1]; @@ -144,7 +148,7 @@ left of the index, and one for everything to the right. Intuitively we know this is safe because the slices don't alias. However the implementation requires some unsafety: -```rust +```rust,ignore fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { unsafe { let self2: &mut [T] = mem::transmute_copy(&self); @@ -189,8 +193,8 @@ Whether it's raw pointers, or safely composing on top of *another* IterMut. For instance, VecDeque's IterMut: -```rust -pub struct IterMut<'a, T:'a> { +```rust,ignore +struct IterMut<'a, T:'a> { // The whole backing array. Some of these indices are initialized! ring: &'a mut [T], tail: usize, diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/tarpl/lifetimes.md index a06363a92d739..7282e4d843cfd 100644 --- a/src/doc/tarpl/lifetimes.md +++ b/src/doc/tarpl/lifetimes.md @@ -38,7 +38,7 @@ let z = &y; The borrow checker always tries to minimize the extent of a lifetime, so it will likely desugar to the following: -```rust +```rust,ignore // NOTE: `'a: {` and `&'b x` is not valid syntax! 'a: { let x: i32 = 0; @@ -69,8 +69,8 @@ z = y; The borrow checker always tries to minimize the extent of a lifetime, so it will likely desugar to something like the following: -```rust -// NOTE: `'a: {` and `&'b x` is not valid syntax! +```rust,ignore +// NOTE: `'a: {` and `foo = &'b x` is not valid syntax! 'a: { let x: i32 = 0; 'b: { @@ -174,14 +174,14 @@ our implementation *just a bit*.) How about the other example: -```rust +```rust,ignore let mut data = vec![1, 2, 3]; let x = &data[0]; data.push(4); println!("{}", x); ``` -```rust +```rust,ignore 'a: { let mut data: Vec = vec![1, 2, 3]; 'b: { @@ -219,4 +219,4 @@ semantics we're actually interested in preserving. For the most part, *that's totally ok*, because it keeps us from spending all day explaining our program to the compiler. However it does mean that several programs that are *totally* correct with respect to Rust's *true* semantics are rejected because lifetimes -are too dumb. \ No newline at end of file +are too dumb. diff --git a/src/doc/tarpl/ownership.md b/src/doc/tarpl/ownership.md index 9c4f92a4394ee..200337a2256e3 100644 --- a/src/doc/tarpl/ownership.md +++ b/src/doc/tarpl/ownership.md @@ -16,7 +16,7 @@ issue...). This is a pervasive problem that C and C++ need to deal with. Consider this simple mistake that all of us who have used a non-GC'd language have made at one point: -```rust +```rust,ignore fn as_str(data: &u32) -> &str { // compute the string let s = format!("{}", data); @@ -45,7 +45,7 @@ verifying that references don't escape the scope of their referent. That's because ensuring pointers are always valid is much more complicated than this. For instance in this code, -```rust +```rust,ignore let mut data = vec![1, 2, 3]; // get an internal reference let x = &data[0]; diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/tarpl/repr-rust.md index a1f5f29f8d85e..b3a5a1278c78c 100644 --- a/src/doc/tarpl/repr-rust.md +++ b/src/doc/tarpl/repr-rust.md @@ -67,7 +67,7 @@ fields in the order specified, we expect it to *pad* the values in the struct to their *alignment* requirements. So if Rust didn't reorder fields, we would expect Rust to produce the following: -```rust +```rust,ignore struct Foo { count: u16, data1: u16, diff --git a/src/doc/tarpl/send-and-sync.md b/src/doc/tarpl/send-and-sync.md index 6045d3d0378ad..5b00709a1bf40 100644 --- a/src/doc/tarpl/send-and-sync.md +++ b/src/doc/tarpl/send-and-sync.md @@ -56,6 +56,8 @@ In the *incredibly rare* case that a type is *inappropriately* automatically derived to be Send or Sync, then one can also *unimplement* Send and Sync: ```rust +#![feature(optin_builtin_traits)] + struct SpecialThreadToken(u8); impl !Send for SpecialThreadToken {} diff --git a/src/doc/tarpl/subtyping.md b/src/doc/tarpl/subtyping.md index 24f974ca73ac8..e43c365bf4f71 100644 --- a/src/doc/tarpl/subtyping.md +++ b/src/doc/tarpl/subtyping.md @@ -104,7 +104,7 @@ However what should happen when passing *by-value* is less obvious. It turns out that, yes, you can use subtyping when passing by-value. That is, this works: ```rust -fn get_box<'a>(&'a u8) -> Box<&'a str> { +fn get_box<'a>(str: &'a u8) -> Box<&'a str> { // string literals are `&'static str`s Box::new("hello") } @@ -123,7 +123,7 @@ must be invariant to avoid lifetime smuggling. `Fn(T) -> U` should be invariant over T, consider the following function signature: -```rust +```rust,ignore // 'a is derived from some parent scope fn foo(&'a str) -> usize; ``` @@ -131,7 +131,7 @@ fn foo(&'a str) -> usize; This signature claims that it can handle any `&str` that lives *at least* as long as `'a`. Now if this signature was variant with respect to `&str`, that would mean -```rust +```rust,ignore fn foo(&'static str) -> usize; ``` @@ -142,7 +142,7 @@ and nothing else. Therefore functions are not variant over their arguments. To see why `Fn(T) -> U` should be *variant* over U, consider the following function signature: -```rust +```rust,ignore // 'a is derived from some parent scope fn foo(usize) -> &'a str; ``` @@ -150,7 +150,7 @@ fn foo(usize) -> &'a str; This signature claims that it will return something that outlives `'a`. It is therefore completely reasonable to provide -```rust +```rust,ignore fn foo(usize) -> &'static str; ``` @@ -171,15 +171,17 @@ in multiple fields. * Otherwise, Foo is invariant over A ```rust -struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { +use std::cell::Cell; + +struct Foo<'a, 'b, A: 'a, B: 'b, C, D, E, F, G, H> { a: &'a A, // variant over 'a and A b: &'b mut B, // invariant over 'b and B c: *const C, // variant over C d: *mut D, // invariant over D e: Vec, // variant over E f: Cell, // invariant over F - g: G // variant over G - h1: H // would also be variant over H except... - h2: Cell // invariant over H, because invariance wins + g: G, // variant over G + h1: H, // would also be variant over H except... + h2: Cell, // invariant over H, because invariance wins } -``` \ No newline at end of file +``` diff --git a/src/doc/tarpl/unbounded-lifetimes.md b/src/doc/tarpl/unbounded-lifetimes.md index 24caeeb36aaab..b540ab4ed5d99 100644 --- a/src/doc/tarpl/unbounded-lifetimes.md +++ b/src/doc/tarpl/unbounded-lifetimes.md @@ -17,7 +17,7 @@ boundaries. Given a function, any output lifetimes that don't derive from inputs are unbounded. For instance: -```rust +```rust,ignore fn get_str<'a>() -> &'a str; ``` diff --git a/src/doc/tarpl/unchecked-uninit.md b/src/doc/tarpl/unchecked-uninit.md index f5c0fb4059935..9ab97b9e2d2d2 100644 --- a/src/doc/tarpl/unchecked-uninit.md +++ b/src/doc/tarpl/unchecked-uninit.md @@ -46,27 +46,26 @@ 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 - // NOTE: exception safety is not a concern; Box can't panic - ptr::write(&mut x[i], Box::new(i)); - } +use std::mem; +use std::ptr; + +// 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: usize = 10; + +let mut 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 + // NOTE: exception safety is not a concern; Box can't panic + ptr::write(&mut x[i], Box::new(i as u32)); } - - println!("{}", x); } + +println!("{:?}", x); ``` It's worth noting that you don't need to worry about ptr::write-style @@ -83,4 +82,4 @@ before it ends, if has a destructor. 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. \ No newline at end of file +it around at all, be sure to be *really* careful. diff --git a/src/doc/tarpl/vec-alloc.md b/src/doc/tarpl/vec-alloc.md index a51f23ca4b8b1..e9c9f681ed84a 100644 --- a/src/doc/tarpl/vec-alloc.md +++ b/src/doc/tarpl/vec-alloc.md @@ -2,7 +2,7 @@ So: -```rust +```rust,ignore #![feature(heap_api)] use std::rt::heap::EMPTY; @@ -69,7 +69,7 @@ Anything else will use up too much space. However since this is a tutorial, we're not going to be particularly optimal here, and just unconditionally check, rather than use clever platform-specific `cfg`s. -```rust +```rust,ignore fn grow(&mut self) { // this is all pretty delicate, so let's say it's all unsafe unsafe { diff --git a/src/doc/tarpl/vec-dealloc.md b/src/doc/tarpl/vec-dealloc.md index a83d24d7b49c9..2ae2477bbacdb 100644 --- a/src/doc/tarpl/vec-dealloc.md +++ b/src/doc/tarpl/vec-dealloc.md @@ -11,13 +11,13 @@ We must not call `heap::deallocate` when `self.cap == 0`, as in this case we hav actually allocated any memory. -```rust +```rust,ignore impl Drop for Vec { fn drop(&mut self) { if self.cap != 0 { while let Some(_) = self.pop() { } - let align = mem::min_align_of::(); + let align = mem::align_of::(); let elem_size = mem::size_of::(); let num_bytes = elem_size * self.cap; unsafe { diff --git a/src/doc/tarpl/vec-deref.md b/src/doc/tarpl/vec-deref.md index b07d784939ae6..826d763f5bbcb 100644 --- a/src/doc/tarpl/vec-deref.md +++ b/src/doc/tarpl/vec-deref.md @@ -9,7 +9,7 @@ conditions. All we need is `slice::from_raw_parts`. -```rust +```rust,ignore use std::ops::Deref; impl Deref for Vec { @@ -24,7 +24,7 @@ impl Deref for Vec { And let's do DerefMut too: -```rust +```rust,ignore use std::ops::DerefMut; impl DerefMut for Vec { diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/tarpl/vec-drain.md index 0a53e8bdfad9c..8dd085d6ebcd8 100644 --- a/src/doc/tarpl/vec-drain.md +++ b/src/doc/tarpl/vec-drain.md @@ -51,7 +51,7 @@ impl RawValIter { And IntoIter becomes the following: -``` +```rust,ignore pub struct IntoIter { _buf: RawVec, // we don't actually care about this. Just need it to live. iter: RawValIter, @@ -96,7 +96,7 @@ We also take a slice to simplify Drain initialization. Alright, now Drain is really easy: -```rust +```rust,ignore use std::marker::PhantomData; pub struct Drain<'a, T: 'a> { @@ -174,7 +174,7 @@ overflow for zero-sized types. Due to our current architecture, all this means is writing 3 guards, one in each method of RawVec. -```rust +```rust,ignore impl RawVec { fn new() -> Self { unsafe { @@ -194,7 +194,7 @@ impl RawVec { // 0, getting to here necessarily means the Vec is overfull. assert!(elem_size != 0, "capacity overflow"); - let align = mem::min_align_of::(); + let align = mem::align_of::(); let (new_cap, ptr) = if self.cap == 0 { let ptr = heap::allocate(elem_size, align); @@ -223,7 +223,7 @@ impl Drop for RawVec { // don't free zero-sized allocations, as they were never allocated. if self.cap != 0 && elem_size != 0 { - let align = mem::min_align_of::(); + let align = mem::align_of::(); let num_bytes = elem_size * self.cap; unsafe { @@ -247,7 +247,7 @@ initialize `start` and `end` as the same value, and our iterators will yield nothing. The current solution to this is to cast the pointers to integers, increment, and then cast them back: -``` +```rust,ignore impl RawValIter { unsafe fn new(slice: &[T]) -> Self { RawValIter { @@ -270,7 +270,7 @@ Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll basically be treating the two pointers as if they point to bytes, we'll just map size 0 to divide by 1. -``` +```rust,ignore impl Iterator for RawValIter { type Item = T; fn next(&mut self) -> Option { @@ -315,4 +315,4 @@ impl DoubleEndedIterator for RawValIter { } ``` -And that's it. Iteration works! \ No newline at end of file +And that's it. Iteration works! diff --git a/src/doc/tarpl/vec-final.md b/src/doc/tarpl/vec-final.md index 96fcf6d471030..847957e2ea977 100644 --- a/src/doc/tarpl/vec-final.md +++ b/src/doc/tarpl/vec-final.md @@ -38,7 +38,7 @@ impl RawVec { // 0, getting to here necessarily means the Vec is overfull. assert!(elem_size != 0, "capacity overflow"); - let align = mem::min_align_of::(); + let align = mem::align_of::(); let (new_cap, ptr) = if self.cap == 0 { let ptr = heap::allocate(elem_size, align); @@ -65,7 +65,7 @@ impl Drop for RawVec { fn drop(&mut self) { let elem_size = mem::size_of::(); if self.cap != 0 && elem_size != 0 { - let align = mem::min_align_of::(); + let align = mem::align_of::(); let num_bytes = elem_size * self.cap; unsafe { @@ -306,4 +306,6 @@ impl<'a, T> Drop for Drain<'a, T> { fn oom() { ::std::process::exit(-9999); } -``` \ No newline at end of file + +# fn main() {} +``` diff --git a/src/doc/tarpl/vec-insert-remove.md b/src/doc/tarpl/vec-insert-remove.md index 42d114c4a4495..f21ed227d84ca 100644 --- a/src/doc/tarpl/vec-insert-remove.md +++ b/src/doc/tarpl/vec-insert-remove.md @@ -11,7 +11,7 @@ here). If we insert at index `i`, we want to shift the `[i .. len]` to `[i+1 .. len+1]` using the *old* len. -```rust +```rust,ignore pub fn insert(&mut self, index: usize, elem: T) { // Note: `<=` because it's valid to insert after everything // which would be equivalent to push. @@ -34,7 +34,7 @@ pub fn insert(&mut self, index: usize, elem: T) { Remove behaves in the opposite manner. We need to shift all the elements from `[i+1 .. len + 1]` to `[i .. len]` using the *new* len. -```rust +```rust,ignore pub fn remove(&mut self, index: usize) -> T { // Note: `<` because it's *not* valid to remove after everything assert!(index < self.len, "index out of bounds"); @@ -47,4 +47,4 @@ pub fn remove(&mut self, index: usize) -> T { result } } -``` \ No newline at end of file +``` diff --git a/src/doc/tarpl/vec-into-iter.md b/src/doc/tarpl/vec-into-iter.md index b7e7d2bdc42df..d21cf940fcc10 100644 --- a/src/doc/tarpl/vec-into-iter.md +++ b/src/doc/tarpl/vec-into-iter.md @@ -37,7 +37,7 @@ indistinguishable from the case where there are no more elements to yield. So we're going to use the following struct: -```rust +```rust,ignore struct IntoIter { buf: Unique, cap: usize, @@ -63,7 +63,7 @@ cap or len being 0 to not do the offset. So this is what we end up with for initialization: -```rust +```rust,ignore impl Vec { fn into_iter(self) -> IntoIter { // Can't destructure Vec since it's Drop @@ -93,7 +93,7 @@ impl Vec { Here's iterating forward: -```rust +```rust,ignore impl Iterator for IntoIter { type Item = T; fn next(&mut self) -> Option { @@ -118,7 +118,7 @@ impl Iterator for IntoIter { And here's iterating backwards. -```rust +```rust,ignore impl DoubleEndedIterator for IntoIter { fn next_back(&mut self) -> Option { if self.start == self.end { @@ -138,14 +138,14 @@ to free it. However it *also* wants to implement Drop to drop any elements it contains that weren't yielded. -```rust +```rust,ignore impl Drop for IntoIter { fn drop(&mut self) { if self.cap != 0 { // drop any remaining elements for _ in &mut *self {} - let align = mem::min_align_of::(); + let align = mem::align_of::(); let elem_size = mem::size_of::(); let num_bytes = elem_size * self.cap; unsafe { @@ -164,7 +164,7 @@ compression. We're going to abstract out the `(ptr, cap)` pair and give them the logic for allocating, growing, and freeing: -```rust +```rust,ignore struct RawVec { ptr: Unique, @@ -182,7 +182,7 @@ impl RawVec { // unchanged from Vec fn grow(&mut self) { unsafe { - let align = mem::min_align_of::(); + let align = mem::align_of::(); let elem_size = mem::size_of::(); let (new_cap, ptr) = if self.cap == 0 { @@ -210,7 +210,7 @@ impl RawVec { impl Drop for RawVec { fn drop(&mut self) { if self.cap != 0 { - let align = mem::min_align_of::(); + let align = mem::align_of::(); let elem_size = mem::size_of::(); let num_bytes = elem_size * self.cap; unsafe { @@ -223,7 +223,7 @@ impl Drop for RawVec { And change vec as follows: -```rust +```rust,ignore pub struct Vec { buf: RawVec, len: usize, @@ -254,14 +254,14 @@ impl Drop for Vec { And finally we can really simplify IntoIter: -```rust +```rust,ignore struct IntoIter { _buf: RawVec, // we don't actually care about this. Just need it to live. start: *const T, end: *const T, } -// next and next_back litterally unchanged since they never referred to the buf +// next and next_back literally unchanged since they never referred to the buf impl Drop for IntoIter { fn drop(&mut self) { @@ -290,4 +290,4 @@ impl Vec { } ``` -Much better. \ No newline at end of file +Much better. diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/tarpl/vec-layout.md index 0f85e4d27cefe..128ad15f7950f 100644 --- a/src/doc/tarpl/vec-layout.md +++ b/src/doc/tarpl/vec-layout.md @@ -4,11 +4,13 @@ First off, we need to come up with the struct layout. Naively we want this design: ```rust -struct Vec { +pub struct Vec { ptr: *mut T, cap: usize, len: usize, } + +# fn main() {} ``` And indeed this would compile. Unfortunately, it would be incorrect. The compiler @@ -32,6 +34,8 @@ pub struct Vec { cap: usize, len: usize, } + +# fn main() {} ``` As a recap, Unique is a wrapper around a raw pointer that declares that: diff --git a/src/doc/tarpl/vec-push-pop.md b/src/doc/tarpl/vec-push-pop.md index d1584a2342100..2ef15e324b6e9 100644 --- a/src/doc/tarpl/vec-push-pop.md +++ b/src/doc/tarpl/vec-push-pop.md @@ -17,7 +17,7 @@ target address with the bits of the value we provide. No evaluation involved. For `push`, if the old len (before push was called) is 0, then we want to write to the 0th index. So we should offset by the old len. -```rust +```rust,ignore pub fn push(&mut self, elem: T) { if self.len == self.cap { self.grow(); } @@ -41,7 +41,7 @@ of T there. For `pop`, if the old len is 1, we want to read out of the 0th index. So we should offset by the *new* len. -```rust +```rust,ignore pub fn pop(&mut self) -> Option { if self.len == 0 { None @@ -52,4 +52,4 @@ pub fn pop(&mut self) -> Option { } } } -``` \ No newline at end of file +``` diff --git a/src/doc/tarpl/working-with-unsafe.md b/src/doc/tarpl/working-with-unsafe.md index 69d0b31cf88d6..0aeb2c0dc2580 100644 --- a/src/doc/tarpl/working-with-unsafe.md +++ b/src/doc/tarpl/working-with-unsafe.md @@ -5,7 +5,7 @@ binary manner. Unfortunately, reality is significantly more complicated than tha For instance, consider the following toy function: ```rust -pub fn index(idx: usize, arr: &[u8]) -> Option { +fn index(idx: usize, arr: &[u8]) -> Option { if idx < arr.len() { unsafe { Some(*arr.get_unchecked(idx)) @@ -22,7 +22,7 @@ function, the scope of the unsafe block is questionable. Consider changing the `<` to a `<=`: ```rust -pub fn index(idx: usize, arr: &[u8]) -> Option { +fn index(idx: usize, arr: &[u8]) -> Option { if idx <= arr.len() { unsafe { Some(*arr.get_unchecked(idx)) @@ -44,7 +44,9 @@ Trickier than that is when we get into actual statefulness. Consider a simple implementation of `Vec`: ```rust -// Note this definition is insufficient. See the section on lifetimes. +use std::ptr; + +// Note this definition is insufficient. See the section on implementing Vec. pub struct Vec { ptr: *mut T, len: usize, @@ -61,21 +63,25 @@ impl Vec { self.reallocate(); } unsafe { - ptr::write(self.ptr.offset(len as isize), elem); + ptr::write(self.ptr.offset(self.len as isize), elem); self.len += 1; } } + + # fn reallocate(&mut self) { } } + +# fn main() {} ``` This code is simple enough to reasonably audit and verify. Now consider adding the following method: -```rust - fn make_room(&mut self) { - // grow the capacity - self.cap += 1; - } +```rust,ignore +fn make_room(&mut self) { + // grow the capacity + self.cap += 1; +} ``` This code is safe, but it is also completely unsound. Changing the capacity From 700895fdd7fcd19ffc00639d9fede532ffeb7952 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 14 Jul 2015 14:41:53 -0700 Subject: [PATCH 074/104] split out vec-zsts correctly --- src/doc/tarpl/SUMMARY.md | 1 + src/doc/tarpl/vec-zsts.md | 176 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 src/doc/tarpl/vec-zsts.md diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/tarpl/SUMMARY.md index 8a8ea6dfab799..4b38b7faca557 100644 --- a/src/doc/tarpl/SUMMARY.md +++ b/src/doc/tarpl/SUMMARY.md @@ -45,5 +45,6 @@ * [Insert and Remove](vec-insert-remove.md) * [IntoIter](vec-into-iter.md) * [Drain](vec-drain.md) + * [Handling Zero-Sized Types](vec-zsts.md) * [Final Code](vec-final.md) * [Implementing Arc and Mutex](arc-and-mutex.md) diff --git a/src/doc/tarpl/vec-zsts.md b/src/doc/tarpl/vec-zsts.md new file mode 100644 index 0000000000000..931aed33ef5d5 --- /dev/null +++ b/src/doc/tarpl/vec-zsts.md @@ -0,0 +1,176 @@ +% Handling Zero-Sized Types + +It's time. We're going to fight the spectre that is zero-sized types. Safe Rust +*never* needs to care about this, but Vec is very intensive on raw pointers and +raw allocations, which are exactly the *only* two things that care about +zero-sized types. We need to be careful of two things: + +* The raw allocator API has undefined behaviour if you pass in 0 for an + allocation size. +* raw pointer offsets are no-ops for zero-sized types, which will break our + C-style pointer iterator. + +Thankfully we abstracted out pointer-iterators and allocating handling into +RawValIter and RawVec respectively. How mysteriously convenient. + + + + +## Allocating Zero-Sized Types + +So if the allocator API doesn't support zero-sized allocations, what on earth +do we store as our allocation? Why, `heap::EMPTY` of course! Almost every operation +with a ZST is a no-op since ZSTs have exactly one value, and therefore no state needs +to be considered to store or load them. This actually extends to `ptr::read` and +`ptr::write`: they won't actually look at the pointer at all. As such we *never* need +to change the pointer. + +Note however that our previous reliance on running out of memory before overflow is +no longer valid with zero-sized types. We must explicitly guard against capacity +overflow for zero-sized types. + +Due to our current architecture, all this means is writing 3 guards, one in each +method of RawVec. + +```rust,ignore +impl RawVec { + fn new() -> Self { + unsafe { + // !0 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { !0 } else { 0 }; + + // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } + } + } + + fn grow(&mut self) { + unsafe { + let elem_size = mem::size_of::(); + + // since we set the capacity to usize::MAX when elem_size is + // 0, getting to here necessarily means the Vec is overfull. + assert!(elem_size != 0, "capacity overflow"); + + let align = mem::align_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + +impl Drop for RawVec { + fn drop(&mut self) { + let elem_size = mem::size_of::(); + + // don't free zero-sized allocations, as they were never allocated. + if self.cap != 0 && elem_size != 0 { + let align = mem::align_of::(); + + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +That's it. We support pushing and popping zero-sized types now. Our iterators +(that aren't provided by slice Deref) are still busted, though. + + + + +## Iterating Zero-Sized Types + +Zero-sized offsets are no-ops. This means that our current design will always +initialize `start` and `end` as the same value, and our iterators will yield +nothing. The current solution to this is to cast the pointers to integers, +increment, and then cast them back: + +```rust,ignore +impl RawValIter { + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if mem::size_of::() == 0 { + ((slice.as_ptr() as usize) + slice.len()) as *const _ + } else if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} +``` + +Now we have a different bug. Instead of our iterators not running at all, our +iterators now run *forever*. We need to do the same trick in our iterator impls. +Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll +basically be treating the two pointers as if they point to bytes, we'll just +map size 0 to divide by 1. + +```rust,ignore +impl Iterator for RawValIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = if mem::size_of::() == 0 { + (self.start as usize + 1) as *const _ + } else { + self.start.offset(1); + } + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let elem_size = mem::size_of::(); + let len = (self.end as usize - self.start as usize) + / if elem_size == 0 { 1 } else { elem_size }; + (len, Some(len)) + } +} + +impl DoubleEndedIterator for RawValIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = if mem::size_of::() == 0 { + (self.end as usize - 1) as *const _ + } else { + self.end.offset(-1); + } + Some(ptr::read(self.end)) + } + } + } +} +``` + +And that's it. Iteration works! From c5a1b87c6f95e023ab465514aac143bdbd88f56b Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 14 Jul 2015 17:59:28 -0700 Subject: [PATCH 075/104] properly remove moved text --- src/doc/tarpl/vec-drain.md | 177 ------------------------------------- 1 file changed, 177 deletions(-) diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/tarpl/vec-drain.md index 8dd085d6ebcd8..df7cf00b99b68 100644 --- a/src/doc/tarpl/vec-drain.md +++ b/src/doc/tarpl/vec-drain.md @@ -139,180 +139,3 @@ impl Vec { - -# Handling Zero-Sized Types - -It's time. We're going to fight the spectre that is zero-sized types. Safe Rust -*never* needs to care about this, but Vec is very intensive on raw pointers and -raw allocations, which are exactly the *only* two things that care about -zero-sized types. We need to be careful of two things: - -* The raw allocator API has undefined behaviour if you pass in 0 for an - allocation size. -* raw pointer offsets are no-ops for zero-sized types, which will break our - C-style pointer iterator. - -Thankfully we abstracted out pointer-iterators and allocating handling into -RawValIter and RawVec respectively. How mysteriously convenient. - - - - -## Allocating Zero-Sized Types - -So if the allocator API doesn't support zero-sized allocations, what on earth -do we store as our allocation? Why, `heap::EMPTY` of course! Almost every operation -with a ZST is a no-op since ZSTs have exactly one value, and therefore no state needs -to be considered to store or load them. This actually extends to `ptr::read` and -`ptr::write`: they won't actually look at the pointer at all. As such we *never* need -to change the pointer. - -Note however that our previous reliance on running out of memory before overflow is -no longer valid with zero-sized types. We must explicitly guard against capacity -overflow for zero-sized types. - -Due to our current architecture, all this means is writing 3 guards, one in each -method of RawVec. - -```rust,ignore -impl RawVec { - fn new() -> Self { - unsafe { - // !0 is usize::MAX. This branch should be stripped at compile time. - let cap = if mem::size_of::() == 0 { !0 } else { 0 }; - - // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" - RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } - } - } - - fn grow(&mut self) { - unsafe { - let elem_size = mem::size_of::(); - - // since we set the capacity to usize::MAX when elem_size is - // 0, getting to here necessarily means the Vec is overfull. - assert!(elem_size != 0, "capacity overflow"); - - let align = mem::align_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - let new_cap = 2 * self.cap; - let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } - } -} - -impl Drop for RawVec { - fn drop(&mut self) { - let elem_size = mem::size_of::(); - - // don't free zero-sized allocations, as they were never allocated. - if self.cap != 0 && elem_size != 0 { - let align = mem::align_of::(); - - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr as *mut _, num_bytes, align); - } - } - } -} -``` - -That's it. We support pushing and popping zero-sized types now. Our iterators -(that aren't provided by slice Deref) are still busted, though. - - - - -## Iterating Zero-Sized Types - -Zero-sized offsets are no-ops. This means that our current design will always -initialize `start` and `end` as the same value, and our iterators will yield -nothing. The current solution to this is to cast the pointers to integers, -increment, and then cast them back: - -```rust,ignore -impl RawValIter { - unsafe fn new(slice: &[T]) -> Self { - RawValIter { - start: slice.as_ptr(), - end: if mem::size_of::() == 0 { - ((slice.as_ptr() as usize) + slice.len()) as *const _ - } else if slice.len() == 0 { - slice.as_ptr() - } else { - slice.as_ptr().offset(slice.len() as isize) - } - } - } -} -``` - -Now we have a different bug. Instead of our iterators not running at all, our -iterators now run *forever*. We need to do the same trick in our iterator impls. -Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll -basically be treating the two pointers as if they point to bytes, we'll just -map size 0 to divide by 1. - -```rust,ignore -impl Iterator for RawValIter { - type Item = T; - fn next(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - let result = ptr::read(self.start); - self.start = if mem::size_of::() == 0 { - (self.start as usize + 1) as *const _ - } else { - self.start.offset(1); - } - Some(result) - } - } - } - - fn size_hint(&self) -> (usize, Option) { - let elem_size = mem::size_of::(); - let len = (self.end as usize - self.start as usize) - / if elem_size == 0 { 1 } else { elem_size }; - (len, Some(len)) - } -} - -impl DoubleEndedIterator for RawValIter { - fn next_back(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - self.end = if mem::size_of::() == 0 { - (self.end as usize - 1) as *const _ - } else { - self.end.offset(-1); - } - Some(ptr::read(self.end)) - } - } - } -} -``` - -And that's it. Iteration works! From d1b899e57a7aa5cec0380900465e0d7d443762d2 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 17 Jul 2015 11:46:02 -0700 Subject: [PATCH 076/104] update subtyping to be a bit clearer about reference variance --- src/doc/tarpl/subtyping.md | 119 ++++++++++++++++++++++--------------- 1 file changed, 70 insertions(+), 49 deletions(-) diff --git a/src/doc/tarpl/subtyping.md b/src/doc/tarpl/subtyping.md index e43c365bf4f71..1b33c9abaa1bb 100644 --- a/src/doc/tarpl/subtyping.md +++ b/src/doc/tarpl/subtyping.md @@ -1,27 +1,28 @@ % Subtyping and Variance -Although Rust doesn't have any notion of inheritance, it *does* include subtyping. -In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are scopes, -we can partially order them based on the *contains* (outlives) relationship. We -can even express this as a generic bound. +Although Rust doesn't have any notion of inheritance, it *does* include +subtyping. In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes +are scopes, we can partially order them based on the *contains* (outlives) +relationship. We can even express this as a generic bound. -Subtyping on lifetimes in terms of that relationship: if `'a: 'b` -("a contains b" or "a outlives b"), then `'a` is a subtype of `'b`. This is a -large source of confusion, because it seems intuitively backwards to many: -the bigger scope is a *sub type* of the smaller scope. +Subtyping on lifetimes in terms of that relationship: if `'a: 'b` ("a contains +b" or "a outlives b"), then `'a` is a subtype of `'b`. This is a large source of +confusion, because it seems intuitively backwards to many: the bigger scope is a +*sub type* of the smaller scope. This does in fact make sense, though. The intuitive reason for this is that if -you expect an `&'a u8`, then it's totally fine for me to hand you an `&'static u8`, -in the same way that if you expect an Animal in Java, it's totally fine for me to -hand you a Cat. Cats are just Animals *and more*, just as `'static` is just `'a` -*and more*. +you expect an `&'a u8`, then it's totally fine for me to hand you an `&'static +u8`, in the same way that if you expect an Animal in Java, it's totally fine for +me to hand you a Cat. Cats are just Animals *and more*, just as `'static` is +just `'a` *and more*. -(Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary -construct that some disagree with. However it simplifies our analysis to treat -lifetimes and types uniformly.) +(Note, the subtyping relationship and typed-ness of lifetimes is a fairly +arbitrary construct that some disagree with. However it simplifies our analysis +to treat lifetimes and types uniformly.) -Higher-ranked lifetimes are also subtypes of every concrete lifetime. This is because -taking an arbitrary lifetime is strictly more general than taking a specific one. +Higher-ranked lifetimes are also subtypes of every concrete lifetime. This is +because taking an arbitrary lifetime is strictly more general than taking a +specific one. @@ -29,37 +30,49 @@ taking an arbitrary lifetime is strictly more general than taking a specific one Variance is where things get a bit complicated. -Variance is a property that *type constructors* have. A type constructor in Rust -is a generic type with unbound arguments. For instance `Vec` is a type constructor -that takes a `T` and returns a `Vec`. `&` and `&mut` are type constructors that -take a two types: a lifetime, and a type to point to. +Variance is a property that *type constructors* have with respect to their +arguments. A type constructor in Rust is a generic type with unbound arguments. +For instance `Vec` is a type constructor that takes a `T` and returns a +`Vec`. `&` and `&mut` are type constructors that take a two types: a +lifetime, and a type to point to. A type constructor's *variance* is how the subtyping of its inputs affects the subtyping of its outputs. There are two kinds of variance in Rust: -* F is *variant* if `T` being a subtype of `U` implies `F` is a subtype of `F` -* F is *invariant* otherwise (no subtyping relation can be derived) +* F is *variant* over `T` if `T` being a subtype of `U` implies + `F` is a subtype of `F` (subtyping "passes through") +* F is *invariant* over `T` otherwise (no subtyping relation can be derived) -(For those of you who are familiar with variance from other languages, what we refer -to as "just" variance is in fact *covariance*. Rust does not have contravariance. -Historically Rust did have some contravariance but it was scrapped due to poor -interactions with other features.) +(For those of you who are familiar with variance from other languages, what we +refer to as "just" variance is in fact *covariance*. Rust does not have +contravariance. Historically Rust did have some contravariance but it was +scrapped due to poor interactions with other features. If you experience +contravariance in Rust call your local compiler developer for medical advice.) Some important variances: -* `&` is variant (as is `*const` by metaphor) -* `&mut` is invariant -* `Fn(T) -> U` is invariant with respect to `T`, but variant with respect to `U` -* `Box`, `Vec`, and all other collections are variant -* `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" - types are invariant (as is `*mut` by metaphor) +* `&'a T` is variant over `'a` and `T` (as is `*const T` by metaphor) +* `&'a mut T` is variant with over `'a` but invariant over `T` +* `Fn(T) -> U` is invariant over `T`, but variant over `U` +* `Box`, `Vec`, and all other collections are variant over their contents +* `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all other + interior mutability types are invariant over T (as is `*mut T` by metaphor) -To understand why these variances are correct and desirable, we will consider several -examples. We have already covered why `&` should be variant when introducing subtyping: -it's desirable to be able to pass longer-lived things where shorter-lived things are -needed. +To understand why these variances are correct and desirable, we will consider +several examples. -To see why `&mut` should be invariant, consider the following code: + +We have already covered why `&'a T` should be variant over `'a` when +introducing subtyping: it's desirable to be able to pass longer-lived things +where shorter-lived things are needed. + +Similar reasoning applies to why it should be variant over T. It is reasonable +to be able to pass `&&'static str` where an `&&'a str` is expected. The +additional level of indirection does not change the desire to be able to pass +longer lived things where shorted lived things are expected. + +However this logic *does not* apply to see why `&mut`. To see why &mut should +be invariant over T, consider the following code: ```rust,ignore fn overwrite(input: &mut T, new: &mut T) { @@ -78,17 +91,24 @@ fn main() { ``` The signature of `overwrite` is clearly valid: it takes mutable references to -two values of the same type, and overwrites one with the other. If `&mut` was -variant, then `&mut &'a str` would be a subtype of `&mut &'static str`, since -`&'a str` is a subtype of `&'static str`. Therefore the lifetime of +two values of the same type, and overwrites one with the other. If `&mut T` was +variant over T, then `&mut &'a str` would be a subtype of `&mut &'static str`, +since `&'a str` is a subtype of `&'static str`. Therefore the lifetime of `forever_str` would successfully be "shrunk" down to the shorter lifetime of `string`, and `overwrite` would be called successfully. `string` would subsequently be dropped, and `forever_str` would point to freed memory when we print it! Therefore `&mut` should be invariant. -This is the general theme of variance vs -invariance: if variance would allow you to *store* a short-lived value in a -longer-lived slot, then you must be invariant. +This is the general theme of variance vs invariance: if variance would allow you +to *store* a short-lived value over a longer-lived slot, then you must be +invariant. + +However it *is* sound for `&'a mut T` to be variant over `'a`. The key difference +between `'a` and T is that `'a` is a property of the reference itself, +while T is something the reference is borrowing. If you change T's type, then +the source still remembers the original type. However if you change the +lifetime's type, no one but the reference knows this information, so it's fine. +Put another way, `&'a mut T` owns `'a`, but only *borrows* T. `Box` and `Vec` are interesting cases because they're variant, but you can definitely store values in them! This is where Rust gets really clever: it's @@ -115,9 +135,9 @@ Weakening when you pass by-value is fine because there's no one else who trouble was because there's always someone else who remembers the original subtype: the actual owner. -The invariance of the cell types can be seen as follows: `&` is like an `&mut` for a -cell, because you can still store values in them through an `&`. Therefore cells -must be invariant to avoid lifetime smuggling. +The invariance of the cell types can be seen as follows: `&` is like an `&mut` +for a cell, because you can still store values in them through an `&`. Therefore +cells must be invariant to avoid lifetime smuggling. `Fn` is the most subtle case because it has mixed variance. To see why `Fn(T) -> U` should be invariant over T, consider the following function @@ -128,8 +148,9 @@ signature: fn foo(&'a str) -> usize; ``` -This signature claims that it can handle any `&str` that lives *at least* as long -as `'a`. Now if this signature was variant with respect to `&str`, that would mean +This signature claims that it can handle any `&str` that lives *at least* as +long as `'a`. Now if this signature was variant over `&'a str`, that +would mean ```rust,ignore fn foo(&'static str) -> usize; From eba459a5c2abf1c6869f0947e297b0805cdc27ef Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 17 Jul 2015 22:20:11 -0700 Subject: [PATCH 077/104] shard out misc section on lifetimes properly --- src/doc/tarpl/SUMMARY.md | 4 +- src/doc/tarpl/dropck.md | 127 +++++++++++++++++++++++++ src/doc/tarpl/lifetime-splitting.md | 140 ++++++++++++++++++++++++++++ src/doc/tarpl/phantom-data.md | 87 +++++++++++++++++ 4 files changed, 357 insertions(+), 1 deletion(-) create mode 100644 src/doc/tarpl/dropck.md create mode 100644 src/doc/tarpl/lifetime-splitting.md create mode 100644 src/doc/tarpl/phantom-data.md diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/tarpl/SUMMARY.md index 4b38b7faca557..b0d75bfc85c96 100644 --- a/src/doc/tarpl/SUMMARY.md +++ b/src/doc/tarpl/SUMMARY.md @@ -15,7 +15,9 @@ * [Unbounded Lifetimes](unbounded-lifetimes.md) * [Higher-Rank Trait Bounds](hrtb.md) * [Subtyping and Variance](subtyping.md) - * [Misc](lifetime-misc.md) + * [Drop Check](dropck.md) + * [PhantomData](phantom-data.md) + * [Splitting Lifetimes](lifetime-splitting.md) * [Type Conversions](conversions.md) * [Coercions](coercions.md) * [The Dot Operator](dot-operator.md) diff --git a/src/doc/tarpl/dropck.md b/src/doc/tarpl/dropck.md new file mode 100644 index 0000000000000..e1a25f513c7fa --- /dev/null +++ b/src/doc/tarpl/dropck.md @@ -0,0 +1,127 @@ +% Drop Check + +We have seen how lifetimes provide us some fairly simple rules for ensuring +that never read dangling references. However up to this point we have only ever +interacted with the *outlives* relationship in an inclusive manner. That is, +when we talked about `'a: 'b`, it was ok for `'a` to live *exactly* as long as +`'b`. At first glance, this seems to be a meaningless distinction. Nothing ever +gets dropped at the same time as another, right? This is why we used the +following desugarring of `let` statements: + +```rust +let x; +let y; +``` + +```rust +{ + let x; + { + let y; + } +} +``` + +Each creates its own scope, clearly establishing that one drops before the +other. However, what if we do the following? + +```rust +let (x, y) = (vec![], vec![]); +``` + +Does either value strictly outlive the other? The answer is in fact *no*, +neither value strictly outlives the other. Of course, one of x or y will be +dropped before the other, but the actual order is not specified. Tuples aren't +special in this regard; composite structures just don't guarantee their +destruction order as of Rust 1.0. + +We *could* specify this for the fields of built-in composites like tuples and +structs. However, what about something like Vec? Vec has to manually drop its +elements via pure-library code. In general, anything that implements Drop has +a chance to fiddle with its innards during its final death knell. Therefore +the compiler can't sufficiently reason about the actual destruction order +of the contents of any type that implements Drop. + +So why do we care? We care because if the type system isn't careful, it could +accidentally make dangling pointers. Consider the following simple program: + +```rust +struct Inspector<'a>(&'a u8); + +fn main() { + let (days, inspector); + days = Box::new(1); + inspector = Inspector(&days); +} +``` + +This program is totally sound and compiles today. The fact that `days` does +not *strictly* outlive `inspector` doesn't matter. As long as the `inspector` +is alive, so is days. + +However if we add a destructor, the program will no longer compile! + +```rust,ignore +struct Inspector<'a>(&'a u8); + +impl<'a> Drop for Inspector<'a> { + fn drop(&mut self) { + println!("I was only {} days from retirement!", self.0); + } +} + +fn main() { + let (days, inspector); + days = Box::new(1); + inspector = Inspector(&days); + // Let's say `days` happens to get dropped first. + // Then when Inspector is dropped, it will try to read free'd memory! +} +``` + +```text +:12:28: 12:32 error: `days` does not live long enough +:12 inspector = Inspector(&days); + ^~~~ +:9:11: 15:2 note: reference must be valid for the block at 9:10... +:9 fn main() { +:10 let (days, inspector); +:11 days = Box::new(1); +:12 inspector = Inspector(&days); +:13 // Let's say `days` happens to get dropped first. +:14 // Then when Inspector is dropped, it will try to read free'd memory! + ... +:10:27: 15:2 note: ...but borrowed value is only valid for the block suffix following statement 0 at 10:26 +:10 let (days, inspector); +:11 days = Box::new(1); +:12 inspector = Inspector(&days); +:13 // Let's say `days` happens to get dropped first. +:14 // Then when Inspector is dropped, it will try to read free'd memory! +:15 } +``` + +Implementing Drop lets the Inspector execute some arbitrary code *during* its +death. This means it can potentially observe that types that are supposed to +live as long as it does actually were destroyed first. + +Interestingly, only *generic* types need to worry about this. If they aren't +generic, then the only lifetimes they can harbor are `'static`, which will truly +live *forever*. This is why this problem is referred to as *sound generic drop*. +Sound generic drop is enforced by the *drop checker*. As of this writing, some +of the finer details of how the drop checker validates types is totally up in +the air. However The Big Rule is the subtlety that we have focused on this whole +section: + +**For a generic type to soundly implement drop, it must strictly outlive all of +its generic arguments.** + +This rule is sufficient but not necessary to satisfy the drop checker. That is, +if your type obeys this rule then it's *definitely* sound to drop. However +there are special cases where you can fail to satisfy this, but still +successfully pass the borrow checker. These are the precise rules that are +currently up in the air. + +It turns out that when writing unsafe code, we generally don't need to +worry at all about doing the right thing for the drop checker. However there +is *one* special case that you need to worry about, which we will look at in +the next section. diff --git a/src/doc/tarpl/lifetime-splitting.md b/src/doc/tarpl/lifetime-splitting.md new file mode 100644 index 0000000000000..7ab2d379ffd59 --- /dev/null +++ b/src/doc/tarpl/lifetime-splitting.md @@ -0,0 +1,140 @@ +% Splitting Lifetimes + +The mutual exclusion property of mutable references can be very limiting when +working with a composite structure. The borrow checker understands some basic stuff, but +will fall over pretty easily. It *does* understand structs sufficiently to +know that it's possible to borrow disjoint fields of a struct simultaneously. +So this works today: + +```rust +struct Foo { + a: i32, + b: i32, + c: i32, +} + +let mut x = Foo {a: 0, b: 0, c: 0}; +let a = &mut x.a; +let b = &mut x.b; +let c = &x.c; +*b += 1; +let c2 = &x.c; +*a += 10; +println!("{} {} {} {}", a, b, c, c2); +``` + +However borrowck doesn't understand arrays or slices in any way, so this doesn't +work: + +```rust,ignore +let x = [1, 2, 3]; +let a = &mut x[0]; +let b = &mut x[1]; +println!("{} {}", a, b); +``` + +```text +:3:18: 3:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:3 let a = &mut x[0]; + ^~~~ +:4:18: 4:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:4 let b = &mut x[1]; + ^~~~ +error: aborting due to 2 previous errors +``` + +While it was plausible that borrowck could understand this simple case, it's +pretty clearly hopeless for borrowck to understand disjointness in general +container types like a tree, especially if distinct keys actually *do* map +to the same value. + +In order to "teach" borrowck that what we're doing is ok, we need to drop down +to unsafe code. For instance, mutable slices expose a `split_at_mut` function that +consumes the slice and returns *two* mutable slices. One for everything to the +left of the index, and one for everything to the right. Intuitively we know this +is safe because the slices don't alias. However the implementation requires some +unsafety: + +```rust,ignore +fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { + unsafe { + let self2: &mut [T] = mem::transmute_copy(&self); + + (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), + ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) + } +} +``` + +This is pretty plainly dangerous. We use transmute to duplicate the slice with an +*unbounded* lifetime, so that it can be treated as disjoint from the other until +we unify them when we return. + +However more subtle is how iterators that yield mutable references work. +The iterator trait is defined as follows: + +```rust +trait Iterator { + type Item; + + fn next(&mut self) -> Option; +} +``` + +Given this definition, Self::Item has *no* connection to `self`. This means +that we can call `next` several times in a row, and hold onto all the results +*concurrently*. This is perfectly fine for by-value iterators, which have exactly +these semantics. It's also actually fine for shared references, as they admit +arbitrarily many references to the same thing (although the +iterator needs to be a separate object from the thing being shared). But mutable +references make this a mess. At first glance, they might seem completely +incompatible with this API, as it would produce multiple mutable references to +the same object! + +However it actually *does* work, exactly because iterators are one-shot objects. +Everything an IterMut yields will be yielded *at most* once, so we don't *actually* +ever yield multiple mutable references to the same piece of data. + +In general all mutable iterators require *some* unsafe code *somewhere*, though. +Whether it's raw pointers, or safely composing on top of *another* IterMut. + +For instance, VecDeque's IterMut: + +```rust,ignore +struct IterMut<'a, T:'a> { + // The whole backing array. Some of these indices are initialized! + ring: &'a mut [T], + tail: usize, + head: usize, +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option<&'a mut T> { + if self.tail == self.head { + return None; + } + let tail = self.tail; + self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); + + unsafe { + // might as well do unchecked indexing since wrap_index has us + // in-bounds, and many of the "middle" indices are uninitialized + // anyway. + let elem = self.ring.get_unchecked_mut(tail); + + // round-trip through a raw pointer to unbound the lifetime from + // ourselves + Some(&mut *(elem as *mut _)) + } + } +} +``` + +A very subtle but interesting detail in this design is that it *relies on +privacy to be sound*. Borrowck works on some very simple rules. One of those rules +is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut +Bar is *also* live. Since IterMut is always live when `next` can be called, if +`ring` were public then we could mutate `ring` while outstanding mutable borrows +to it exist! diff --git a/src/doc/tarpl/phantom-data.md b/src/doc/tarpl/phantom-data.md new file mode 100644 index 0000000000000..034f31784295d --- /dev/null +++ b/src/doc/tarpl/phantom-data.md @@ -0,0 +1,87 @@ +% PhantomData + +When working with unsafe code, we can often end up in a situation where +types or lifetimes are logically associated with a struct, but not actually +part of a field. This most commonly occurs with lifetimes. For instance, the +`Iter` for `&'a [T]` is (approximately) defined as follows: + +```rust,ignore +struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, +} +``` + +However because `'a` is unused within the struct's body, it's *unbounded*. +Because of the troubles this has historically caused, unbounded lifetimes and +types are *illegal* in struct definitions. Therefore we must somehow refer +to these types in the body. Correctly doing this is necessary to have +correct variance and drop checking. + +We do this using *PhantomData*, which is a special marker type. PhantomData +consumes no space, but simulates a field of the given type for the purpose of +static analysis. This was deemed to be less error-prone than explicitly telling +the type-system the kind of variance that you want, while also providing other +useful such as the information needed by drop check. + +Iter logically contains a bunch of `&'a T`s, so this is exactly what we tell +the PhantomData to simulate: + +``` +use std::marker; + +struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, + _marker: marker::PhantomData<&'a T>, +} +``` + +and that's it. The lifetime will be bounded, and your iterator will be variant +over `'a` and `T`. Everything Just Works. + +Another important example is Vec, which is (approximately) defined as follows: + +``` +struct Vec { + data: *const T, // *const for variance! + len: usize, + cap: usize, +} +``` + +Unlike the previous example it *appears* that everything is exactly as we +want. Every generic argument to Vec shows up in the at least one field. +Good to go! + +Nope. + +The drop checker will generously determine that Vec does not own any values +of type T. This will in turn make it conclude that it does *not* need to worry +about Vec dropping any T's in its destructor for determining drop check +soundness. This will in turn allow people to create unsoundness using +Vec's destructor. + +In order to tell dropck that we *do* own values of type T, and therefore may +drop some T's when *we* drop, we must add an extra PhantomData saying exactly +that: + +``` +use std::marker; + +struct Vec { + data: *const T, // *const for covariance! + len: usize, + cap: usize, + _marker: marker::PhantomData, +} +``` + +Raw pointers that own an allocation is such a pervasive pattern that the +standard library made a utility for itself called `Unique` which: + +* wraps a `*const T` for variance +* includes a `PhantomData`, +* auto-derives Send/Sync as if T was contained +* marks the pointer as NonZero for the null-pointer optimization + From fc2d29450ed5bd0f72179a2a3da8ac4ecf86c47a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 17 Jul 2015 22:20:44 -0700 Subject: [PATCH 078/104] no really I deleted you --- src/doc/tarpl/lifetime-misc.md | 233 --------------------------------- 1 file changed, 233 deletions(-) delete mode 100644 src/doc/tarpl/lifetime-misc.md diff --git a/src/doc/tarpl/lifetime-misc.md b/src/doc/tarpl/lifetime-misc.md deleted file mode 100644 index bd44bb6964af5..0000000000000 --- a/src/doc/tarpl/lifetime-misc.md +++ /dev/null @@ -1,233 +0,0 @@ -% misc - -This is just a dumping ground while I work out what to do with this stuff - - -# PhantomData - -When working with unsafe code, we can often end up in a situation where -types or lifetimes are logically associated with a struct, but not actually -part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` -for `&'a [T]` is (approximately) defined as follows: - -```rust,ignore -struct Iter<'a, T: 'a> { - ptr: *const T, - end: *const T, -} -``` - -However because `'a` is unused within the struct's body, it's *unbound*. -Because of the troubles this has historically caused, unbound lifetimes and -types are *illegal* in struct definitions. Therefore we must somehow refer -to these types in the body. Correctly doing this is necessary to have -correct variance and drop checking. - -We do this using *PhantomData*, which is a special marker type. PhantomData -consumes no space, but simulates a field of the given type for the purpose of -static analysis. This was deemed to be less error-prone than explicitly telling -the type-system the kind of variance that you want, while also providing other -useful information. - -Iter logically contains `&'a T`, so this is exactly what we tell -the PhantomData to simulate: - -``` -use std::marker; - -struct Iter<'a, T: 'a> { - ptr: *const T, - end: *const T, - _marker: marker::PhantomData<&'a T>, -} -``` - - - - -# Dropck - -When a type is going out of scope, Rust will try to Drop it. Drop executes -arbitrary code, and in fact allows us to "smuggle" arbitrary code execution -into many places. As such additional soundness checks (dropck) are necessary to -ensure that a type T can be safely instantiated and dropped. It turns out that we -*really* don't need to care about dropck in practice, as it often "just works". - -However the one exception is with PhantomData. Given a struct like Vec: - -``` -struct Vec { - data: *const T, // *const for variance! - len: usize, - cap: usize, -} -``` - -dropck will generously determine that Vec does not own any values of -type T. This will unfortunately allow people to construct unsound Drop -implementations that access data that has already been dropped. In order to -tell dropck that we *do* own values of type T, and may call destructors of that -type, we must add extra PhantomData: - -``` -use std::marker; - -struct Vec { - data: *const T, // *const for covariance! - len: usize, - cap: usize, - _marker: marker::PhantomData, -} -``` - -Raw pointers that own an allocation is such a pervasive pattern that the -standard library made a utility for itself called `Unique` which: - -* wraps a `*const T`, -* includes a `PhantomData`, -* auto-derives Send/Sync as if T was contained -* marks the pointer as NonZero for the null-pointer optimization - - - - -# Splitting Lifetimes - -The mutual exclusion property of mutable references can be very limiting when -working with a composite structure. The borrow checker understands some basic stuff, but -will fall over pretty easily. It *does* understand structs sufficiently to -know that it's possible to borrow disjoint fields of a struct simultaneously. -So this works today: - -```rust -struct Foo { - a: i32, - b: i32, - c: i32, -} - -let mut x = Foo {a: 0, b: 0, c: 0}; -let a = &mut x.a; -let b = &mut x.b; -let c = &x.c; -*b += 1; -let c2 = &x.c; -*a += 10; -println!("{} {} {} {}", a, b, c, c2); -``` - -However borrowck doesn't understand arrays or slices in any way, so this doesn't -work: - -```rust,ignore -let x = [1, 2, 3]; -let a = &mut x[0]; -let b = &mut x[1]; -println!("{} {}", a, b); -``` - -```text -:3:18: 3:22 error: cannot borrow immutable indexed content `x[..]` as mutable -:3 let a = &mut x[0]; - ^~~~ -:4:18: 4:22 error: cannot borrow immutable indexed content `x[..]` as mutable -:4 let b = &mut x[1]; - ^~~~ -error: aborting due to 2 previous errors -``` - -While it was plausible that borrowck could understand this simple case, it's -pretty clearly hopeless for borrowck to understand disjointness in general -container types like a tree, especially if distinct keys actually *do* map -to the same value. - -In order to "teach" borrowck that what we're doing is ok, we need to drop down -to unsafe code. For instance, mutable slices expose a `split_at_mut` function that -consumes the slice and returns *two* mutable slices. One for everything to the -left of the index, and one for everything to the right. Intuitively we know this -is safe because the slices don't alias. However the implementation requires some -unsafety: - -```rust,ignore -fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { - unsafe { - let self2: &mut [T] = mem::transmute_copy(&self); - - (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), - ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) - } -} -``` - -This is pretty plainly dangerous. We use transmute to duplicate the slice with an -*unbounded* lifetime, so that it can be treated as disjoint from the other until -we unify them when we return. - -However more subtle is how iterators that yield mutable references work. -The iterator trait is defined as follows: - -```rust -trait Iterator { - type Item; - - fn next(&mut self) -> Option; -} -``` - -Given this definition, Self::Item has *no* connection to `self`. This means -that we can call `next` several times in a row, and hold onto all the results -*concurrently*. This is perfectly fine for by-value iterators, which have exactly -these semantics. It's also actually fine for shared references, as they admit -arbitrarily many references to the same thing (although the -iterator needs to be a separate object from the thing being shared). But mutable -references make this a mess. At first glance, they might seem completely -incompatible with this API, as it would produce multiple mutable references to -the same object! - -However it actually *does* work, exactly because iterators are one-shot objects. -Everything an IterMut yields will be yielded *at most* once, so we don't *actually* -ever yield multiple mutable references to the same piece of data. - -In general all mutable iterators require *some* unsafe code *somewhere*, though. -Whether it's raw pointers, or safely composing on top of *another* IterMut. - -For instance, VecDeque's IterMut: - -```rust,ignore -struct IterMut<'a, T:'a> { - // The whole backing array. Some of these indices are initialized! - ring: &'a mut [T], - tail: usize, - head: usize, -} - -impl<'a, T> Iterator for IterMut<'a, T> { - type Item = &'a mut T; - - fn next(&mut self) -> Option<&'a mut T> { - if self.tail == self.head { - return None; - } - let tail = self.tail; - self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); - - unsafe { - // might as well do unchecked indexing since wrap_index has us - // in-bounds, and many of the "middle" indices are uninitialized - // anyway. - let elem = self.ring.get_unchecked_mut(tail); - - // round-trip through a raw pointer to unbound the lifetime from - // ourselves - Some(&mut *(elem as *mut _)) - } - } -} -``` - -A very subtle but interesting detail in this design is that it *relies on -privacy to be sound*. Borrowck works on some very simple rules. One of those rules -is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut -Bar is *also* live. Since IterMut is always live when `next` can be called, if -`ring` were public then we could mutate `ring` while outstanding mutable borrows -to it exist! From b79d279418db10728d5067fc872c0a9f273ba123 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sat, 18 Jul 2015 09:10:01 -0700 Subject: [PATCH 079/104] fix typo --- src/doc/tarpl/exotic-sizes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md index 5eeb4850d876e..100c526c4c615 100644 --- a/src/doc/tarpl/exotic-sizes.md +++ b/src/doc/tarpl/exotic-sizes.md @@ -63,7 +63,7 @@ context. Rust largely understands that any operation that produces or stores a ZST can be reduced to a no-op. For instance, a `HashSet` can be effeciently implemented as a thin wrapper around `HashMap` because all the operations `HashMap` -normally does to store and retrieve keys will be completely stripped in +normally does to store and retrieve values will be completely stripped in monomorphization. Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. From c97673c7b0fffe131822f2a5be520cf408c68319 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sat, 18 Jul 2015 11:44:41 -0700 Subject: [PATCH 080/104] fix up lifetimes --- src/doc/tarpl/lifetimes.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/tarpl/lifetimes.md index 7282e4d843cfd..350a4ead13094 100644 --- a/src/doc/tarpl/lifetimes.md +++ b/src/doc/tarpl/lifetimes.md @@ -66,11 +66,7 @@ let y = &x; z = y; ``` -The borrow checker always tries to minimize the extent of a lifetime, so it will -likely desugar to something like the following: - ```rust,ignore -// NOTE: `'a: {` and `foo = &'b x` is not valid syntax! 'a: { let x: i32 = 0; 'b: { @@ -191,8 +187,6 @@ println!("{}", x); 'c: { // Temporary scope because we don't need the // &mut to last any longer. - - // NOTE: Vec::push is not valid syntax Vec::push(&'c mut data, 4); } println!("{}", x); From 13b2605ed985a37481dc497357dc6dcdf37ba6ff Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 19 Jul 2015 20:48:51 -0700 Subject: [PATCH 081/104] fixup and cool example for checked-uninit --- src/doc/tarpl/checked-uninit.md | 23 +++++++++++++++++++++++ src/doc/tarpl/other-reprs.md | 2 +- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/doc/tarpl/checked-uninit.md b/src/doc/tarpl/checked-uninit.md index 65bffd7d09fea..8b03cd497b74c 100644 --- a/src/doc/tarpl/checked-uninit.md +++ b/src/doc/tarpl/checked-uninit.md @@ -68,6 +68,29 @@ fn main() { } ``` +Of course, while the analysis doesn't consider actual values, it does +have a relatively sophisticated understanding of dependencies and control +flow. For instance, this works: + +```rust +let x: i32; + +loop { + // Rust doesn't understand that this branch will be taken unconditionally, + // because it relies on actual values. + if true { + // But it does understand that it will only be taken once because + // we *do* unconditionally break out of it. Therefore `x` doesn't + // need to be marked as mutable. + x = 0; + break; + } +} +// It also knows that it's impossible to get here without reaching the break. +// And therefore that `x` must be initialized here! +println!("{}", x); +``` + 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: diff --git a/src/doc/tarpl/other-reprs.md b/src/doc/tarpl/other-reprs.md index d4c6134c5432b..26e0192a536d6 100644 --- a/src/doc/tarpl/other-reprs.md +++ b/src/doc/tarpl/other-reprs.md @@ -47,7 +47,7 @@ discriminant. On non-C-like enums, this will inhibit certain optimizations like the null- pointer optimization. -These reprs have no affect on a struct. +These reprs have no effect on a struct. From 94a89e561a62d54d25dd64329ef8af396d8ec032 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 19 Jul 2015 21:43:17 -0700 Subject: [PATCH 082/104] some conversions cleanup --- src/doc/tarpl/casts.md | 27 +++++++++++++++++---------- src/doc/tarpl/coercions.md | 6 +++--- src/doc/tarpl/conversions.md | 11 +++++++---- src/doc/tarpl/transmutes.md | 18 ++++++++++++------ 4 files changed, 39 insertions(+), 23 deletions(-) diff --git a/src/doc/tarpl/casts.md b/src/doc/tarpl/casts.md index cbcf81d837121..37f84ead7974b 100644 --- a/src/doc/tarpl/casts.md +++ b/src/doc/tarpl/casts.md @@ -1,9 +1,21 @@ % Casts -Casts are a superset of coercions: every coercion can be explicitly invoked via -a cast, but some conversions *require* a cast. These "true casts" are generally -regarded as dangerous or problematic actions. True casts revolve around raw -pointers and the primitive numeric types. True casts aren't checked. +Casts are a superset of coercions: every coercion can be explicitly +invoked via a cast. However some conversions *require* a cast. +While coercions are pervasive and largely harmless, these "true casts" +are rare and potentially dangerous. As such, casts must be explicitly invoked +using the `as` keyword: `expr as Type`. + +True casts generally revolve around raw pointers and the primitive numeric +types. Even though they're dangerous, these casts are *infallible* at runtime. +If a cast triggers some subtle corner case no indication will be given that +this occurred. The cast will simply succeed. + +That said, casts aren't `unsafe` because they generally can't violate memory +safety *on their own*. For instance, converting an integer to a raw pointer can +very easily lead to terrible things. However the act of creating the pointer +itself is safe, because actually using a raw pointer is already marked as +`unsafe`. Here's an exhaustive list of all the true casts. For brevity, we will use `*` to denote either a `*const` or `*mut`, and `integer` to denote any integral @@ -22,13 +34,8 @@ primitive: * `fn as *T` where `T: Sized` * `fn as integer` -where `&.T` and `*T` are references of either mutability, -and where unsize_kind(`T`) is the kind of the unsize info -in `T` - the vtable for a trait definition (e.g. `fmt::Display` or -`Iterator`, not `Iterator`) or a length (or `()` if `T: Sized`). - Note that lengths are not adjusted when casting raw slices - -`T: *const [u16] as *const [u8]` creates a slice that only includes +`*const [u16] as *const [u8]` creates a slice that only includes half of the original memory. Casting is not transitive, that is, even if `e as U1 as U2` is a valid diff --git a/src/doc/tarpl/coercions.md b/src/doc/tarpl/coercions.md index df0fdfa57ca13..0eb03d271c457 100644 --- a/src/doc/tarpl/coercions.md +++ b/src/doc/tarpl/coercions.md @@ -9,8 +9,7 @@ Here's all the kinds of coercion: Coercion is allowed between the following types: -* Subtyping: `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) - of `U` +* Subtyping: `T` to `U` if `T` is a [subtype][] of `U` * Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` * Pointer Weakening: * `&mut T` to `&T` @@ -25,7 +24,6 @@ only implemented automatically, and enables the following transformations: * `[T, ..n]` => `[T]` * `T` => `Trait` where `T: Trait` -* `SubTrait` => `Trait` where `SubTrait: Trait` (TODO: is this now implied by the previous?) * `Foo<..., T, ...>` => `Foo<..., U, ...>` where: * `T: Unsize` * `Foo` is a struct @@ -70,3 +68,5 @@ fn main() { :10 foo(t); ^~~ ``` + +[subtype]: subtyping.html diff --git a/src/doc/tarpl/conversions.md b/src/doc/tarpl/conversions.md index 56c050072b976..2309c45c6a84f 100644 --- a/src/doc/tarpl/conversions.md +++ b/src/doc/tarpl/conversions.md @@ -1,9 +1,12 @@ % Type Conversions At the end of the day, everything is just a pile of bits somewhere, and type -systems are just there to help us use those bits right. Needing to reinterpret -those piles of bits as different types is a common problem and Rust consequently -gives you several ways to do that. +systems are just there to help us use those bits right. There are two common +problems with typing bits: needing to reinterpret those exact bits as a +different type, and needing to change the bits to have equivalent meaning for +a different type. Because Rust encourages encoding important properties in the +type system, these problems are incredibly pervasive. As such, Rust +consequently gives you several ways to solve them. First we'll look at the ways that *Safe Rust* gives you to reinterpret values. The most trivial way to do this is to just destructure a value into its @@ -26,6 +29,6 @@ fn reinterpret(foo: Foo) -> Bar { } ``` -But this is, at best, annoying to do. For common conversions, Rust provides +But this is, at best, annoying. For common conversions, Rust provides more ergonomic alternatives. diff --git a/src/doc/tarpl/transmutes.md b/src/doc/tarpl/transmutes.md index 577d35ddb56dc..f19dda0d8b81f 100644 --- a/src/doc/tarpl/transmutes.md +++ b/src/doc/tarpl/transmutes.md @@ -1,10 +1,10 @@ % Transmutes Get out of our way type system! We're going to reinterpret these bits or die -trying! Even though this book is all about doing things that are unsafe, I really -can't emphasize that you should deeply think about finding Another Way than the -operations covered in this section. This is really, truly, the most horribly -unsafe thing you can do in Rust. The railguards here are dental floss. +trying! Even though this book is all about doing things that are unsafe, I +really can't emphasize that you should deeply think about finding Another Way +than the operations covered in this section. This is really, truly, the most +horribly unsafe thing you can do in Rust. The railguards here are dental floss. `mem::transmute` takes a value of type `T` and reinterprets it to have type `U`. The only restriction is that the `T` and `U` are verified to have the @@ -17,8 +17,11 @@ same size. The ways to cause Undefined Behaviour with this are mind boggling. * Making a primitive with an invalid value is UB * Transmuting between non-repr(C) types is UB * Transmuting an & to &mut is UB + * Transmuting an & to &mut is *always* UB + * No you can't do it + * No you're not special * Transmuting to a reference without an explicitly provided lifetime - produces an [unbound lifetime](lifetimes.html#unbounded-lifetimes) + produces an [unbounded lifetime][] `mem::transmute_copy` somehow manages to be *even more* wildly unsafe than this. It copies `size_of` bytes out of an `&T` and interprets them as a `U`. @@ -26,4 +29,7 @@ The size check that `mem::transmute` has is gone (as it may be valid to copy out a prefix), though it is Undefined Behaviour for `U` to be larger than `T`. Also of course you can get most of the functionality of these functions using -pointer casts. \ No newline at end of file +pointer casts. + + +[unbounded lifetime]: unbounded-lifetimes.html From 42c2f107c120e9da046c9b26aa34238fcd6549b6 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 11:02:45 -0700 Subject: [PATCH 083/104] flesh out void types --- src/doc/tarpl/exotic-sizes.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md index 100c526c4c615..d4df9492da778 100644 --- a/src/doc/tarpl/exotic-sizes.md +++ b/src/doc/tarpl/exotic-sizes.md @@ -81,9 +81,33 @@ consider passing in `0` as Undefined Behaviour. Rust also enables types to be declared that *cannot even be instantiated*. These types can only be talked about at the type level, and never at the value level. +Empty types can be declared by specifying an enum with no variants: ```rust -enum Foo { } // No variants = EMPTY +enum Void {} // No variants = EMPTY ``` -TODO: WHY?! +Empty types are even more marginal than ZSTs. The primary motivating example for +Void types is type-level unreachability. For instance, suppose an API needs to +return a Result in general, but a specific case actually is infallible. It's +actually possible to communicate this at the type level by returning a +`Result`. Consumers of the API can confidently unwrap such a Result +knowing that it's *statically impossible* for this value to be an `Err`, as +this would require providing a value of type Void. + +In principle, Rust can do some interesting analysees and optimizations based +on this fact. For instance, `Result` could be represented as just `T`, +because the Err case doesn't actually exist. Also in principle the following +could compile: + +```rust,ignore +enum Void {} + +let res: Result = Ok(0); + +// Err doesn't exist anymore, so Ok is actually irrefutable. +let Ok(num) = res; +``` + +But neither of these tricks work today, so all Void types get you today is +the ability to be confident that certain situations are statically impossible. From 5f6e0abe27aa6632f95492ad8864d8084c1bacef Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 11:31:29 -0700 Subject: [PATCH 084/104] clean up vec chapter of tarpl --- src/doc/tarpl/SUMMARY.md | 1 + src/doc/tarpl/vec-alloc.md | 2 +- src/doc/tarpl/vec-dealloc.md | 12 +-- src/doc/tarpl/vec-deref.md | 20 ++-- src/doc/tarpl/vec-drain.md | 9 +- src/doc/tarpl/vec-insert-remove.md | 9 +- src/doc/tarpl/vec-into-iter.md | 159 +++-------------------------- src/doc/tarpl/vec-layout.md | 21 ++-- src/doc/tarpl/vec-raw.md | 136 ++++++++++++++++++++++++ 9 files changed, 192 insertions(+), 177 deletions(-) create mode 100644 src/doc/tarpl/vec-raw.md diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/tarpl/SUMMARY.md index b0d75bfc85c96..d8b348760765f 100644 --- a/src/doc/tarpl/SUMMARY.md +++ b/src/doc/tarpl/SUMMARY.md @@ -46,6 +46,7 @@ * [Deref](vec-deref.md) * [Insert and Remove](vec-insert-remove.md) * [IntoIter](vec-into-iter.md) + * [RawVec](vec-raw.md) * [Drain](vec-drain.md) * [Handling Zero-Sized Types](vec-zsts.md) * [Final Code](vec-final.md) diff --git a/src/doc/tarpl/vec-alloc.md b/src/doc/tarpl/vec-alloc.md index e9c9f681ed84a..14b9b462afc63 100644 --- a/src/doc/tarpl/vec-alloc.md +++ b/src/doc/tarpl/vec-alloc.md @@ -46,7 +46,7 @@ Okay, now we can write growing. Roughly, we want to have this logic: if cap == 0: allocate() cap = 1 -else +else: reallocate cap *= 2 ``` diff --git a/src/doc/tarpl/vec-dealloc.md b/src/doc/tarpl/vec-dealloc.md index 2ae2477bbacdb..b767caa491236 100644 --- a/src/doc/tarpl/vec-dealloc.md +++ b/src/doc/tarpl/vec-dealloc.md @@ -2,13 +2,13 @@ Next we should implement Drop so that we don't massively leak tons of resources. The easiest way is to just call `pop` until it yields None, and then deallocate -our buffer. Note that calling `pop` is uneeded if `T: !Drop`. In theory we can -ask Rust if T needs_drop and omit the calls to `pop`. However in practice LLVM -is *really* good at removing simple side-effect free code like this, so I wouldn't -bother unless you notice it's not being stripped (in this case it is). +our buffer. Note that calling `pop` is unneeded if `T: !Drop`. In theory we can +ask Rust if `T` `needs_drop` and omit the calls to `pop`. However in practice +LLVM is *really* good at removing simple side-effect free code like this, so I +wouldn't bother unless you notice it's not being stripped (in this case it is). -We must not call `heap::deallocate` when `self.cap == 0`, as in this case we haven't -actually allocated any memory. +We must not call `heap::deallocate` when `self.cap == 0`, as in this case we +haven't actually allocated any memory. ```rust,ignore diff --git a/src/doc/tarpl/vec-deref.md b/src/doc/tarpl/vec-deref.md index 826d763f5bbcb..6460eab479bd4 100644 --- a/src/doc/tarpl/vec-deref.md +++ b/src/doc/tarpl/vec-deref.md @@ -1,13 +1,15 @@ % Deref -Alright! We've got a decent minimal ArrayStack implemented. We can push, we can -pop, and we can clean up after ourselves. However there's a whole mess of functionality -we'd reasonably want. In particular, we have a proper array, but none of the slice -functionality. That's actually pretty easy to solve: we can implement `Deref`. -This will magically make our Vec coerce to and behave like a slice in all sorts of -conditions. +Alright! We've got a decent minimal stack implemented. We can push, we can +pop, and we can clean up after ourselves. However there's a whole mess of +functionality we'd reasonably want. In particular, we have a proper array, but +none of the slice functionality. That's actually pretty easy to solve: we can +implement `Deref`. This will magically make our Vec coerce to, and +behave like, a slice in all sorts of conditions. -All we need is `slice::from_raw_parts`. +All we need is `slice::from_raw_parts`. It will correctly handle empty slices +for us. Later once we set up zero-sized type support it will also Just Work +for those too. ```rust,ignore use std::ops::Deref; @@ -36,5 +38,5 @@ impl DerefMut for Vec { } ``` -Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, `iter_mut`, -and all other sorts of bells and whistles provided by slice. Sweet! +Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, +`iter_mut`, and all other sorts of bells and whistles provided by slice. Sweet! diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/tarpl/vec-drain.md index df7cf00b99b68..b6b2826660079 100644 --- a/src/doc/tarpl/vec-drain.md +++ b/src/doc/tarpl/vec-drain.md @@ -2,7 +2,7 @@ Let's move on to Drain. Drain is largely the same as IntoIter, except that instead of consuming the Vec, it borrows the Vec and leaves its allocation -free. For now we'll only implement the "basic" full-range version. +untouched. For now we'll only implement the "basic" full-range version. ```rust,ignore use std::marker::PhantomData; @@ -38,6 +38,9 @@ impl RawValIter { RawValIter { start: slice.as_ptr(), end: if slice.len() == 0 { + // if `len = 0`, then this is not actually allocated memory. + // Need to avoid offsetting because that will give wrong + // information to LLVM via GEP. slice.as_ptr() } else { slice.as_ptr().offset(slice.len() as isize) @@ -137,5 +140,7 @@ impl Vec { } ``` +For more details on the `mem::forget` problem, see the +[section on leaks][leaks]. - +[leaks]: leaking.html diff --git a/src/doc/tarpl/vec-insert-remove.md b/src/doc/tarpl/vec-insert-remove.md index f21ed227d84ca..6f88a77b32a75 100644 --- a/src/doc/tarpl/vec-insert-remove.md +++ b/src/doc/tarpl/vec-insert-remove.md @@ -1,12 +1,13 @@ % Insert and Remove -Something *not* provided but slice is `insert` and `remove`, so let's do those next. +Something *not* provided by slice is `insert` and `remove`, so let's do those +next. Insert needs to shift all the elements at the target index to the right by one. To do this we need to use `ptr::copy`, which is our version of C's `memmove`. -This copies some chunk of memory from one location to another, correctly handling -the case where the source and destination overlap (which will definitely happen -here). +This copies some chunk of memory from one location to another, correctly +handling the case where the source and destination overlap (which will +definitely happen here). If we insert at index `i`, we want to shift the `[i .. len]` to `[i+1 .. len+1]` using the *old* len. diff --git a/src/doc/tarpl/vec-into-iter.md b/src/doc/tarpl/vec-into-iter.md index d21cf940fcc10..566cad75b5124 100644 --- a/src/doc/tarpl/vec-into-iter.md +++ b/src/doc/tarpl/vec-into-iter.md @@ -11,19 +11,20 @@ allocation. IntoIter needs to be DoubleEnded as well, to enable reading from both ends. Reading from the back could just be implemented as calling `pop`, but reading from the front is harder. We could call `remove(0)` but that would be insanely -expensive. Instead we're going to just use ptr::read to copy values out of either -end of the Vec without mutating the buffer at all. +expensive. Instead we're going to just use ptr::read to copy values out of +either end of the Vec without mutating the buffer at all. To do this we're going to use a very common C idiom for array iteration. We'll -make two pointers; one that points to the start of the array, and one that points -to one-element past the end. When we want an element from one end, we'll read out -the value pointed to at that end and move the pointer over by one. When the two -pointers are equal, we know we're done. +make two pointers; one that points to the start of the array, and one that +points to one-element past the end. When we want an element from one end, we'll +read out the value pointed to at that end and move the pointer over by one. When +the two pointers are equal, we know we're done. Note that the order of read and offset are reversed for `next` and `next_back` For `next_back` the pointer is always *after* the element it wants to read next, while for `next` the pointer is always *at* the element it wants to read next. -To see why this is, consider the case where every element but one has been yielded. +To see why this is, consider the case where every element but one has been +yielded. The array looks like this: @@ -35,6 +36,10 @@ The array looks like this: If E pointed directly at the element it wanted to yield next, it would be indistinguishable from the case where there are no more elements to yield. +Although we don't actually care about it during iteration, we also need to hold +onto the Vec's allocation information in order to free it once IntoIter is +dropped. + So we're going to use the following struct: ```rust,ignore @@ -46,8 +51,8 @@ struct IntoIter { } ``` -One last subtle detail: if our Vec is empty, we want to produce an empty iterator. -This will actually technically fall out doing the naive thing of: +One last subtle detail: if our Vec is empty, we want to produce an empty +iterator. This will actually technically fall out doing the naive thing of: ```text start = ptr @@ -155,139 +160,3 @@ impl Drop for IntoIter { } } ``` - -We've actually reached an interesting situation here: we've duplicated the logic -for specifying a buffer and freeing its memory. Now that we've implemented it and -identified *actual* logic duplication, this is a good time to perform some logic -compression. - -We're going to abstract out the `(ptr, cap)` pair and give them the logic for -allocating, growing, and freeing: - -```rust,ignore - -struct RawVec { - ptr: Unique, - cap: usize, -} - -impl RawVec { - fn new() -> Self { - assert!(mem::size_of::() != 0, "TODO: implement ZST support"); - unsafe { - RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: 0 } - } - } - - // unchanged from Vec - fn grow(&mut self) { - unsafe { - let align = mem::align_of::(); - let elem_size = mem::size_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - let new_cap = 2 * self.cap; - let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } - } -} - - -impl Drop for RawVec { - fn drop(&mut self) { - if self.cap != 0 { - let align = mem::align_of::(); - let elem_size = mem::size_of::(); - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr as *mut _, num_bytes, align); - } - } - } -} -``` - -And change vec as follows: - -```rust,ignore -pub struct Vec { - buf: RawVec, - len: usize, -} - -impl Vec { - fn ptr(&self) -> *mut T { *self.buf.ptr } - - fn cap(&self) -> usize { self.buf.cap } - - pub fn new() -> Self { - Vec { buf: RawVec::new(), len: 0 } - } - - // push/pop/insert/remove largely unchanged: - // * `self.ptr -> self.ptr()` - // * `self.cap -> self.cap()` - // * `self.grow -> self.buf.grow()` -} - -impl Drop for Vec { - fn drop(&mut self) { - while let Some(_) = self.pop() {} - // deallocation is handled by RawVec - } -} -``` - -And finally we can really simplify IntoIter: - -```rust,ignore -struct IntoIter { - _buf: RawVec, // we don't actually care about this. Just need it to live. - start: *const T, - end: *const T, -} - -// next and next_back literally unchanged since they never referred to the buf - -impl Drop for IntoIter { - fn drop(&mut self) { - // only need to ensure all our elements are read; - // buffer will clean itself up afterwards. - for _ in &mut *self {} - } -} - -impl Vec { - pub fn into_iter(self) -> IntoIter { - unsafe { - // need to use ptr::read to unsafely move the buf out since it's - // not Copy. - let buf = ptr::read(&self.buf); - let len = self.len; - mem::forget(self); - - IntoIter { - start: *buf.ptr, - end: buf.ptr.offset(len as isize), - _buf: buf, - } - } - } -} -``` - -Much better. diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/tarpl/vec-layout.md index 128ad15f7950f..4e440846ec7df 100644 --- a/src/doc/tarpl/vec-layout.md +++ b/src/doc/tarpl/vec-layout.md @@ -13,15 +13,15 @@ pub struct Vec { # fn main() {} ``` -And indeed this would compile. Unfortunately, it would be incorrect. The compiler -will give us too strict variance, so e.g. an `&Vec<&'static str>` couldn't be used -where an `&Vec<&'a str>` was expected. More importantly, it will give incorrect -ownership information to dropck, as it will conservatively assume we don't own -any values of type `T`. See [the chapter on ownership and lifetimes] -(lifetimes.html) for details. +And indeed this would compile. Unfortunately, it would be incorrect. The +compiler will give us too strict variance, so e.g. an `&Vec<&'static str>` +couldn't be used where an `&Vec<&'a str>` was expected. More importantly, it +will give incorrect ownership information to dropck, as it will conservatively +assume we don't own any values of type `T`. See [the chapter on ownership and +lifetimes] (lifetimes.html) for details. -As we saw in the lifetimes chapter, we should use `Unique` in place of `*mut T` -when we have a raw pointer to an allocation we own: +As we saw in the lifetimes chapter, we should use `Unique` in place of +`*mut T` when we have a raw pointer to an allocation we own: ```rust @@ -40,9 +40,10 @@ pub struct Vec { As a recap, Unique is a wrapper around a raw pointer that declares that: -* We own at least one value of type `T` +* We may own a value of type `T` * We are Send/Sync iff `T` is Send/Sync -* Our pointer is never null (and therefore `Option` is null-pointer-optimized) +* Our pointer is never null (and therefore `Option` is + null-pointer-optimized) That last point is subtle. First, it makes `Unique::new` unsafe to call, because putting `null` inside of it is Undefined Behaviour. It also throws a diff --git a/src/doc/tarpl/vec-raw.md b/src/doc/tarpl/vec-raw.md new file mode 100644 index 0000000000000..40de0196f29a3 --- /dev/null +++ b/src/doc/tarpl/vec-raw.md @@ -0,0 +1,136 @@ +% RawVec + +We've actually reached an interesting situation here: we've duplicated the logic +for specifying a buffer and freeing its memory. Now that we've implemented it +and identified *actual* logic duplication, this is a good time to perform some +logic compression. + +We're going to abstract out the `(ptr, cap)` pair and give them the logic for +allocating, growing, and freeing: + +```rust,ignore +struct RawVec { + ptr: Unique, + cap: usize, +} + +impl RawVec { + fn new() -> Self { + assert!(mem::size_of::() != 0, "TODO: implement ZST support"); + unsafe { + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: 0 } + } + } + + // unchanged from Vec + fn grow(&mut self) { + unsafe { + let align = mem::align_of::(); + let elem_size = mem::size_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + + +impl Drop for RawVec { + fn drop(&mut self) { + if self.cap != 0 { + let align = mem::align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +And change vec as follows: + +```rust,ignore +pub struct Vec { + buf: RawVec, + len: usize, +} + +impl Vec { + fn ptr(&self) -> *mut T { *self.buf.ptr } + + fn cap(&self) -> usize { self.buf.cap } + + pub fn new() -> Self { + Vec { buf: RawVec::new(), len: 0 } + } + + // push/pop/insert/remove largely unchanged: + // * `self.ptr -> self.ptr()` + // * `self.cap -> self.cap()` + // * `self.grow -> self.buf.grow()` +} + +impl Drop for Vec { + fn drop(&mut self) { + while let Some(_) = self.pop() {} + // deallocation is handled by RawVec + } +} +``` + +And finally we can really simplify IntoIter: + +```rust,ignore +struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + start: *const T, + end: *const T, +} + +// next and next_back literally unchanged since they never referred to the buf + +impl Drop for IntoIter { + fn drop(&mut self) { + // only need to ensure all our elements are read; + // buffer will clean itself up afterwards. + for _ in &mut *self {} + } +} + +impl Vec { + pub fn into_iter(self) -> IntoIter { + unsafe { + // need to use ptr::read to unsafely move the buf out since it's + // not Copy, and Vec implements Drop (so we can't destructure it). + let buf = ptr::read(&self.buf); + let len = self.len; + mem::forget(self); + + IntoIter { + start: *buf.ptr, + end: buf.ptr.offset(len as isize), + _buf: buf, + } + } + } +} +``` + +Much better. From 99043dde9dd2d0507ad2e3cda65b9d3e9244f13f Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 11:36:26 -0700 Subject: [PATCH 085/104] mention void pointers --- src/doc/tarpl/exotic-sizes.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md index d4df9492da778..68ce061d8c8ba 100644 --- a/src/doc/tarpl/exotic-sizes.md +++ b/src/doc/tarpl/exotic-sizes.md @@ -95,10 +95,9 @@ actually possible to communicate this at the type level by returning a knowing that it's *statically impossible* for this value to be an `Err`, as this would require providing a value of type Void. -In principle, Rust can do some interesting analysees and optimizations based +In principle, Rust can do some interesting analyses and optimizations based on this fact. For instance, `Result` could be represented as just `T`, -because the Err case doesn't actually exist. Also in principle the following -could compile: +because the Err case doesn't actually exist. The following *could* also compile: ```rust,ignore enum Void {} @@ -111,3 +110,9 @@ let Ok(num) = res; But neither of these tricks work today, so all Void types get you today is the ability to be confident that certain situations are statically impossible. + +One final subtle detail about empty types is that raw pointers to them are +actually valid to construct, but dereferencing them is Undefined Behaviour +because that doesn't actually make sense. That is, you could model C's `void *` +type with `*const Void`, but this doesn't necessarily gain anything over using +e.g. `*const ()`, which *is* safe to randomly dereference. From 7a47ffcbc73fa3bd02429c92841dcb0792a1f9b8 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 11:37:15 -0700 Subject: [PATCH 086/104] UB is src bzns --- src/doc/tarpl/vec-into-iter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/tarpl/vec-into-iter.md b/src/doc/tarpl/vec-into-iter.md index 566cad75b5124..0ffc23c452333 100644 --- a/src/doc/tarpl/vec-into-iter.md +++ b/src/doc/tarpl/vec-into-iter.md @@ -63,7 +63,7 @@ However because `offset` is marked as a GEP inbounds instruction, this will tell LLVM that ptr is allocated and won't alias other allocated memory. This is fine for zero-sized types, as they can't alias anything. However if we're using `heap::EMPTY` as a sentinel for a non-allocation for a *non-zero-sized* type, -this can cause undefined behaviour. Alas, we must therefore special case either +this can cause Undefined Behaviour. Alas, we must therefore special case either cap or len being 0 to not do the offset. So this is what we end up with for initialization: From 0a36ea7db130dfaa6012d76ccf80b9b77e15796b Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 15:32:52 -0700 Subject: [PATCH 087/104] get into the weeds over GEP and allocations --- src/doc/tarpl/vec-alloc.md | 156 ++++++++++++++++++++++++++++++------ src/doc/tarpl/vec-layout.md | 95 ++++++++++++++-------- src/doc/tarpl/vec.md | 16 +++- 3 files changed, 209 insertions(+), 58 deletions(-) diff --git a/src/doc/tarpl/vec-alloc.md b/src/doc/tarpl/vec-alloc.md index 14b9b462afc63..6f98220ebc975 100644 --- a/src/doc/tarpl/vec-alloc.md +++ b/src/doc/tarpl/vec-alloc.md @@ -1,5 +1,22 @@ % Allocating Memory +Using Unique throws a wrench in an important feature of Vec (and indeed all of +the std collections): an empty Vec doesn't actually allocate at all. So if we +can't allocate, but also can't put a null pointer in `ptr`, what do we do in +`Vec::new`? Well, we just put some other garbage in there! + +This is perfectly fine because we already have `cap == 0` as our sentinel for no +allocation. We don't even need to handle it specially in almost any code because +we usually need to check if `cap > len` or `len > 0` anyway. The traditional +Rust value to put here is `0x01`. The standard library actually exposes this +as `std::rt::heap::EMPTY`. There are quite a few places where we'll +want to use `heap::EMPTY` because there's no real allocation to talk about but +`null` would make the compiler do bad things. + +All of the `heap` API is totally unstable under the `heap_api` feature, though. +We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of +the `heap` API anyway, so let's just get that dependency over with. + So: ```rust,ignore @@ -24,15 +41,29 @@ I slipped in that assert there because zero-sized types will require some special handling throughout our code, and I want to defer the issue for now. Without this assert, some of our early drafts will do some Very Bad Things. -Next we need to figure out what to actually do when we *do* want space. For that, -we'll need to use the rest of the heap APIs. These basically allow us to -talk directly to Rust's instance of jemalloc. - -We'll also need a way to handle out-of-memory conditions. The standard library -calls the `abort` intrinsic, but calling intrinsics from normal Rust code is a -pretty bad idea. Unfortunately, the `abort` exposed by the standard library -allocates. Not something we want to do during `oom`! Instead, we'll call -`std::process::exit`. +Next we need to figure out what to actually do when we *do* want space. For +that, we'll need to use the rest of the heap APIs. These basically allow us to +talk directly to Rust's allocator (jemalloc by default). + +We'll also need a way to handle out-of-memory (OOM) conditions. The standard +library calls the `abort` intrinsic, which just calls an illegal instruction to +crash the whole program. The reason we abort and don't panic is because +unwinding can cause allocations to happen, and that seems like a bad thing to do +when your allocator just came back with "hey I don't have any more memory". + +Of course, this is a bit silly since most platforms don't actually run out of +memory in a conventional way. Your operating system will probably kill the +application by another means if you legitimately start using up all the memory. +The most likely way we'll trigger OOM is by just asking for ludicrous quantities +of memory at once (e.g. half the theoretical address space). As such it's +*probably* fine to panic and nothing bad will happen. Still, we're trying to be +like the standard library as much as possible, so we'll just kill the whole +program. + +We said we don't want to use intrinsics, so doing *exactly* what `std` does is +out. `std::rt::util::abort` actually exists, but it takes a message to print, +which will probably allocate. Also it's still unstable. Instead, we'll call +`std::process::exit` with some random number. ```rust fn oom() { @@ -51,29 +82,104 @@ else: cap *= 2 ``` -But Rust's only supported allocator API is so low level that we'll need to -do a fair bit of extra work, though. We also need to guard against some special -conditions that can occur with really large allocations. In particular, we index -into arrays using unsigned integers, but `ptr::offset` takes signed integers. This -means Bad Things will happen if we ever manage to grow to contain more than -`isize::MAX` elements. Thankfully, this isn't something we need to worry about -in most cases. +But Rust's only supported allocator API is so low level that we'll need to do a +fair bit of extra work. We also need to guard against some special +conditions that can occur with really large allocations or empty allocations. + +In particular, `ptr::offset` will cause us *a lot* of trouble, because it has +the semantics of LLVM's GEP inbounds instruction. If you're fortunate enough to +not have dealt with this instruction, here's the basic story with GEP: alias +analysis, alias analysis, alias analysis. It's super important to an optimizing +compiler to be able to reason about data dependencies and aliasing. -On 64-bit targets we're artifically limited to only 48-bits, so we'll run out -of memory far before we reach that point. However on 32-bit targets, particularly -those with extensions to use more of the address space, it's theoretically possible -to successfully allocate more than `isize::MAX` bytes of memory. Still, we only -really need to worry about that if we're allocating elements that are a byte large. -Anything else will use up too much space. +As a simple example, consider the following fragment of code: + +```rust +# let x = &mut 0; +# let y = &mut 0; +*x *= 7; +*y *= 3; +``` -However since this is a tutorial, we're not going to be particularly optimal here, -and just unconditionally check, rather than use clever platform-specific `cfg`s. +If the compiler can prove that `x` and `y` point to different locations in +memory, the two operations can in theory be executed in parallel (by e.g. +loading them into different registers and working on them independently). +However in *general* the compiler can't do this because if x and y point to +the same location in memory, the operations need to be done to the same value, +and they can't just be merged afterwards. + +When you use GEP inbounds, you are specifically telling LLVM that the offsets +you're about to do are within the bounds of a single allocated entity. The +ultimate payoff being that LLVM can assume that if two pointers are known to +point to two disjoint objects, all the offsets of those pointers are *also* +known to not alias (because you won't just end up in some random place in +memory). LLVM is heavily optimized to work with GEP offsets, and inbounds +offsets are the best of all, so it's important that we use them as much as +possible. + +So that's what GEP's about, how can it cause us trouble? + +The first problem is that we index into arrays with unsigned integers, but +GEP (and as a consequence `ptr::offset`) takes a *signed integer*. This means +that half of the seemingly valid indices into an array will overflow GEP and +actually go in the wrong direction! As such we must limit all allocations to +`isize::MAX` elements. This actually means we only need to worry about +byte-sized objects, because e.g. `> isize::MAX` `u16`s will truly exhaust all of +the system's memory. However in order to avoid subtle corner cases where someone +reinterprets some array of `< isize::MAX` objects as bytes, std limits all +allocations to `isize::MAX` bytes. + +On all 64-bit targets that Rust currently supports we're artificially limited +to significantly less than all 64 bits of the address space (modern x64 +platforms only expose 48-bit addressing), so we can rely on just running out of +memory first. However on 32-bit targets, particularly those with extensions to +use more of the address space (PAE x86 or x32), it's theoretically possible to +successfully allocate more than `isize::MAX` bytes of memory. + +However since this is a tutorial, we're not going to be particularly optimal +here, and just unconditionally check, rather than use clever platform-specific +`cfg`s. + +The other corner-case we need to worry about is *empty* allocations. There will +be two kinds of empty allocations we need to worry about: `cap = 0` for all T, +and `cap > 0` for zero-sized types. + +These cases are tricky because they come +down to what LLVM means by "allocated". LLVM's notion of an +allocation is significantly more abstract than how we usually use it. Because +LLVM needs to work with different languages' semantics and custom allocators, +it can't really intimately understand allocation. Instead, the main idea behind +allocation is "doesn't overlap with other stuff". That is, heap allocations, +stack allocations, and globals don't randomly overlap. Yep, it's about alias +analysis. As such, Rust can technically play a bit fast an loose with the notion of +an allocation as long as it's *consistent*. + +Getting back to the empty allocation case, there are a couple of places where +we want to offset by 0 as a consequence of generic code. The question is then: +is it consistent to do so? For zero-sized types, we have concluded that it is +indeed consistent to do a GEP inbounds offset by an arbitrary number of +elements. This is a runtime no-op because every element takes up no space, +and it's fine to pretend that there's infinite zero-sized types allocated +at `0x01`. No allocator will ever allocate that address, because they won't +allocate `0x00` and they generally allocate to some minimal alignment higher +than a byte. + +However what about for positive-sized types? That one's a bit trickier. In +principle, you can argue that offsetting by 0 gives LLVM no information: either +there's an element before the address, or after it, but it can't know which. +However we've chosen to conservatively assume that it may do bad things. As +such we *will* guard against this case explicitly. + +*Phew* + +Ok with all the nonsense out of the way, let's actually allocate some memory: ```rust,ignore fn grow(&mut self) { // this is all pretty delicate, so let's say it's all unsafe unsafe { - let align = mem::min_align_of::(); + // current API requires us to specify size and alignment manually. + let align = mem::align_of::(); let elem_size = mem::size_of::(); let (new_cap, ptr) = if self.cap == 0 { diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/tarpl/vec-layout.md index 4e440846ec7df..bce9a2f22f4df 100644 --- a/src/doc/tarpl/vec-layout.md +++ b/src/doc/tarpl/vec-layout.md @@ -13,15 +13,64 @@ pub struct Vec { # fn main() {} ``` -And indeed this would compile. Unfortunately, it would be incorrect. The -compiler will give us too strict variance, so e.g. an `&Vec<&'static str>` +And indeed this would compile. Unfortunately, it would be incorrect. First, the +compiler will give us too strict variance. So a `&Vec<&'static str>` couldn't be used where an `&Vec<&'a str>` was expected. More importantly, it -will give incorrect ownership information to dropck, as it will conservatively -assume we don't own any values of type `T`. See [the chapter on ownership and -lifetimes] (lifetimes.html) for details. +will give incorrect ownership information to the drop checker, as it will +conservatively assume we don't own any values of type `T`. See [the chapter +on ownership and lifetimes][ownership] for all the details on variance and +drop check. -As we saw in the lifetimes chapter, we should use `Unique` in place of -`*mut T` when we have a raw pointer to an allocation we own: +As we saw in the ownership chapter, we should use `Unique` in place of +`*mut T` when we have a raw pointer to an allocation we own. Unique is unstable, +so we'd like to not use it if possible, though. + +As a recap, Unique is a wrapper around a raw pointer that declares that: + +* We are variant over `T` +* We may own a value of type `T` (for drop check) +* We are Send/Sync if `T` is Send/Sync +* We deref to `*mut T` (so it largely acts like a `*mut` in our code) +* Our pointer is never null (so `Option>` is null-pointer-optimized) + +We can implement all of the above requirements except for the last +one in stable Rust: + +```rust +use std::marker::PhantomData; +use std::ops::Deref; +use std::mem; + +struct Unique { + ptr: *const T, // *const for variance + _marker: PhantomData, // For the drop checker +} + +// Deriving Send and Sync is safe because we are the Unique owners +// of this data. It's like Unique is "just" T. +unsafe impl Send for Unique {} +unsafe impl Sync for Unique {} + +impl Unique { + pub fn new(ptr: *mut T) -> Self { + Unique { ptr: ptr, _marker: PhantomData } + } +} + +impl Deref for Unique { + type Target = *mut T; + fn deref(&self) -> &*mut T { + // There's no way to cast the *const to a *mut + // while also taking a reference. So we just + // transmute it since it's all "just pointers". + unsafe { mem::transmute(&self.ptr) } + } +} +``` + +Unfortunately the mechanism for stating that your value is non-zero is +unstable and unlikely to be stabilized soon. As such we're just going to +take the hit and use std's Unique: ```rust @@ -38,29 +87,11 @@ pub struct Vec { # fn main() {} ``` -As a recap, Unique is a wrapper around a raw pointer that declares that: - -* We may own a value of type `T` -* We are Send/Sync iff `T` is Send/Sync -* Our pointer is never null (and therefore `Option` is - null-pointer-optimized) - -That last point is subtle. First, it makes `Unique::new` unsafe to call, because -putting `null` inside of it is Undefined Behaviour. It also throws a -wrench in an important feature of Vec (and indeed all of the std collections): -an empty Vec doesn't actually allocate at all. So if we can't allocate, -but also can't put a null pointer in `ptr`, what do we do in -`Vec::new`? Well, we just put some other garbage in there! - -This is perfectly fine because we already have `cap == 0` as our sentinel for no -allocation. We don't even need to handle it specially in almost any code because -we usually need to check if `cap > len` or `len > 0` anyway. The traditional -Rust value to put here is `0x01`. The standard library actually exposes this -as `std::rt::heap::EMPTY`. There are quite a few places where we'll want to use -`heap::EMPTY` because there's no real allocation to talk about but `null` would -make the compiler angry. - -All of the `heap` API is totally unstable under the `heap_api` feature, though. -We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of -the `heap` API anyway, so let's just get that dependency over with. +If you don't care about the null-pointer optimization, then you can use the +stable code. However we will be designing the rest of the code around enabling +the optimization. In particular, `Unique::new` is unsafe to call, because +putting `null` inside of it is Undefined Behaviour. Our stable Unique doesn't +need `new` to be unsafe because it doesn't make any interesting guarantees about +its contents. +[ownership]: ownership.html diff --git a/src/doc/tarpl/vec.md b/src/doc/tarpl/vec.md index a613f259b70f2..39d9686ccac7f 100644 --- a/src/doc/tarpl/vec.md +++ b/src/doc/tarpl/vec.md @@ -2,5 +2,19 @@ To bring everything together, we're going to write `std::Vec` from scratch. Because all the best tools for writing unsafe code are unstable, this -project will only work on nightly (as of Rust 1.2.0). +project will only work on nightly (as of Rust 1.2.0). With the exception of the +allocator API, much of the unstable code we'll use is expected to be stabilized +in a similar form as it is today. +However we will generally try to avoid unstable code where possible. In +particular we won't use any intrinsics that could make a code a little +bit nicer or efficient because intrinsics are permanently unstable. Although +many intrinsics *do* become stabilized elsewhere (`std::ptr` and `str::mem` +consist of many intrinsics). + +Ultimately this means out implementation may not take advantage of all +possible optimizations, though it will be by no means *naive*. We will +definitely get into the weeds over nitty-gritty details, even +when the problem doesn't *really* merit it. + +You wanted advanced. We're gonna go advanced. From 06ded9c04e23ceaa41a4a5d01dd54432aaafd0db Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 15:35:33 -0700 Subject: [PATCH 088/104] explain phantom --- src/doc/tarpl/vec-drain.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/tarpl/vec-drain.md index b6b2826660079..23671978369a9 100644 --- a/src/doc/tarpl/vec-drain.md +++ b/src/doc/tarpl/vec-drain.md @@ -8,6 +8,9 @@ untouched. For now we'll only implement the "basic" full-range version. use std::marker::PhantomData; struct Drain<'a, T: 'a> { + // Need to bound the lifetime here, so we do it with `&'a mut Vec` + // because that's semantically what we contain. We're "just" calling + // `pop()` and `remove(0)`. vec: PhantomData<&'a mut Vec> start: *const T, end: *const T, From 14bc45477085222dcf2b87bef75ca3e7d0b5274a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 15:36:50 -0700 Subject: [PATCH 089/104] remove redundant explanation --- src/doc/tarpl/vec-into-iter.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/src/doc/tarpl/vec-into-iter.md b/src/doc/tarpl/vec-into-iter.md index 0ffc23c452333..a9c1917feb9c6 100644 --- a/src/doc/tarpl/vec-into-iter.md +++ b/src/doc/tarpl/vec-into-iter.md @@ -51,22 +51,7 @@ struct IntoIter { } ``` -One last subtle detail: if our Vec is empty, we want to produce an empty -iterator. This will actually technically fall out doing the naive thing of: - -```text -start = ptr -end = ptr.offset(len) -``` - -However because `offset` is marked as a GEP inbounds instruction, this will tell -LLVM that ptr is allocated and won't alias other allocated memory. This is fine -for zero-sized types, as they can't alias anything. However if we're using -`heap::EMPTY` as a sentinel for a non-allocation for a *non-zero-sized* type, -this can cause Undefined Behaviour. Alas, we must therefore special case either -cap or len being 0 to not do the offset. - -So this is what we end up with for initialization: +And this is what we end up with for initialization: ```rust,ignore impl Vec { From 5f02de3c226bce60c58ce2bc436e69c55b90a616 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 15:50:47 -0700 Subject: [PATCH 090/104] clarify casts are checked at compile time --- src/doc/tarpl/casts.md | 4 +++- src/doc/tarpl/repr-rust.md | 6 +++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/src/doc/tarpl/casts.md b/src/doc/tarpl/casts.md index 37f84ead7974b..a5527b2507551 100644 --- a/src/doc/tarpl/casts.md +++ b/src/doc/tarpl/casts.md @@ -9,7 +9,9 @@ using the `as` keyword: `expr as Type`. True casts generally revolve around raw pointers and the primitive numeric types. Even though they're dangerous, these casts are *infallible* at runtime. If a cast triggers some subtle corner case no indication will be given that -this occurred. The cast will simply succeed. +this occurred. The cast will simply succeed. That said, casts must be valid +at the type level, or else they will be prevented statically. For instance, +`7u8 as bool` will not compile. That said, casts aren't `unsafe` because they generally can't violate memory safety *on their own*. For instance, converting an integer to a raw pointer can diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/tarpl/repr-rust.md index b3a5a1278c78c..f7ed15f1e8701 100644 --- a/src/doc/tarpl/repr-rust.md +++ b/src/doc/tarpl/repr-rust.md @@ -12,7 +12,11 @@ An enum is said to be *C-like* if none of its variants have associated data. For all these, individual fields are aligned to their preferred alignment. For primitives this is usually equal to their size. For instance, a u32 will be aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 -bits. Composite structures will have a preferred alignment equal to the maximum +bits. Note that some primitives may be emulated on different platforms, and as +such may have strange alignment. For instance, a u64 on x86 may actually be +emulated as a pair of u32s, and thus only have 32-bit alignment. + +Composite structures will have a preferred alignment equal to the maximum of their fields' preferred alignment, and a size equal to a multiple of their preferred alignment. This ensures that arrays of T can be correctly iterated by offsetting by their size. So for instance, From 3f8e029bedba23b8b2d174fac2718f970a396676 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 20 Jul 2015 16:18:52 -0700 Subject: [PATCH 091/104] remove subtyping from coercions, it's something else --- src/doc/tarpl/coercions.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/doc/tarpl/coercions.md b/src/doc/tarpl/coercions.md index 0eb03d271c457..8bb82843ba0d3 100644 --- a/src/doc/tarpl/coercions.md +++ b/src/doc/tarpl/coercions.md @@ -1,16 +1,16 @@ % Coercions Types can implicitly be coerced to change in certain contexts. These changes are -generally just *weakening* of types, largely focused around pointers and lifetimes. -They mostly exist to make Rust "just work" in more cases, and are largely harmless. +generally just *weakening* of types, largely focused around pointers and +lifetimes. They mostly exist to make Rust "just work" in more cases, and are +largely harmless. Here's all the kinds of coercion: - Coercion is allowed between the following types: -* Subtyping: `T` to `U` if `T` is a [subtype][] of `U` -* Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` +* Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to + `T_3` * Pointer Weakening: * `&mut T` to `&T` * `*mut T` to `*const T` @@ -68,5 +68,3 @@ fn main() { :10 foo(t); ^~~ ``` - -[subtype]: subtyping.html From f54c5ad5660e81972b772be1c8852e1ef2969f28 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 24 Jul 2015 10:02:16 -0700 Subject: [PATCH 092/104] fix accident --- src/doc/tarpl/references.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/tarpl/references.md b/src/doc/tarpl/references.md index 993e2a52aebfa..a109bf5d012f9 100644 --- a/src/doc/tarpl/references.md +++ b/src/doc/tarpl/references.md @@ -2,7 +2,8 @@ There are two kinds of reference: -* Shared reference: `&` Mutable reference: `&mut` +* Shared reference: `&` +* Mutable reference: `&mut` Which obey the following rules: From 36a8b94464dd0cc7763fe3fb2fe9a3fbed273d06 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 26 Jul 2015 18:12:36 -0700 Subject: [PATCH 093/104] expand lifetime splitting to show IterMut is totally safe --- src/doc/tarpl/lifetime-splitting.md | 247 ++++++++++++++++++++++------ 1 file changed, 194 insertions(+), 53 deletions(-) diff --git a/src/doc/tarpl/lifetime-splitting.md b/src/doc/tarpl/lifetime-splitting.md index 7ab2d379ffd59..9b6b769520fac 100644 --- a/src/doc/tarpl/lifetime-splitting.md +++ b/src/doc/tarpl/lifetime-splitting.md @@ -1,10 +1,10 @@ % Splitting Lifetimes The mutual exclusion property of mutable references can be very limiting when -working with a composite structure. The borrow checker understands some basic stuff, but -will fall over pretty easily. It *does* understand structs sufficiently to -know that it's possible to borrow disjoint fields of a struct simultaneously. -So this works today: +working with a composite structure. The borrow checker understands some basic +stuff, but will fall over pretty easily. It *does* understand structs +sufficiently to know that it's possible to borrow disjoint fields of a struct +simultaneously. So this works today: ```rust struct Foo { @@ -49,11 +49,11 @@ container types like a tree, especially if distinct keys actually *do* map to the same value. In order to "teach" borrowck that what we're doing is ok, we need to drop down -to unsafe code. For instance, mutable slices expose a `split_at_mut` function that -consumes the slice and returns *two* mutable slices. One for everything to the -left of the index, and one for everything to the right. Intuitively we know this -is safe because the slices don't alias. However the implementation requires some -unsafety: +to unsafe code. For instance, mutable slices expose a `split_at_mut` function +that consumes the slice and returns *two* mutable slices. One for everything to +the left of the index, and one for everything to the right. Intuitively we know +this is safe because the slices don't alias. However the implementation requires +some unsafety: ```rust,ignore fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { @@ -66,9 +66,9 @@ fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { } ``` -This is pretty plainly dangerous. We use transmute to duplicate the slice with an -*unbounded* lifetime, so that it can be treated as disjoint from the other until -we unify them when we return. +This is pretty plainly dangerous. We use transmute to duplicate the slice with +an *unbounded* lifetime, so that it can be treated as disjoint from the other +until we unify them when we return. However more subtle is how iterators that yield mutable references work. The iterator trait is defined as follows: @@ -81,60 +81,201 @@ trait Iterator { } ``` -Given this definition, Self::Item has *no* connection to `self`. This means -that we can call `next` several times in a row, and hold onto all the results -*concurrently*. This is perfectly fine for by-value iterators, which have exactly -these semantics. It's also actually fine for shared references, as they admit -arbitrarily many references to the same thing (although the -iterator needs to be a separate object from the thing being shared). But mutable -references make this a mess. At first glance, they might seem completely -incompatible with this API, as it would produce multiple mutable references to -the same object! +Given this definition, Self::Item has *no* connection to `self`. This means that +we can call `next` several times in a row, and hold onto all the results +*concurrently*. This is perfectly fine for by-value iterators, which have +exactly these semantics. It's also actually fine for shared references, as they +admit arbitrarily many references to the same thing (although the iterator needs +to be a separate object from the thing being shared). + +But mutable references make this a mess. At first glance, they might seem +completely incompatible with this API, as it would produce multiple mutable +references to the same object! However it actually *does* work, exactly because iterators are one-shot objects. -Everything an IterMut yields will be yielded *at most* once, so we don't *actually* -ever yield multiple mutable references to the same piece of data. +Everything an IterMut yields will be yielded *at most* once, so we don't +*actually* ever yield multiple mutable references to the same piece of data. -In general all mutable iterators require *some* unsafe code *somewhere*, though. -Whether it's raw pointers, or safely composing on top of *another* IterMut. +Perhaps surprisingly, mutable iterators *don't* require unsafe code to be +implemented for many types! -For instance, VecDeque's IterMut: +For instance here's a singly linked list: -```rust,ignore -struct IterMut<'a, T:'a> { - // The whole backing array. Some of these indices are initialized! - ring: &'a mut [T], - tail: usize, - head: usize, +```rust +# fn main() {} +type Link = Option>>; + +struct Node { + elem: T, + next: Link, +} + +pub struct LinkedList { + head: Link, +} + +pub struct IterMut<'a, T: 'a>(Option<&'a mut Node>); + +impl LinkedList { + fn iter_mut(&mut self) -> IterMut { + IterMut(self.head.as_mut().map(|node| &mut **node)) + } } impl<'a, T> Iterator for IterMut<'a, T> { type Item = &'a mut T; - fn next(&mut self) -> Option<&'a mut T> { - if self.tail == self.head { - return None; + fn next(&mut self) -> Option { + self.0.take().map(|node| { + self.0 = node.next.as_mut().map(|node| &mut **node); + &mut node.elem + }) + } +} +``` + +Here's a mutable slice: + +```rust +use std::mem; + +pub struct IterMut<'a, T: 'a>(&'a mut[T]); + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option { + let slice = mem::replace(&mut self.0, &mut []); + if slice.is_empty() { return None; } + + let (l, r) = slice.split_at_mut(1); + self.0 = r; + l.get_mut(0) + } +} + +impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { + fn next_back(&mut self) -> Option { + let slice = mem::replace(&mut self.0, &mut []); + if slice.is_empty() { return None; } + + let new_len = slice.len() - 1; + let (l, r) = slice.split_at_mut(new_len); + self.0 = l; + r.get_mut(0) + } +} +``` + +And here's a binary tree: + +```rust +use std::collections::VecDeque; + +type Link = Option>>; + +struct Node { + elem: T, + left: Link, + right: Link, +} + +pub struct Tree { + root: Link, +} + +struct NodeIterMut<'a, T: 'a> { + elem: Option<&'a mut T>, + left: Option<&'a mut Node>, + right: Option<&'a mut Node>, +} + +enum State<'a, T: 'a> { + Elem(&'a mut T), + Node(&'a mut Node), +} + +pub struct IterMut<'a, T: 'a>(VecDeque>); + +impl Tree { + pub fn iter_mut(&mut self) -> IterMut { + let mut deque = VecDeque::new(); + self.root.as_mut().map(|root| deque.push_front(root.iter_mut())); + IterMut(deque) + } +} + +impl Node { + pub fn iter_mut(&mut self) -> NodeIterMut { + NodeIterMut { + elem: Some(&mut self.elem), + left: self.left.as_mut().map(|node| &mut **node), + right: self.right.as_mut().map(|node| &mut **node), + } + } +} + + +impl<'a, T> Iterator for NodeIterMut<'a, T> { + type Item = State<'a, T>; + + fn next(&mut self) -> Option { + match self.left.take() { + Some(node) => Some(State::Node(node)), + None => match self.elem.take() { + Some(elem) => Some(State::Elem(elem)), + None => match self.right.take() { + Some(node) => Some(State::Node(node)), + None => None, + } + } + } + } +} + +impl<'a, T> DoubleEndedIterator for NodeIterMut<'a, T> { + fn next_back(&mut self) -> Option { + match self.right.take() { + Some(node) => Some(State::Node(node)), + None => match self.elem.take() { + Some(elem) => Some(State::Elem(elem)), + None => match self.left.take() { + Some(node) => Some(State::Node(node)), + None => None, + } + } + } + } +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + fn next(&mut self) -> Option { + loop { + match self.0.front_mut().and_then(|node_it| node_it.next()) { + Some(State::Elem(elem)) => return Some(elem), + Some(State::Node(node)) => self.0.push_front(node.iter_mut()), + None => if let None = self.0.pop_front() { return None }, + } } - let tail = self.tail; - self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); - - unsafe { - // might as well do unchecked indexing since wrap_index has us - // in-bounds, and many of the "middle" indices are uninitialized - // anyway. - let elem = self.ring.get_unchecked_mut(tail); - - // round-trip through a raw pointer to unbound the lifetime from - // ourselves - Some(&mut *(elem as *mut _)) + } +} + +impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { + fn next(&mut self) -> Option { + loop { + match self.0.back_mut().and_then(|node_it| node_it.next_back()) { + Some(State::Elem(elem)) => return Some(elem), + Some(State::Node(node)) => self.0.push_back(node.iter_mut()), + None => if let None = self.0.pop_back() { return None }, + } } } } ``` -A very subtle but interesting detail in this design is that it *relies on -privacy to be sound*. Borrowck works on some very simple rules. One of those rules -is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut -Bar is *also* live. Since IterMut is always live when `next` can be called, if -`ring` were public then we could mutate `ring` while outstanding mutable borrows -to it exist! +All of these are completely safe and work on stable Rust! This ultimately +falls out of the simple struct case we saw before: Rust understands that you +can safely split a mutable reference into subfields. We can then encode +permanently consuming a reference via Options (or in the case of slices, +replacing with an empty slice). From 8c7111da07f20422a6bd5243b56d302f0f02c3a5 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Sun, 26 Jul 2015 18:19:50 -0700 Subject: [PATCH 094/104] fixup atomics --- src/doc/tarpl/atomics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/tarpl/atomics.md b/src/doc/tarpl/atomics.md index 8395b22c8d8e8..87378da7c5235 100644 --- a/src/doc/tarpl/atomics.md +++ b/src/doc/tarpl/atomics.md @@ -85,12 +85,12 @@ x = 1; y *= 2; Ideally this program has 2 possible final states: -* `y = 3`: (thread 2 did the check before thread 1 completed) y = 6`: (thread 2 -* `did the check after thread 1 completed) +* `y = 3`: (thread 2 did the check before thread 1 completed) +* `y = 6`: (thread 2 did the check after thread 1 completed) However there's a third potential state that the hardware enables: -* `y = 2`: (thread 2 saw `x = 2`, but not `y = 3`, and then overwrote `y = 3`) +* `y = 2`: (thread 2 saw `x = 1`, but not `y = 3`, and then overwrote `y = 3`) It's worth noting that different kinds of CPU provide different guarantees. It is common to separate hardware into two categories: strongly-ordered and weakly- From b53406f8241edb45eb962795da99cb2cf73d8c1a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 27 Jul 2015 14:40:54 -0700 Subject: [PATCH 095/104] fixups for aturon --- src/doc/tarpl/lifetimes.md | 4 +-- src/doc/tarpl/references.md | 62 ++++++++++++++++++++++++------------- src/doc/tarpl/subtyping.md | 2 +- 3 files changed, 43 insertions(+), 25 deletions(-) diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/tarpl/lifetimes.md index 350a4ead13094..f4475b738509b 100644 --- a/src/doc/tarpl/lifetimes.md +++ b/src/doc/tarpl/lifetimes.md @@ -19,7 +19,7 @@ our toes with lifetimes, we're going to pretend that we're actually allowed to label scopes with lifetimes, and desugar the examples from the start of this chapter. -Our examples made use of *aggressive* sugar -- high fructose corn syrup even -- +Originally, our examples made use of *aggressive* sugar -- high fructose corn syrup even -- around scopes and lifetimes, because writing everything out explicitly is *extremely noisy*. All Rust code relies on aggressive inference and elision of "obvious" things. @@ -166,7 +166,7 @@ our implementation *just a bit*.) -# Example 2: aliasing a mutable reference +# Example: aliasing a mutable reference How about the other example: diff --git a/src/doc/tarpl/references.md b/src/doc/tarpl/references.md index a109bf5d012f9..da70dd529078b 100644 --- a/src/doc/tarpl/references.md +++ b/src/doc/tarpl/references.md @@ -1,5 +1,12 @@ % References +This section gives a high-level view of the memory model that *all* Rust +programs must satisfy to be correct. Safe code is statically verified +to obey this model by the borrow checker. Unsafe code may go above +and beyond the borrow checker while still satisfying this model. The borrow +checker may also be extended to allow more programs to compile, as long as +this more fundamental model is satisfied. + There are two kinds of reference: * Shared reference: `&` @@ -7,53 +14,63 @@ There are two kinds of reference: Which obey the following rules: -* A reference cannot outlive its referent A mutable reference cannot be aliased +* A reference cannot outlive its referent +* A mutable reference cannot be aliased -To define aliasing, we must define the notion of *paths* and *liveness*. +That's it. That's the whole model. Of course, we should probably define +what *aliased* means. To define aliasing, we must define the notion of +*paths* and *liveness*. # Paths -If all Rust had were values, then every value would be uniquely owned by a -variable or composite structure. From this we naturally derive a *tree* of -ownership. The stack itself is the root of the tree, with every variable as its -direct children. Each variable's direct children would be their fields (if any), -and so on. +If all Rust had were values (no pointers), then every value would be uniquely +owned by a variable or composite structure. From this we naturally derive a +*tree* of ownership. The stack itself is the root of the tree, with every +variable as its direct children. Each variable's direct children would be their +fields (if any), and so on. From this view, every value in Rust has a unique *path* in the tree of -ownership. References to a value can subsequently be interpreted as a path in -this tree. Of particular interest are *ancestors* and *descendants*: if `x` owns -`y`, then `x` is an *ancestor* of `y`, and `y` is a *descendant* of `x`. Note +ownership. Of particular interest are *ancestors* and *descendants*: if `x` owns +`y`, then `x` is an ancestor of `y`, and `y` is a descendant of `x`. Note that this is an inclusive relationship: `x` is a descendant and ancestor of itself. +We can then define references as simply *names* for paths. When you create a +reference, you're declaring that an ownership path exists to this address +of memory. + Tragically, plenty of data doesn't reside on the stack, and we must also accommodate this. Globals and thread-locals are simple enough to model as residing at the bottom of the stack (though we must be careful with mutable globals). Data on the heap poses a different problem. If all Rust had on the heap was data uniquely owned by a pointer on the stack, -then we can just treat that pointer as a struct that owns the value on the heap. -Box, Vec, String, and HashMap, are examples of types which uniquely own data on -the heap. +then we could just treat such a pointer as a struct that owns the value on the +heap. Box, Vec, String, and HashMap, are examples of types which uniquely +own data on the heap. Unfortunately, data on the heap is not *always* uniquely owned. Rc for instance -introduces a notion of *shared* ownership. Shared ownership means there is no -unique path. A value with no unique path limits what we can do with it. In -general, only shared references can be created to these values. However +introduces a notion of *shared* ownership. Shared ownership of a value means +there is no unique path to it. A value with no unique path limits what we can do +with it. + +In general, only shared references can be created to non-unique paths. However mechanisms which ensure mutual exclusion may establish One True Owner -temporarily, establishing a unique path to that value (and therefore all its -children). +temporarily, establishing a unique path to that value (and therefore all +its children). If this is done, the value may be mutated. In particular, a +mutable reference can be taken. The most common way to establish such a path is through *interior mutability*, in contrast to the *inherited mutability* that everything in Rust normally uses. Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. -These types provide exclusive access through runtime restrictions. However it is -also possible to establish unique ownership without interior mutability. For -instance, if an Rc has refcount 1, then it is safe to mutate or move its -internals. +These types provide exclusive access through runtime restrictions. + +An interesting case of this effect is Rc itself: if an Rc has refcount 1, +then it is safe to mutate or even move its internals. Note however that the +refcount itself uses interior mutability. In order to correctly communicate to the type system that a variable or field of a struct can have interior mutability, it must be wrapped in an UnsafeCell. This @@ -62,6 +79,7 @@ that value. You still must yourself ensure that mutual exclusion is upheld. + # Liveness Note: Liveness is not the same thing as a *lifetime*, which will be explained diff --git a/src/doc/tarpl/subtyping.md b/src/doc/tarpl/subtyping.md index 1b33c9abaa1bb..8c5ac9cca6b3f 100644 --- a/src/doc/tarpl/subtyping.md +++ b/src/doc/tarpl/subtyping.md @@ -100,7 +100,7 @@ subsequently be dropped, and `forever_str` would point to freed memory when we print it! Therefore `&mut` should be invariant. This is the general theme of variance vs invariance: if variance would allow you -to *store* a short-lived value over a longer-lived slot, then you must be +to store a short-lived value into a longer-lived slot, then you must be invariant. However it *is* sound for `&'a mut T` to be variant over `'a`. The key difference From fd13bdf626a50b5b21afbbe87806dc346f8ea9d7 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 27 Jul 2015 15:03:38 -0700 Subject: [PATCH 096/104] vec fixes for huonw --- src/doc/tarpl/vec-alloc.md | 11 +++++------ src/doc/tarpl/vec-drain.md | 3 ++- src/doc/tarpl/vec-layout.md | 7 +++++-- src/doc/tarpl/vec-raw.md | 8 ++++---- src/doc/tarpl/vec.md | 2 +- 5 files changed, 17 insertions(+), 14 deletions(-) diff --git a/src/doc/tarpl/vec-alloc.md b/src/doc/tarpl/vec-alloc.md index 6f98220ebc975..93efbbbdf89a2 100644 --- a/src/doc/tarpl/vec-alloc.md +++ b/src/doc/tarpl/vec-alloc.md @@ -61,9 +61,7 @@ like the standard library as much as possible, so we'll just kill the whole program. We said we don't want to use intrinsics, so doing *exactly* what `std` does is -out. `std::rt::util::abort` actually exists, but it takes a message to print, -which will probably allocate. Also it's still unstable. Instead, we'll call -`std::process::exit` with some random number. +out. Instead, we'll call `std::process::exit` with some random number. ```rust fn oom() { @@ -78,7 +76,7 @@ if cap == 0: allocate() cap = 1 else: - reallocate + reallocate() cap *= 2 ``` @@ -109,7 +107,7 @@ the same location in memory, the operations need to be done to the same value, and they can't just be merged afterwards. When you use GEP inbounds, you are specifically telling LLVM that the offsets -you're about to do are within the bounds of a single allocated entity. The +you're about to do are within the bounds of a single "allocated" entity. The ultimate payoff being that LLVM can assume that if two pointers are known to point to two disjoint objects, all the offsets of those pointers are *also* known to not alias (because you won't just end up in some random place in @@ -162,7 +160,8 @@ elements. This is a runtime no-op because every element takes up no space, and it's fine to pretend that there's infinite zero-sized types allocated at `0x01`. No allocator will ever allocate that address, because they won't allocate `0x00` and they generally allocate to some minimal alignment higher -than a byte. +than a byte. Also generally the whole first page of memory is +protected from being allocated anyway (a whole 4k, on many platforms). However what about for positive-sized types? That one's a bit trickier. In principle, you can argue that offsetting by 0 gives LLVM no information: either diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/tarpl/vec-drain.md index 23671978369a9..3be295f1adc2d 100644 --- a/src/doc/tarpl/vec-drain.md +++ b/src/doc/tarpl/vec-drain.md @@ -83,6 +83,7 @@ impl Vec { pub fn into_iter(self) -> IntoIter { unsafe { let iter = RawValIter::new(&self); + let buf = ptr::read(&self.buf); mem::forget(self); @@ -112,7 +113,7 @@ pub struct Drain<'a, T: 'a> { impl<'a, T> Iterator for Drain<'a, T> { type Item = T; - fn next(&mut self) -> Option { self.iter.next_back() } + fn next(&mut self) -> Option { self.iter.next() } fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } } diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/tarpl/vec-layout.md index bce9a2f22f4df..325399d622b69 100644 --- a/src/doc/tarpl/vec-layout.md +++ b/src/doc/tarpl/vec-layout.md @@ -1,7 +1,10 @@ % Layout -First off, we need to come up with the struct layout. Naively we want this -design: +First off, we need to come up with the struct layout. A Vec has three parts: +a pointer to the allocation, the size of the allocation, and the number of +elements that have been initialized. + +Naively, this means we just want this design: ```rust pub struct Vec { diff --git a/src/doc/tarpl/vec-raw.md b/src/doc/tarpl/vec-raw.md index 40de0196f29a3..8f78462cf4027 100644 --- a/src/doc/tarpl/vec-raw.md +++ b/src/doc/tarpl/vec-raw.md @@ -1,9 +1,9 @@ % RawVec We've actually reached an interesting situation here: we've duplicated the logic -for specifying a buffer and freeing its memory. Now that we've implemented it -and identified *actual* logic duplication, this is a good time to perform some -logic compression. +for specifying a buffer and freeing its memory in Vec and IntoIter. Now that +we've implemented it and identified *actual* logic duplication, this is a good +time to perform some logic compression. We're going to abstract out the `(ptr, cap)` pair and give them the logic for allocating, growing, and freeing: @@ -64,7 +64,7 @@ impl Drop for RawVec { } ``` -And change vec as follows: +And change Vec as follows: ```rust,ignore pub struct Vec { diff --git a/src/doc/tarpl/vec.md b/src/doc/tarpl/vec.md index 39d9686ccac7f..63f83788c4bac 100644 --- a/src/doc/tarpl/vec.md +++ b/src/doc/tarpl/vec.md @@ -12,7 +12,7 @@ bit nicer or efficient because intrinsics are permanently unstable. Although many intrinsics *do* become stabilized elsewhere (`std::ptr` and `str::mem` consist of many intrinsics). -Ultimately this means out implementation may not take advantage of all +Ultimately this means our implementation may not take advantage of all possible optimizations, though it will be by no means *naive*. We will definitely get into the weeds over nitty-gritty details, even when the problem doesn't *really* merit it. From 05bb1dbc43a620fbbd65ae830bb53ba9768ac185 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 27 Jul 2015 16:01:22 -0700 Subject: [PATCH 097/104] OBRM for aturon --- src/doc/tarpl/SUMMARY.md | 2 +- src/doc/tarpl/destructors.md | 6 ++++-- src/doc/tarpl/leaking.md | 40 ++++++++++++++++++++++++++++-------- src/doc/tarpl/obrm.md | 14 +++++++++++++ src/doc/tarpl/raii.md | 14 ------------- 5 files changed, 50 insertions(+), 26 deletions(-) create mode 100644 src/doc/tarpl/obrm.md delete mode 100644 src/doc/tarpl/raii.md diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/tarpl/SUMMARY.md index d8b348760765f..a7014d7f0207a 100644 --- a/src/doc/tarpl/SUMMARY.md +++ b/src/doc/tarpl/SUMMARY.md @@ -27,7 +27,7 @@ * [Checked](checked-uninit.md) * [Drop Flags](drop-flags.md) * [Unchecked](unchecked-uninit.md) -* [Ownership-Oriented Resource Management](raii.md) +* [Ownership Based Resource Management](obrm.md) * [Constructors](constructors.md) * [Destructors](destructors.md) * [Leaking](leaking.md) diff --git a/src/doc/tarpl/destructors.md b/src/doc/tarpl/destructors.md index e146ae4a1dac3..34c8b2b8624d3 100644 --- a/src/doc/tarpl/destructors.md +++ b/src/doc/tarpl/destructors.md @@ -45,8 +45,8 @@ impl Drop for Box { ``` 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 immediately marked as uninitialized. +a [Unique][] that has no actual `Drop` implementation. Similarly nothing can +use-after-free the `ptr` because when drop exits, it becomes inacessible. However this wouldn't work: @@ -174,3 +174,5 @@ arbitrarily invalid state in there. On balance this is an ok choice. Certainly what you should reach for by default. However, in the future we expect there to be a first-class way to announce that a field shouldn't be automatically dropped. + +[Unique]: phantom-data.html diff --git a/src/doc/tarpl/leaking.md b/src/doc/tarpl/leaking.md index bb6f7bb4bda09..dcb03b1c8b6a0 100644 --- a/src/doc/tarpl/leaking.md +++ b/src/doc/tarpl/leaking.md @@ -8,14 +8,17 @@ is perfect and all of our problems are solved. Everything is terrible and we have new and exotic problems to try to solve. -Many people like to believe that Rust eliminates resource leaks, but this is -absolutely not the case, no matter how you look at it. In the strictest sense, -"leaking" is so abstract as to be unpreventable. It's quite trivial to -initialize a collection at the start of a program, fill it with tons of objects -with destructors, and then enter an infinite event loop that never refers to it. -The collection will sit around uselessly, holding on to its precious resources -until the program terminates (at which point all those resources would have been -reclaimed by the OS anyway). +Many people like to believe that Rust eliminates resource leaks. In practice, +this is basically true. You would be surprised to see a Safe Rust program +leak resources in an uncontrolled way. + +However from a theoretical perspective this is absolutely not the case, no +matter how you look at it. In the strictest sense, "leaking" is so abstract as +to be unpreventable. It's quite trivial to initialize a collection at the start +of a program, fill it with tons of objects with destructors, and then enter an +infinite event loop that never refers to it. The collection will sit around +uselessly, holding on to its precious resources until the program terminates (at +which point all those resources would have been reclaimed by the OS anyway). We may consider a more restricted form of leak: failing to drop a value that is unreachable. Rust also doesn't prevent this. In fact Rust has a *function for @@ -181,7 +184,26 @@ in memory. ## thread::scoped::JoinGuard The thread::scoped API intends to allow threads to be spawned that reference -data on the stack without any synchronization over that data. Usage looked like: +data on their parent's stack without any synchronization over that data by +ensuring the parent joins the thread before any of the shared data goes out +of scope. + +```rust +pub fn scoped<'a, F>(f: F) -> JoinGuard<'a> + where F: FnOnce() + Send + 'a +``` + +Here `f` is some closure for the other thread to execute. Saying that +`F: Send +'a` is saying that it closes over data that lives for `'a`, and it +either owns that data or the data was Sync (implying `&data` is Send). + +Because JoinGuard has a lifetime, it keeps all the data it closes over +borrowed in the parent thread. This means the JoinGuard can't outlive +the data that the other thread is working on. When the JoinGuard *does* get +dropped it blocks the parent thread, ensuring the child terminates before any +of the closed-over data goes out of scope in the parent. + +Usage looked like: ```rust,ignore let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; diff --git a/src/doc/tarpl/obrm.md b/src/doc/tarpl/obrm.md new file mode 100644 index 0000000000000..2c495240c1278 --- /dev/null +++ b/src/doc/tarpl/obrm.md @@ -0,0 +1,14 @@ +% The Perils Of Ownership Based Resource Management (OBRM) + +OBRM (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. diff --git a/src/doc/tarpl/raii.md b/src/doc/tarpl/raii.md deleted file mode 100644 index e9b92c69ccd2d..0000000000000 --- a/src/doc/tarpl/raii.md +++ /dev/null @@ -1,14 +0,0 @@ -% 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. From 57891067374a4cf3fff8c2be4bd0804cb4ef7fbe Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 28 Jul 2015 13:20:36 -0700 Subject: [PATCH 098/104] many many pnkfelix fixes --- src/doc/tarpl/exotic-sizes.md | 79 +++++++++++++++---------- src/doc/tarpl/meet-safe-and-unsafe.md | 36 ++++++------ src/doc/tarpl/other-reprs.md | 19 +++--- src/doc/tarpl/ownership.md | 15 ++--- src/doc/tarpl/repr-rust.md | 84 +++++++++++++++++---------- src/doc/tarpl/safe-unsafe-meaning.md | 56 ++++++++++++------ src/doc/tarpl/working-with-unsafe.md | 37 +++++++----- 7 files changed, 200 insertions(+), 126 deletions(-) diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/tarpl/exotic-sizes.md index 68ce061d8c8ba..d75d12e716e31 100644 --- a/src/doc/tarpl/exotic-sizes.md +++ b/src/doc/tarpl/exotic-sizes.md @@ -9,19 +9,24 @@ is not always the case, however. # Dynamically Sized Types (DSTs) -Rust also supports types without a statically known size. On the surface, this -is a bit nonsensical: Rust *must* know the size of something in order to work -with it! DSTs are generally produced as views, or through type-erasure of types -that *do* have a known size. Due to their lack of a statically known size, these -types can only exist *behind* some kind of pointer. They consequently produce a -*fat* pointer consisting of the pointer and the information that *completes* -them. - -For instance, the slice type, `[T]`, is some statically unknown number of -elements stored contiguously. `&[T]` consequently consists of a `(&T, usize)` -pair that specifies where the slice starts, and how many elements it contains. -Similarly, Trait Objects support interface-oriented type erasure through a -`(data_ptr, vtable_ptr)` pair. +Rust in fact supports Dynamically Sized Types (DSTs): types without a statically +known size or alignment. On the surface, this is a bit nonsensical: Rust *must* +know the size and alignment of something in order to correctly work with it! In +this regard, DSTs are not normal types. Due to their lack of a statically known +size, these types can only exist behind some kind of pointer. Any pointer to a +DST consequently becomes a *fat* pointer consisting of the pointer and the +information that "completes" them (more on this below). + +There are two major DSTs exposed by the language: trait objects, and slices. + +A trait object represents some type that implements the traits it specifies. +The exact original type is *erased* in favour of runtime reflection +with a vtable containing all the information necessary to use the type. +This is the information that completes a trait object: a pointer to its vtable. + +A slice is simply a view into some contiguous storage -- typically an array or +`Vec`. The information that completes a slice is just the number of elements +it points to. Structs can actually store a single DST directly as their last field, but this makes them a DST as well: @@ -34,8 +39,8 @@ struct Foo { } ``` -**NOTE: As of Rust 1.0 struct DSTs are broken if the last field has -a variable position based on its alignment.** +**NOTE: [As of Rust 1.0 struct DSTs are broken if the last field has +a variable position based on its alignment][dst-issue].** @@ -56,22 +61,32 @@ struct Baz { } ``` -On their own, ZSTs are, for obvious reasons, pretty useless. However as with -many curious layout choices in Rust, their potential is realized in a generic -context. - -Rust largely understands that any operation that produces or stores a ZST can be -reduced to a no-op. For instance, a `HashSet` can be effeciently implemented -as a thin wrapper around `HashMap` because all the operations `HashMap` -normally does to store and retrieve values will be completely stripped in -monomorphization. - -Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. +On their own, Zero Sized Types (ZSTs) are, for obvious reasons, pretty useless. +However as with many curious layout choices in Rust, their potential is realized +in a generic context: Rust largely understands that any operation that produces +or stores a ZST can be reduced to a no-op. First off, storing it doesn't even +make sense -- it doesn't occupy any space. Also there's only one value of that +type, so anything that loads it can just produce it from the aether -- which is +also a no-op since it doesn't occupy any space. + +One of the most extreme example's of this is Sets and Maps. Given a +`Map`, it is common to implement a `Set` as just a thin wrapper +around `Map`. In many languages, this would necessitate +allocating space for UselessJunk and doing work to store and load UselessJunk +only to discard it. Proving this unnecessary would be a difficult analysis for +the compiler. + +However in Rust, we can just say that `Set = Map`. Now Rust +statically knows that every load and store is useless, and no allocation has any +size. The result is that the monomorphized code is basically a custom +implementation of a HashSet with none of the overhead that HashMap would have to +support values. Safe code need not worry about ZSTs, but *unsafe* code must be careful about the consequence of types with no size. In particular, pointer offsets are no-ops, -and standard allocators (including jemalloc, the one used by Rust) generally -consider passing in `0` as Undefined Behaviour. +and standard allocators (including jemalloc, the one used by default in Rust) +generally consider passing in `0` for the size of an allocation as Undefined +Behaviour. @@ -93,11 +108,12 @@ return a Result in general, but a specific case actually is infallible. It's actually possible to communicate this at the type level by returning a `Result`. Consumers of the API can confidently unwrap such a Result knowing that it's *statically impossible* for this value to be an `Err`, as -this would require providing a value of type Void. +this would require providing a value of type `Void`. In principle, Rust can do some interesting analyses and optimizations based on this fact. For instance, `Result` could be represented as just `T`, -because the Err case doesn't actually exist. The following *could* also compile: +because the `Err` case doesn't actually exist. The following *could* also +compile: ```rust,ignore enum Void {} @@ -116,3 +132,6 @@ actually valid to construct, but dereferencing them is Undefined Behaviour because that doesn't actually make sense. That is, you could model C's `void *` type with `*const Void`, but this doesn't necessarily gain anything over using e.g. `*const ()`, which *is* safe to randomly dereference. + + +[dst-issue]: https://github.com/rust-lang/rust/issues/26403 diff --git a/src/doc/tarpl/meet-safe-and-unsafe.md b/src/doc/tarpl/meet-safe-and-unsafe.md index 5ff000f2bbce9..a5e3136c54acf 100644 --- a/src/doc/tarpl/meet-safe-and-unsafe.md +++ b/src/doc/tarpl/meet-safe-and-unsafe.md @@ -2,7 +2,7 @@ Programmers in safe "high-level" languages face a fundamental dilemma. On one hand, it would be *really* great to just say what you want and not worry about -how it's done. On the other hand, that can lead to some *really* poor +how it's done. On the other hand, that can lead to unacceptably poor performance. It may be necessary to drop down to less clear or idiomatic practices to get the performance characteristics you want. Or maybe you just throw up your hands in disgust and decide to shell out to an implementation in @@ -12,21 +12,22 @@ Worse, when you want to talk directly to the operating system, you *have* to talk to an unsafe language: *C*. C is ever-present and unavoidable. It's the lingua-franca of the programming world. Even other safe languages generally expose C interfaces for the world at large! -Regardless of *why* you're doing it, as soon as your program starts talking to +Regardless of why you're doing it, as soon as your program starts talking to C it stops being safe. With that said, Rust is *totally* a safe programming language. Well, Rust *has* a safe programming language. Let's step back a bit. -Rust can be thought of as being composed of two -programming languages: *Safe* and *Unsafe*. Safe is For Reals Totally Safe. -Unsafe, unsurprisingly, is *not* For Reals Totally Safe. In fact, Unsafe lets -you do some really crazy unsafe things. +Rust can be thought of as being composed of two programming languages: *Safe +Rust* and *Unsafe Rust*. Safe Rust is For Reals Totally Safe. Unsafe Rust, +unsurprisingly, is *not* For Reals Totally Safe. In fact, Unsafe Rust lets you +do some really crazy unsafe things. -Safe is *the* Rust programming language. If all you do is write Safe Rust, -you will never have to worry about type-safety or memory-safety. You will never -endure a null or dangling pointer, or any of that Undefined Behaviour nonsense. +Safe Rust is the *true* Rust programming language. If all you do is write Safe +Rust, you will never have to worry about type-safety or memory-safety. You will +never endure a null or dangling pointer, or any of that Undefined Behaviour +nonsense. *That's totally awesome*. @@ -69,17 +70,16 @@ language cares about is preventing the following things: * A non-utf8 `str` * Unwinding into another language * Causing a [data race][race] -* Double-dropping a value -That's it. That's all the Undefined Behaviour baked into Rust. Of course, unsafe -functions and traits are free to declare arbitrary other constraints that a -program must maintain to avoid Undefined Behaviour. However these are generally -just things that will transitively lead to one of the above problems. Some -additional constraints may also derive from compiler intrinsics that make special -assumptions about how code can be optimized. +That's it. That's all the causes of Undefined Behaviour baked into Rust. Of +course, unsafe functions and traits are free to declare arbitrary other +constraints that a program must maintain to avoid Undefined Behaviour. However, +generally violations of these constraints will just transitively lead to one of +the above problems. Some additional constraints may also derive from compiler +intrinsics that make special assumptions about how code can be optimized. -Rust is otherwise quite permissive with respect to other dubious operations. Rust -considers it "safe" to: +Rust is otherwise quite permissive with respect to other dubious operations. +Rust considers it "safe" to: * Deadlock * Have a [race condition][race] diff --git a/src/doc/tarpl/other-reprs.md b/src/doc/tarpl/other-reprs.md index 26e0192a536d6..93ef2c13cdf8c 100644 --- a/src/doc/tarpl/other-reprs.md +++ b/src/doc/tarpl/other-reprs.md @@ -12,21 +12,21 @@ The order, size, and alignment of fields is exactly what you would expect from C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, as C is the lingua-franca of the programming world. This is also necessary to soundly do more elaborate tricks with data layout such as -reintepretting values as a different type. +reinterpreting values as a different type. However, the interaction with Rust's more exotic data layout features must be kept in mind. Due to its dual purpose as "for FFI" and "for layout control", `repr(C)` can be applied to types that will be nonsensical or problematic if passed through the FFI boundary. -* ZSTs are still zero-sized, even though this is not a standard behaviour in +* ZSTs are still zero-sized, even though this is not a standard behaviour in C, and is explicitly contrary to the behaviour of an empty type in C++, which still consumes a byte of space. * DSTs, tuples, and tagged unions are not a concept in C and as such are never FFI safe. -* **The [drop flag][] will still be added** +* **If the type would have any [drop flags][], they will still be added** * This is equivalent to one of `repr(u*)` (see the next section) for enums. The chosen size is the default enum size for the target platform's C ABI. Note that @@ -39,10 +39,10 @@ compiled with certain flags. # repr(u8), repr(u16), repr(u32), repr(u64) These specify the size to make a C-like enum. If the discriminant overflows the -integer it has to fit in, it will be an error. You can manually ask Rust to -allow this by setting the overflowing element to explicitly be 0. However Rust -will not allow you to create an enum where two variants have the same -discriminant. +integer it has to fit in, it will produce a compile-time error. You can manually +ask Rust to allow this by setting the overflowing element to explicitly be 0. +However Rust will not allow you to create an enum where two variants have the +same discriminant. On non-C-like enums, this will inhibit certain optimizations like the null- pointer optimization. @@ -65,9 +65,12 @@ compiler might be able to paper over alignment issues with shifts and masks. However if you take a reference to a packed field, it's unlikely that the compiler will be able to emit code to avoid an unaligned load. +**[As of Rust 1.0 this can cause undefined behaviour.][ub loads]** + `repr(packed)` is not to be used lightly. Unless you have extreme requirements, this should not be used. This repr is a modifier on `repr(C)` and `repr(rust)`. -[drop flag]: drop-flags.html +[drop flags]: drop-flags.html +[ub loads]: https://github.com/rust-lang/rust/issues/27060 diff --git a/src/doc/tarpl/ownership.md b/src/doc/tarpl/ownership.md index 200337a2256e3..f79cd92479f0b 100644 --- a/src/doc/tarpl/ownership.md +++ b/src/doc/tarpl/ownership.md @@ -5,16 +5,17 @@ memory-safe and efficient, while avoiding garbage collection. Before getting into the ownership system in detail, we will consider the motivation of this design. -We will assume that you accept that garbage collection is not always an optimal -solution, and that it is desirable to manually manage memory to some extent. -If you do not accept this, might I interest you in a different language? +We will assume that you accept that garbage collection (GC) is not always an +optimal solution, and that it is desirable to manually manage memory in some +contexts. If you do not accept this, might I interest you in a different +language? Regardless of your feelings on GC, it is pretty clearly a *massive* boon to making code safe. You never have to worry about things going away *too soon* (although whether you still *wanted* to be pointing at that thing is a different -issue...). This is a pervasive problem that C and C++ need to deal with. -Consider this simple mistake that all of us who have used a non-GC'd language -have made at one point: +issue...). This is a pervasive problem that C and C++ programs need to deal +with. Consider this simple mistake that all of us who have used a non-GC'd +language have made at one point: ```rust,ignore fn as_str(data: &u32) -> &str { @@ -40,7 +41,7 @@ be forced to accept your program on the assumption that it is correct. This will never happen to Rust. It's up to the programmer to prove to the compiler that everything is sound. -Of course, rust's story around ownership is much more complicated than just +Of course, Rust's story around ownership is much more complicated than just verifying that references don't escape the scope of their referent. That's because ensuring pointers are always valid is much more complicated than this. For instance in this code, diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/tarpl/repr-rust.md index f7ed15f1e8701..639d64adc18b8 100644 --- a/src/doc/tarpl/repr-rust.md +++ b/src/doc/tarpl/repr-rust.md @@ -1,5 +1,19 @@ % repr(Rust) +First and foremost, all types have an alignment specified in bytes. The +alignment of a type specifies what addresses are valid to store the value at. A +value of alignment `n` must only be stored at an address that is a multiple of +`n`. So alignment 2 means you must be stored at an even address, and 1 means +that you can be stored anywhere. Alignment is at least 1, and always a power of +2. Most primitives are generally aligned to their size, although this is +platform-specific behaviour. In particular, on x86 `u64` and `f64` may be only +aligned to 32 bits. + +A type's size must always be a multiple of its alignment. This ensures that an +array of that type may always be indexed by offsetting by a multiple of its +size. Note that the size and alignment of a type may not be known +statically in the case of [dynamically sized types][dst]. + Rust gives you the following ways to lay out composite data: * structs (named product types) @@ -9,17 +23,10 @@ Rust gives you the following ways to lay out composite data: An enum is said to be *C-like* if none of its variants have associated data. -For all these, individual fields are aligned to their preferred alignment. For -primitives this is usually equal to their size. For instance, a u32 will be -aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 -bits. Note that some primitives may be emulated on different platforms, and as -such may have strange alignment. For instance, a u64 on x86 may actually be -emulated as a pair of u32s, and thus only have 32-bit alignment. - -Composite structures will have a preferred alignment equal to the maximum -of their fields' preferred alignment, and a size equal to a multiple of their -preferred alignment. This ensures that arrays of T can be correctly iterated -by offsetting by their size. So for instance, +Composite structures will have an alignment equal to the maximum +of their fields' alignment. Rust will consequently insert padding where +necessary to ensure that all fields are properly aligned and that the overall +type's size is a multiple of its alignment. For instance: ```rust struct A { @@ -29,12 +36,24 @@ struct A { } ``` -will have a size that is a multiple of 32-bits, and 32-bit alignment. +will be 32-bit aligned assuming these primitives are aligned to their size. +It will therefore have a size that is a multiple of 32-bits. It will potentially +*really* become: -There is *no indirection* for these types; all data is stored contiguously as you would -expect in C. However with the exception of arrays (which are densely packed and -in-order), the layout of data is not by default specified in Rust. Given the two -following struct definitions: +```rust +struct A { + a: u8, + _pad1: [u8; 3], // to align `b` + b: u32, + c: u16, + _pad2: [u8; 2], // to make overall size multiple of 4 +} +``` + +There is *no indirection* for these types; all data is stored contiguously as +you would expect in C. However with the exception of arrays (which are densely +packed and in-order), the layout of data is not by default specified in Rust. +Given the two following struct definitions: ```rust struct A { @@ -48,13 +67,15 @@ struct B { } ``` -Rust *does* guarantee that two instances of A have their data laid out in exactly -the same way. However Rust *does not* guarantee that an instance of A has the same -field ordering or padding as an instance of B (in practice there's no *particular* -reason why they wouldn't, other than that its not currently guaranteed). +Rust *does* guarantee that two instances of A have their data laid out in +exactly the same way. However Rust *does not* guarantee that an instance of A +has the same field ordering or padding as an instance of B (in practice there's +no *particular* reason why they wouldn't, other than that its not currently +guaranteed). -With A and B as written, this is basically nonsensical, but several other features -of Rust make it desirable for the language to play with data layout in complex ways. +With A and B as written, this is basically nonsensical, but several other +features of Rust make it desirable for the language to play with data layout in +complex ways. For instance, consider this struct: @@ -66,10 +87,10 @@ struct Foo { } ``` -Now consider the monomorphizations of `Foo` and `Foo`. If Rust lays out the -fields in the order specified, we expect it to *pad* the values in the struct to satisfy -their *alignment* requirements. So if Rust didn't reorder fields, we would expect Rust to -produce the following: +Now consider the monomorphizations of `Foo` and `Foo`. If +Rust lays out the fields in the order specified, we expect it to *pad* the +values in the struct to satisfy their *alignment* requirements. So if Rust +didn't reorder fields, we would expect Rust to produce the following: ```rust,ignore struct Foo { @@ -87,10 +108,11 @@ struct Foo { } ``` -The latter case quite simply wastes space. An optimal use of space therefore requires -different monomorphizations to have *different field orderings*. +The latter case quite simply wastes space. An optimal use of space therefore +requires different monomorphizations to have *different field orderings*. -**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0** +**Note: this is a hypothetical optimization that is not yet implemented in Rust +**1.0 Enums make this consideration even more complicated. Naively, an enum such as: @@ -121,8 +143,10 @@ by using null as a special value. The net result is that There are many types in Rust that are, or contain, "not null" pointers such as `Box`, `Vec`, `String`, `&T`, and `&mut T`. Similarly, one can imagine -nested enums pooling their tags into a single descriminant, as they are by +nested enums pooling their tags into a single discriminant, as they are by definition known to have a limited range of valid values. In principle enums can use fairly elaborate algorithms to cache bits throughout nested types with special constrained representations. As such it is *especially* desirable that we leave enum layout unspecified today. + +[dst]: exotic-sizes.html#dynamically-sized-types-(dsts) diff --git a/src/doc/tarpl/safe-unsafe-meaning.md b/src/doc/tarpl/safe-unsafe-meaning.md index 2a593ffc5a7a1..c7210f8e2cf98 100644 --- a/src/doc/tarpl/safe-unsafe-meaning.md +++ b/src/doc/tarpl/safe-unsafe-meaning.md @@ -1,29 +1,30 @@ % How Safe and Unsafe Interact -So what's the relationship between Safe and Unsafe? How do they interact? +So what's the relationship between Safe and Unsafe Rust? How do they interact? -Rust models the seperation between Safe and Unsafe with the `unsafe` keyword, which -can be thought as a sort of *foreign function interface* (FFI) between Safe and Unsafe. -This is the magic behind why we can say Safe is a safe language: all the scary unsafe -bits are relagated *exclusively* to FFI *just like every other safe language*. +Rust models the separation between Safe and Unsafe Rust with the `unsafe` +keyword, which can be thought as a sort of *foreign function interface* (FFI) +between Safe and Unsafe Rust. This is the magic behind why we can say Safe Rust +is a safe language: all the scary unsafe bits are relegated *exclusively* to FFI +*just like every other safe language*. However because one language is a subset of the other, the two can be cleanly -intermixed as long as the boundary between Safe and Unsafe is denoted with the -`unsafe` keyword. No need to write headers, initialize runtimes, or any of that -other FFI boiler-plate. +intermixed as long as the boundary between Safe and Unsafe Rust is denoted with +the `unsafe` keyword. No need to write headers, initialize runtimes, or any of +that other FFI boiler-plate. There are several places `unsafe` can appear in Rust today, which can largely be grouped into two categories: * There are unchecked contracts here. To declare you understand this, I require you to write `unsafe` elsewhere: - * On functions, `unsafe` is declaring the function to be unsafe to call. Users - of the function must check the documentation to determine what this means, - and then have to write `unsafe` somewhere to identify that they're aware of - the danger. + * On functions, `unsafe` is declaring the function to be unsafe to call. + Users of the function must check the documentation to determine what this + means, and then have to write `unsafe` somewhere to identify that they're + aware of the danger. * On trait declarations, `unsafe` is declaring that *implementing* the trait - is an unsafe operation, as it has contracts that other unsafe code is free to - trust blindly. (More on this below.) + is an unsafe operation, as it has contracts that other unsafe code is free + to trust blindly. (More on this below.) * I am declaring that I have, to the best of my knowledge, adhered to the unchecked contracts: @@ -64,9 +65,9 @@ This means that Unsafe, **the royal vanguard of Undefined Behaviour**, has to be *super paranoid* about generic safe code. Unsafe is free to trust *specific* safe code (or else you would degenerate into infinite spirals of paranoid despair). It is generally regarded as ok to trust the standard library to be correct, as -std is effectively an extension of the language (and you *really* just have to trust -the language). If `std` fails to uphold the guarantees it declares, then it's -basically a language bug. +`std` is effectively an extension of the language (and you *really* just have +to trust the language). If `std` fails to uphold the guarantees it declares, +then it's basically a language bug. That said, it would be best to minimize *needlessly* relying on properties of concrete safe code. Bugs happen! Of course, I must reinforce that this is only @@ -89,7 +90,7 @@ Ord for a type, but don't actually provide a proper total ordering, BTreeMap wil get *really confused* and start making a total mess of itself. Data that is inserted may be impossible to find! -But that's ok. BTreeMap is safe, so it guarantees that even if you give it a +But that's okay. BTreeMap is safe, so it guarantees that even if you give it a *completely* garbage Ord implementation, it will still do something *safe*. You won't start reading uninitialized memory or unallocated memory. In fact, BTreeMap manages to not actually lose any of your data. When the map is dropped, all the @@ -104,7 +105,24 @@ Safe's responsibility to uphold. But wouldn't it be grand if there was some way for Unsafe to trust *some* trait contracts *somewhere*? This is the problem that unsafe traits tackle: by marking *the trait itself* as unsafe *to implement*, Unsafe can trust the implementation -to be correct. +to uphold the trait's contract. Although the trait implementation may be +incorrect in arbitrary other ways. + +For instance, given a hypothetical UnsafeOrd trait, this is technically a valid +implementation: + +```rust +# use std::cmp::Ordering; +# struct MyType; +# pub unsafe trait UnsafeOrd { fn cmp(&self, other: &Self) -> Ordering; } +unsafe impl UnsafeOrd for MyType { + fn cmp(&self, other: &Self) -> Ordering { + Ordering::Equal + } +} +``` + +But it's probably not the implementation you want. Rust has traditionally avoided making traits unsafe because it makes Unsafe pervasive, which is not desirable. Send and Sync are unsafe is because diff --git a/src/doc/tarpl/working-with-unsafe.md b/src/doc/tarpl/working-with-unsafe.md index 0aeb2c0dc2580..b20dff72e1c6a 100644 --- a/src/doc/tarpl/working-with-unsafe.md +++ b/src/doc/tarpl/working-with-unsafe.md @@ -1,8 +1,8 @@ % Working with Unsafe -Rust generally only gives us the tools to talk about Unsafe in a scoped and -binary manner. Unfortunately, reality is significantly more complicated than that. -For instance, consider the following toy function: +Rust generally only gives us the tools to talk about Unsafe Rust in a scoped and +binary manner. Unfortunately, reality is significantly more complicated than +that. For instance, consider the following toy function: ```rust fn index(idx: usize, arr: &[u8]) -> Option { @@ -35,10 +35,15 @@ fn index(idx: usize, arr: &[u8]) -> Option { This program is now unsound, and yet *we only modified safe code*. This is the fundamental problem of safety: it's non-local. The soundness of our unsafe -operations necessarily depends on the state established by "safe" operations. -Although safety *is* modular (we *still* don't need to worry about about -unrelated safety issues like uninitialized memory), it quickly contaminates the -surrounding code. +operations necessarily depends on the state established by otherwise +"safe" operations. + +Safety is modular in the sense that opting into unsafety doesn't require you +to consider arbitrary other kinds of badness. For instance, doing an unchecked +index into a slice doesn't mean you suddenly need to worry about the slice being +null or containing uninitialized memory. Nothing fundamentally changes. However +safety *isn't* modular in the sense that programs are inherently stateful and +your unsafe operations may depend on arbitrary other state. Trickier than that is when we get into actual statefulness. Consider a simple implementation of `Vec`: @@ -84,10 +89,10 @@ fn make_room(&mut self) { } ``` -This code is safe, but it is also completely unsound. Changing the capacity -violates the invariants of Vec (that `cap` reflects the allocated space in the -Vec). This is not something the rest of Vec can guard against. It *has* to -trust the capacity field because there's no way to verify it. +This code is 100% Safe Rust but it is also completely unsound. Changing the +capacity violates the invariants of Vec (that `cap` reflects the allocated space +in the Vec). This is not something the rest of Vec can guard against. It *has* +to trust the capacity field because there's no way to verify it. `unsafe` does more than pollute a whole function: it pollutes a whole *module*. Generally, the only bullet-proof way to limit the scope of unsafe code is at the @@ -102,9 +107,13 @@ as Vec. It is therefore possible for us to write a completely safe abstraction that relies on complex invariants. This is *critical* to the relationship between Safe Rust and Unsafe Rust. We have already seen that Unsafe code must trust -*some* Safe code, but can't trust *arbitrary* Safe code. However if Unsafe -couldn't prevent client Safe code from messing with its state in arbitrary ways, -safety would be a lost cause. +*some* Safe code, but can't trust *generic* Safe code. It can't trust an +arbitrary implementor of a trait or any function that was passed to it to be +well-behaved in a way that safe code doesn't care about. + +However if unsafe code couldn't prevent client safe code from messing with its +state in arbitrary ways, safety would be a lost cause. Thankfully, it *can* +prevent arbitrary code from messing with critical state due to privacy. Safety lives! From 0d37e7897766129715a2be960cb87a717a48390d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 28 Jul 2015 15:13:54 -0700 Subject: [PATCH 099/104] lots more felix fixes --- src/doc/tarpl/casts.md | 18 +++++++++------ src/doc/tarpl/checked-uninit.md | 13 +++++++++-- src/doc/tarpl/coercions.md | 2 +- src/doc/tarpl/drop-flags.md | 34 ++++++++++++++++++++-------- src/doc/tarpl/dropck.md | 12 +++++----- src/doc/tarpl/exception-safety.md | 2 +- src/doc/tarpl/hrtb.md | 23 ++++++++++--------- src/doc/tarpl/lifetime-splitting.md | 13 ++++++----- src/doc/tarpl/lifetimes.md | 17 +++++++------- src/doc/tarpl/safe-unsafe-meaning.md | 14 ++++++------ src/doc/tarpl/subtyping.md | 14 +++++++----- src/doc/tarpl/unchecked-uninit.md | 16 ++++++------- 12 files changed, 104 insertions(+), 74 deletions(-) diff --git a/src/doc/tarpl/casts.md b/src/doc/tarpl/casts.md index a5527b2507551..cb12ffe8d2145 100644 --- a/src/doc/tarpl/casts.md +++ b/src/doc/tarpl/casts.md @@ -41,8 +41,7 @@ Note that lengths are not adjusted when casting raw slices - half of the original memory. Casting is not transitive, that is, even if `e as U1 as U2` is a valid -expression, `e as U2` is not necessarily so (in fact it will only be valid if -`U1` coerces to `U2`). +expression, `e as U2` is not necessarily so. For numeric casts, there are quite a few cases to consider: @@ -53,15 +52,20 @@ For numeric casts, there are quite a few cases to consider: * zero-extend if the source is unsigned * sign-extend if the source is signed * casting from a float to an integer will round the float towards zero - * **NOTE: currently this will cause Undefined Behaviour if the rounded - value cannot be represented by the target integer type**. This includes - Inf and NaN. This is a bug and will be fixed. + * **[NOTE: currently this will cause Undefined Behaviour if the rounded + value cannot be represented by the target integer type][float-int]**. + This includes Inf and NaN. This is a bug and will be fixed. * casting from an integer to float will produce the floating point representation of the integer, rounded if necessary (rounding strategy unspecified) * casting from an f32 to an f64 is perfect and lossless * casting from an f64 to an f32 will produce the closest possible value (rounding strategy unspecified) - * **NOTE: currently this will cause Undefined Behaviour if the value + * **[NOTE: currently this will cause Undefined Behaviour if the value is finite but larger or smaller than the largest or smallest finite - value representable by f32**. This is a bug and will be fixed. + value representable by f32][float-float]**. This is a bug and will + be fixed. + + +[float-int]: https://github.com/rust-lang/rust/issues/10184 +[float-float]: https://github.com/rust-lang/rust/issues/15536 diff --git a/src/doc/tarpl/checked-uninit.md b/src/doc/tarpl/checked-uninit.md index 8b03cd497b74c..706016a480c66 100644 --- a/src/doc/tarpl/checked-uninit.md +++ b/src/doc/tarpl/checked-uninit.md @@ -104,5 +104,14 @@ fn main() { ``` 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. +mutable, as a Safe Rust program could observe that the value of `y` changed: + +```rust +fn main() { + let mut y = Box::new(0); + let z = y; // y is now logically uninitialized because Box isn't Copy + y = Box::new(1); // reinitialize y +} +``` + +Otherwise it's like `y` is a brand new variable. diff --git a/src/doc/tarpl/coercions.md b/src/doc/tarpl/coercions.md index 8bb82843ba0d3..2e33a6729d1cc 100644 --- a/src/doc/tarpl/coercions.md +++ b/src/doc/tarpl/coercions.md @@ -27,7 +27,7 @@ only implemented automatically, and enables the following transformations: * `Foo<..., T, ...>` => `Foo<..., U, ...>` where: * `T: Unsize` * `Foo` is a struct - * Only the last field has type `T` + * Only the last field of `Foo` has type `T` * `T` is not part of the type of any other fields Coercions occur at a *coercion site*. Any location that is explicitly typed diff --git a/src/doc/tarpl/drop-flags.md b/src/doc/tarpl/drop-flags.md index e8c331cd05659..f95ccc00329e5 100644 --- a/src/doc/tarpl/drop-flags.md +++ b/src/doc/tarpl/drop-flags.md @@ -2,12 +2,25 @@ The examples in the previous section introduce an interesting problem for Rust. We have seen that's possible to conditionally initialize, deinitialize, and -*reinitialize* locations of memory totally safely. For Copy types, this isn't +reinitialize locations of memory totally safely. For Copy types, this isn't particularly notable since they're just a random pile of bits. However types with destructors are a different story: Rust needs to know whether to call a destructor whenever a variable is assigned to, or a variable goes out of scope. How can it do this with conditional initialization? +Note that this is not a problem that all assignments need worry about. In +particular, assigning through a dereference unconditionally drops, and assigning +in a `let` unconditionally *doesn't* drop: + +``` +let mut x = Box::new(0); // let makes a fresh variable, so never need to drop +let y = &mut x; +*y = Box::new(1); // Deref assumes the referent is initialized, so always drops +``` + +This is only a problem when overwriting a previously initialized variable or +one of its subfields. + 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 toggled. When a variable *might* need to be dropped, this @@ -15,7 +28,7 @@ flag is evaluated to determine if it *should* be dropped. Of course, it is *often* the case that a value's initialization state can be *statically* known at every point in the program. If this is the case, then the -compiler can theoretically generate more effecient code! For instance, straight- +compiler can theoretically generate more efficient code! For instance, straight- line code has such *static drop semantics*: ```rust @@ -23,8 +36,8 @@ let mut x = Box::new(0); // x was uninit; just overwrite. let mut y = x; // y was uninit; just overwrite and make x uninit. x = Box::new(0); // x was uninit; just overwrite. y = x; // y was init; Drop y, overwrite it, and make x uninit! - // y was init; Drop y! - // x was uninit; do nothing. + // y goes out of scope; y was init; Drop y! + // x goes out of scope; x was uninit; do nothing. ``` And even branched code where all branches have the same behaviour with respect @@ -40,7 +53,7 @@ if condition { drop(x) // x gets moved out; make x uninit. } x = Box::new(0); // x was uninit; just overwrite. - // x was init; Drop x! + // x goes out of scope; x was init; Drop x! ``` However code like this *requires* runtime information to correctly Drop: @@ -52,7 +65,8 @@ if condition { x = Box::new(0); // x was uninit; just overwrite. println!("{}", x); } - // x *might* be uninit; check the flag! + // x goes out of scope; x *might* be uninit; + // check the flag! ``` Of course, in this case it's trivial to retrieve static drop semantics: @@ -66,10 +80,10 @@ if condition { ``` As of Rust 1.0, the drop flags are actually not-so-secretly stashed in a hidden -field of any type that implements Drop. Rust sets the drop flag by -overwriting the *entire* value with a particular byte. This is pretty obviously -Not The Fastest and causes a bunch of trouble with optimizing code. It's legacy -from a time when you could do much more complex conditional initialization. +field of any type that implements Drop. Rust sets the drop flag by overwriting +the *entire* value with a particular bit pattern. This is pretty obviously Not +The Fastest and causes a bunch of trouble with optimizing code. It's legacy from +a time when you could do much more complex conditional initialization. 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 diff --git a/src/doc/tarpl/dropck.md b/src/doc/tarpl/dropck.md index e1a25f513c7fa..419c61281d9fc 100644 --- a/src/doc/tarpl/dropck.md +++ b/src/doc/tarpl/dropck.md @@ -49,7 +49,7 @@ accidentally make dangling pointers. Consider the following simple program: struct Inspector<'a>(&'a u8); fn main() { - let (days, inspector); + let (inspector, days); days = Box::new(1); inspector = Inspector(&days); } @@ -71,7 +71,7 @@ impl<'a> Drop for Inspector<'a> { } fn main() { - let (days, inspector); + let (inspector, days); days = Box::new(1); inspector = Inspector(&days); // Let's say `days` happens to get dropped first. @@ -85,14 +85,14 @@ fn main() { ^~~~ :9:11: 15:2 note: reference must be valid for the block at 9:10... :9 fn main() { -:10 let (days, inspector); +:10 let (inspector, days); :11 days = Box::new(1); :12 inspector = Inspector(&days); :13 // Let's say `days` happens to get dropped first. :14 // Then when Inspector is dropped, it will try to read free'd memory! ... :10:27: 15:2 note: ...but borrowed value is only valid for the block suffix following statement 0 at 10:26 -:10 let (days, inspector); +:10 let (inspector, days); :11 days = Box::new(1); :12 inspector = Inspector(&days); :13 // Let's say `days` happens to get dropped first. @@ -112,8 +112,8 @@ of the finer details of how the drop checker validates types is totally up in the air. However The Big Rule is the subtlety that we have focused on this whole section: -**For a generic type to soundly implement drop, it must strictly outlive all of -its generic arguments.** +**For a generic type to soundly implement drop, its generics arguments must +strictly outlive it.** This rule is sufficient but not necessary to satisfy the drop checker. That is, if your type obeys this rule then it's *definitely* sound to drop. However diff --git a/src/doc/tarpl/exception-safety.md b/src/doc/tarpl/exception-safety.md index 9a31934090340..a43eec4f37ea3 100644 --- a/src/doc/tarpl/exception-safety.md +++ b/src/doc/tarpl/exception-safety.md @@ -37,7 +37,7 @@ needs to be careful and consider exception safety. ## Vec::push_all `Vec::push_all` is a temporary hack to get extending a Vec by a slice reliably -effecient without specialization. Here's a simple implementation: +efficient without specialization. Here's a simple implementation: ```rust,ignore impl Vec { diff --git a/src/doc/tarpl/hrtb.md b/src/doc/tarpl/hrtb.md index 640742f9b1499..3cc06f21df000 100644 --- a/src/doc/tarpl/hrtb.md +++ b/src/doc/tarpl/hrtb.md @@ -1,6 +1,6 @@ % Higher-Rank Trait Bounds (HRTBs) -Rust's Fn traits are a little bit magic. For instance, we can write the +Rust's `Fn` traits are a little bit magic. For instance, we can write the following code: ```rust @@ -52,21 +52,22 @@ fn main() { } ``` -How on earth are we supposed to express the lifetimes on F's trait bound? We need -to provide some lifetime there, but the lifetime we care about can't be named until -we enter the body of `call`! Also, that isn't some fixed lifetime; call works with -*any* lifetime `&self` happens to have at that point. +How on earth are we supposed to express the lifetimes on `F`'s trait bound? We +need to provide some lifetime there, but the lifetime we care about can't be +named until we enter the body of `call`! Also, that isn't some fixed lifetime; +call works with *any* lifetime `&self` happens to have at that point. -This job requires The Magic of Higher-Rank Trait Bounds. The way we desugar -this is as follows: +This job requires The Magic of Higher-Rank Trait Bounds (HRTBs). The way we +desugar this is as follows: ```rust,ignore where for<'a> F: Fn(&'a (u8, u16)) -> &'a u8, ``` -(Where `Fn(a, b, c) -> d` is itself just sugar for the unstable *real* Fn trait) +(Where `Fn(a, b, c) -> d` is itself just sugar for the unstable *real* `Fn` +trait) `for<'a>` can be read as "for all choices of `'a`", and basically produces an -*inifinite list* of trait bounds that F must satisfy. Intense. There aren't many -places outside of the Fn traits where we encounter HRTBs, and even for those we -have a nice magic sugar for the common cases. +*infinite list* of trait bounds that F must satisfy. Intense. There aren't many +places outside of the `Fn` traits where we encounter HRTBs, and even for +those we have a nice magic sugar for the common cases. diff --git a/src/doc/tarpl/lifetime-splitting.md b/src/doc/tarpl/lifetime-splitting.md index 9b6b769520fac..e320c5c7b6b6d 100644 --- a/src/doc/tarpl/lifetime-splitting.md +++ b/src/doc/tarpl/lifetime-splitting.md @@ -52,16 +52,17 @@ In order to "teach" borrowck that what we're doing is ok, we need to drop down to unsafe code. For instance, mutable slices expose a `split_at_mut` function that consumes the slice and returns *two* mutable slices. One for everything to the left of the index, and one for everything to the right. Intuitively we know -this is safe because the slices don't alias. However the implementation requires -some unsafety: +this is safe because the slices don't overlap, and therefore alias. However +the implementation requires some unsafety: ```rust,ignore fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { + let len = self.len(); + let ptr = self.as_mut_ptr(); + assert!(mid <= len); unsafe { - let self2: &mut [T] = mem::transmute_copy(&self); - - (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), - ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) + (from_raw_parts_mut(ptr, mid), + from_raw_parts_mut(ptr.offset(mid as isize), len - mid)) } } ``` diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/tarpl/lifetimes.md index f4475b738509b..5d7b305982fbe 100644 --- a/src/doc/tarpl/lifetimes.md +++ b/src/doc/tarpl/lifetimes.md @@ -7,11 +7,10 @@ the scope it's valid for. Within a function body, Rust generally doesn't let you explicitly name the lifetimes involved. This is because it's generally not really *necessary* -to talk about lifetimes in a local context; rust has all the information and -can work out everything. It's also a good thing because the scope of a borrow -is often significantly smaller than the scope its referent is *actually* valid -for. Rust will introduce *many* anonymous scopes and temporaries to make your -code *just work*. +to talk about lifetimes in a local context; Rust has all the information and +can work out everything as optimally as possible. Many anonymous scopes and +temporaries that you would otherwise have to write are often introduced to +make your code *just work*. However once you cross the function boundary, you need to start talking about lifetimes. Lifetimes are denoted with an apostrophe: `'a`, `'static`. To dip @@ -19,10 +18,10 @@ our toes with lifetimes, we're going to pretend that we're actually allowed to label scopes with lifetimes, and desugar the examples from the start of this chapter. -Originally, our examples made use of *aggressive* sugar -- high fructose corn syrup even -- -around scopes and lifetimes, because writing everything out explicitly is -*extremely noisy*. All Rust code relies on aggressive inference and elision of -"obvious" things. +Originally, our examples made use of *aggressive* sugar -- high fructose corn +syrup even -- around scopes and lifetimes, because writing everything out +explicitly is *extremely noisy*. All Rust code relies on aggressive inference +and elision of "obvious" things. One particularly interesting piece of sugar is that each `let` statement implicitly introduces a scope. For the most part, this doesn't really matter. However it diff --git a/src/doc/tarpl/safe-unsafe-meaning.md b/src/doc/tarpl/safe-unsafe-meaning.md index c7210f8e2cf98..1a4e5b8ffad19 100644 --- a/src/doc/tarpl/safe-unsafe-meaning.md +++ b/src/doc/tarpl/safe-unsafe-meaning.md @@ -125,13 +125,13 @@ unsafe impl UnsafeOrd for MyType { But it's probably not the implementation you want. Rust has traditionally avoided making traits unsafe because it makes Unsafe -pervasive, which is not desirable. Send and Sync are unsafe is because -thread safety is a *fundamental property* that Unsafe cannot possibly hope to -defend against in the same way it would defend against a bad Ord implementation. -The only way to possibly defend against thread-unsafety would be to *not use -threading at all*. Making every operation atomic isn't even sufficient, because -it's possible for complex invariants to exist between disjoint locations in -memory. For instance, the pointer and capacity of a Vec must be in sync. +pervasive, which is not desirable. Send and Sync are unsafe is because thread +safety is a *fundamental property* that Unsafe cannot possibly hope to defend +against in the same way it would defend against a bad Ord implementation. The +only way to possibly defend against thread-unsafety would be to *not use +threading at all*. Making every load and store atomic isn't even sufficient, +because it's possible for complex invariants to exist between disjoint locations +in memory. For instance, the pointer and capacity of a Vec must be in sync. Even concurrent paradigms that are traditionally regarded as Totally Safe like message passing implicitly rely on some notion of thread safety -- are you diff --git a/src/doc/tarpl/subtyping.md b/src/doc/tarpl/subtyping.md index 8c5ac9cca6b3f..975d1c59c76db 100644 --- a/src/doc/tarpl/subtyping.md +++ b/src/doc/tarpl/subtyping.md @@ -33,7 +33,7 @@ Variance is where things get a bit complicated. Variance is a property that *type constructors* have with respect to their arguments. A type constructor in Rust is a generic type with unbound arguments. For instance `Vec` is a type constructor that takes a `T` and returns a -`Vec`. `&` and `&mut` are type constructors that take a two types: a +`Vec`. `&` and `&mut` are type constructors that take two inputs: a lifetime, and a type to point to. A type constructor's *variance* is how the subtyping of its inputs affects the @@ -54,7 +54,8 @@ Some important variances: * `&'a T` is variant over `'a` and `T` (as is `*const T` by metaphor) * `&'a mut T` is variant with over `'a` but invariant over `T` * `Fn(T) -> U` is invariant over `T`, but variant over `U` -* `Box`, `Vec`, and all other collections are variant over their contents +* `Box`, `Vec`, and all other collections are variant over the types of + their contents * `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all other interior mutability types are invariant over T (as is `*mut T` by metaphor) @@ -71,7 +72,7 @@ to be able to pass `&&'static str` where an `&&'a str` is expected. The additional level of indirection does not change the desire to be able to pass longer lived things where shorted lived things are expected. -However this logic *does not* apply to see why `&mut`. To see why &mut should +However this logic *does not* apply to `&mut`. To see why `&mut` should be invariant over T, consider the following code: ```rust,ignore @@ -117,8 +118,9 @@ in them *via a mutable reference*! The mutable reference makes the whole type invariant, and therefore prevents you from smuggling a short-lived type into them. -Being variant *does* allows them to be weakened when shared immutably. -So you can pass a `&Box<&'static str>` where a `&Box<&'a str>` is expected. +Being variant *does* allows `Box` and `Vec` to be weakened when shared +immutably. So you can pass a `&Box<&'static str>` where a `&Box<&'a str>` is +expected. However what should happen when passing *by-value* is less obvious. It turns out that, yes, you can use subtyping when passing by-value. That is, this works: @@ -178,7 +180,7 @@ fn foo(usize) -> &'static str; in its place. Therefore functions *are* variant over their return type. `*const` has the exact same semantics as `&`, so variance follows. `*mut` on the -other hand can dereference to an &mut whether shared or not, so it is marked +other hand can dereference to an `&mut` whether shared or not, so it is marked as invariant just like cells. This is all well and good for the types the standard library provides, but diff --git a/src/doc/tarpl/unchecked-uninit.md b/src/doc/tarpl/unchecked-uninit.md index 9ab97b9e2d2d2..d0397c3719084 100644 --- a/src/doc/tarpl/unchecked-uninit.md +++ b/src/doc/tarpl/unchecked-uninit.md @@ -26,7 +26,7 @@ returns a pointer to uninitialized memory. To handle this, we must use the `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`. +dropping 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`. @@ -35,7 +35,7 @@ evaluating the old value: `write`, `copy`, and `copy_nonoverlapping`. 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!) + (this is equivalent to memcpy -- 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 @@ -68,14 +68,14 @@ unsafe { println!("{:?}", x); ``` -It's worth noting that you don't need to worry about ptr::write-style -shenanigans with types which don't implement Drop or -contain Drop types, because Rust knows not to try to Drop them. Similarly you -should be able to assign to fields of partially initialized structs -directly if those fields don't contain any Drop types. +It's worth noting that you don't need to worry about `ptr::write`-style +shenanigans with types which don't implement `Drop` or contain `Drop` types, +because Rust knows not to try to drop them. Similarly you should be able to +assign to fields of partially initialized structs directly if those fields don't +contain any `Drop` types. 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. +Rust trying to drop values you make like this before they're fully initialized. Every control path through that variable's scope must initialize the value before it ends, if has a destructor. *[This includes code panicking](unwinding.html)*. From b93438f648233ccdc98d80bcba53d78f672522f9 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 28 Jul 2015 15:16:59 -0700 Subject: [PATCH 100/104] fix incorrect name --- src/doc/tarpl/lifetimes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/tarpl/lifetimes.md index 5d7b305982fbe..37d0357336139 100644 --- a/src/doc/tarpl/lifetimes.md +++ b/src/doc/tarpl/lifetimes.md @@ -137,7 +137,7 @@ fn main() { // need to last for the whole scope x is valid for. The return // of as_str must find a str somewhere *before* this function // call. Obviously not happening. - println!("{}", as_str::<'d>(&'d temp)); + println!("{}", as_str::<'d>(&'d x)); } } } From 9123bb02ca3d71e16ce3e4a2ebb1fca49fcd93e2 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 28 Jul 2015 15:38:39 -0700 Subject: [PATCH 101/104] fix borrow-splitting --- src/doc/tarpl/SUMMARY.md | 2 +- .../{lifetime-splitting.md => borrow-splitting.md} | 7 +++---- src/doc/tarpl/unchecked-uninit.md | 10 +++++----- 3 files changed, 9 insertions(+), 10 deletions(-) rename src/doc/tarpl/{lifetime-splitting.md => borrow-splitting.md} (97%) diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/tarpl/SUMMARY.md index a7014d7f0207a..aeab8fc727693 100644 --- a/src/doc/tarpl/SUMMARY.md +++ b/src/doc/tarpl/SUMMARY.md @@ -17,7 +17,7 @@ * [Subtyping and Variance](subtyping.md) * [Drop Check](dropck.md) * [PhantomData](phantom-data.md) - * [Splitting Lifetimes](lifetime-splitting.md) + * [Splitting Borrows](borrow-splitting.md) * [Type Conversions](conversions.md) * [Coercions](coercions.md) * [The Dot Operator](dot-operator.md) diff --git a/src/doc/tarpl/lifetime-splitting.md b/src/doc/tarpl/borrow-splitting.md similarity index 97% rename from src/doc/tarpl/lifetime-splitting.md rename to src/doc/tarpl/borrow-splitting.md index e320c5c7b6b6d..fe5f2343dec59 100644 --- a/src/doc/tarpl/lifetime-splitting.md +++ b/src/doc/tarpl/borrow-splitting.md @@ -1,4 +1,4 @@ -% Splitting Lifetimes +% Splitting Borrows The mutual exclusion property of mutable references can be very limiting when working with a composite structure. The borrow checker understands some basic @@ -67,9 +67,8 @@ fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { } ``` -This is pretty plainly dangerous. We use transmute to duplicate the slice with -an *unbounded* lifetime, so that it can be treated as disjoint from the other -until we unify them when we return. +This is actually a bit subtle. So as to avoid ever making two `&mut`'s to the +same value, we explicitly construct brand-new slices through raw pointers. However more subtle is how iterators that yield mutable references work. The iterator trait is defined as follows: diff --git a/src/doc/tarpl/unchecked-uninit.md b/src/doc/tarpl/unchecked-uninit.md index d0397c3719084..da9fb294a1eab 100644 --- a/src/doc/tarpl/unchecked-uninit.md +++ b/src/doc/tarpl/unchecked-uninit.md @@ -15,11 +15,11 @@ initialization. Unfortunately, this opens us up to all kinds of problems. 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 uninitialized 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. +initialized or not. If it's believed uninitialized, then Rust will semantically +just memcopy the bits over the uninitialized 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 returns a pointer to uninitialized memory. From b539906de1d12dc935a1c3db9e511518dddabb3d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 28 Jul 2015 15:41:58 -0700 Subject: [PATCH 102/104] clarify subtyping --- src/doc/tarpl/subtyping.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/tarpl/subtyping.md b/src/doc/tarpl/subtyping.md index 975d1c59c76db..767a0aca542f9 100644 --- a/src/doc/tarpl/subtyping.md +++ b/src/doc/tarpl/subtyping.md @@ -1,9 +1,9 @@ % Subtyping and Variance -Although Rust doesn't have any notion of inheritance, it *does* include -subtyping. In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes -are scopes, we can partially order them based on the *contains* (outlives) -relationship. We can even express this as a generic bound. +Although Rust doesn't have any notion of structural inheritance, it *does* +include subtyping. In Rust, subtyping derives entirely from *lifetimes*. Since +lifetimes are scopes, we can partially order them based on the *contains* +(outlives) relationship. We can even express this as a generic bound. Subtyping on lifetimes in terms of that relationship: if `'a: 'b` ("a contains b" or "a outlives b"), then `'a` is a subtype of `'b`. This is a large source of From 4c48ffa53e7b9aa008bed5ac92a8362c0574172e Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 29 Jul 2015 15:55:19 -0700 Subject: [PATCH 103/104] add warning about reference section --- src/doc/tarpl/references.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/doc/tarpl/references.md b/src/doc/tarpl/references.md index da70dd529078b..3d7369eca0fed 100644 --- a/src/doc/tarpl/references.md +++ b/src/doc/tarpl/references.md @@ -22,6 +22,10 @@ what *aliased* means. To define aliasing, we must define the notion of *paths* and *liveness*. +**NOTE: The model that follows is generally agreed to be dubious and have +issues. It's ok-ish as an intuitive model, but fails to capture the desired +semantics. We leave this here to be able to use notions introduced here in later +sections. This will be significantly changed in the future. TODO: do that.** # Paths From ddb029034b734ec078589724c45e6eb8bf2e6645 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 29 Jul 2015 17:15:11 -0700 Subject: [PATCH 104/104] fix example code --- src/doc/tarpl/borrow-splitting.md | 4 +++- src/doc/tarpl/dropck.md | 6 +++--- src/doc/tarpl/leaking.md | 2 +- src/doc/tarpl/safe-unsafe-meaning.md | 2 +- src/doc/tarpl/vec-layout.md | 2 +- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/src/doc/tarpl/borrow-splitting.md b/src/doc/tarpl/borrow-splitting.md index fe5f2343dec59..123e2baf8fafd 100644 --- a/src/doc/tarpl/borrow-splitting.md +++ b/src/doc/tarpl/borrow-splitting.md @@ -137,6 +137,7 @@ impl<'a, T> Iterator for IterMut<'a, T> { Here's a mutable slice: ```rust +# fn main() {} use std::mem; pub struct IterMut<'a, T: 'a>(&'a mut[T]); @@ -170,6 +171,7 @@ impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { And here's a binary tree: ```rust +# fn main() {} use std::collections::VecDeque; type Link = Option>>; @@ -262,7 +264,7 @@ impl<'a, T> Iterator for IterMut<'a, T> { } impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { - fn next(&mut self) -> Option { + fn next_back(&mut self) -> Option { loop { match self.0.back_mut().and_then(|node_it| node_it.next_back()) { Some(State::Elem(elem)) => return Some(elem), diff --git a/src/doc/tarpl/dropck.md b/src/doc/tarpl/dropck.md index 419c61281d9fc..c75bf8b11794c 100644 --- a/src/doc/tarpl/dropck.md +++ b/src/doc/tarpl/dropck.md @@ -8,12 +8,12 @@ when we talked about `'a: 'b`, it was ok for `'a` to live *exactly* as long as gets dropped at the same time as another, right? This is why we used the following desugarring of `let` statements: -```rust +```rust,ignore let x; let y; ``` -```rust +```rust,ignore { let x; { @@ -25,7 +25,7 @@ let y; Each creates its own scope, clearly establishing that one drops before the other. However, what if we do the following? -```rust +```rust,ignore let (x, y) = (vec![], vec![]); ``` diff --git a/src/doc/tarpl/leaking.md b/src/doc/tarpl/leaking.md index dcb03b1c8b6a0..343de99f08ad0 100644 --- a/src/doc/tarpl/leaking.md +++ b/src/doc/tarpl/leaking.md @@ -188,7 +188,7 @@ data on their parent's stack without any synchronization over that data by ensuring the parent joins the thread before any of the shared data goes out of scope. -```rust +```rust,ignore pub fn scoped<'a, F>(f: F) -> JoinGuard<'a> where F: FnOnce() + Send + 'a ``` diff --git a/src/doc/tarpl/safe-unsafe-meaning.md b/src/doc/tarpl/safe-unsafe-meaning.md index 1a4e5b8ffad19..909308397d717 100644 --- a/src/doc/tarpl/safe-unsafe-meaning.md +++ b/src/doc/tarpl/safe-unsafe-meaning.md @@ -114,7 +114,7 @@ implementation: ```rust # use std::cmp::Ordering; # struct MyType; -# pub unsafe trait UnsafeOrd { fn cmp(&self, other: &Self) -> Ordering; } +# unsafe trait UnsafeOrd { fn cmp(&self, other: &Self) -> Ordering; } unsafe impl UnsafeOrd for MyType { fn cmp(&self, other: &Self) -> Ordering { Ordering::Equal diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/tarpl/vec-layout.md index 325399d622b69..3df63d5249c55 100644 --- a/src/doc/tarpl/vec-layout.md +++ b/src/doc/tarpl/vec-layout.md @@ -12,7 +12,6 @@ pub struct Vec { cap: usize, len: usize, } - # fn main() {} ``` @@ -69,6 +68,7 @@ impl Deref for Unique { unsafe { mem::transmute(&self.ptr) } } } +# fn main() {} ``` Unfortunately the mechanism for stating that your value is non-zero is

9E8XSY2)E(Vq?32Bxtg&VLnC zLbQ9O`V{KlN407-%5AWUvWt^9#f!)Nt6U8!>6(}HfJKs9+b2*4c~Aj8$P52pY*=_E z+kn#R<1hK*e(A{lED8!L-ClpF*lTzSY@BDzOSh4(P2*` z2gXWHTDs(AHAiEjf-I>QNv35DC3LW)JO7F6#R^k4HIY&m4^a&DP_P05Wvap#oSD27 zzH0qR6*>x@aRjv``nQwd#cK zk$Ik&?x&P@XbcPAj)YQ9hV2BO)JbyN>^I^#XXezmdb{6xU6oK`H7TvDAoY~ zbti-NwEo}9J2WVAeK{&S+Aw5|Ftu;31XrG*YHw;R=VshMY<&H)}nc5ZeK3WixDXL1m=q1466DRic6uL$V8#$v++_i$T zHjI^}rRN{qsQuPPn*zJ_2<0M%tW@-%croRpG$$kc!bTyBxriD``px6z{=7B4U6I+K z)sW=2APrV%@*aVw9|+49ou~52j2b`?Zw)w5sf3LQvpGMmkR_tgMq z*3;x_+yoLU6)D(#-jSm9T>*qvTUptd zhRW?Gq!vv^O=5YbK$R)nGI7IPdZl&vvYs}V3R7@N+>G0W3CgJIa8s$AbX)c2a57p5 zkAo-5Y|W2wu!_;fd?e+%dVTe|h<=%$_wOn1C7Mi@ zeNjPe1%dt3Ht97;ii(lNT5;v0?dLHU8ISxJw@oeoIrjP9ZVPQ*wnO{J78|O3=cg}3 zqu!XHwAz6EH?hbMFk^w?@pp)2Q`CPDdOoN8CF5jck0_~Zy5J~LEj)+{SX{&e=#yHP z;^K3yM~TCxXD#J4b=^(V%jV+oN!Db; z8^bM{1n&(wm_%oxQ$g=H(Uu5g4eH4+?x9kQsaw`XL2Dqj5ofJSq}%CZb8XnR)Bx7u zSF<#rLDVfI#+%OH&Zvj12Qhvdbj;~LIv+s|!BqXLpzv^-s{B1R-fr=MRxpsEy*pOb z_z=E6yd4X7V9VUxa$GXCS@3=$t5alA|j6rqe1@v4W} zd4mVT+y6?*&&VOJSJbNy46VKan!!EFIcBl5;W65DacQ|3H#f`Qqq4OKtU?t@y$h|) z&)e@EMF}Rt#a%CsNZLg(kg?6PGot)wwD;u>dL}I5YA0j`ZXnq_g=!(L?kHGKM!1yK z(KY?DbpJk+Ft0a65Xo!lg33VaHkPb4pd z3=J9C>pnrA^FRvHIA#4BO}?zLgf98nHE042_f)kO$yvkzat=34kh`x>x0_ZaEQ|f2 z;m(*xDA)ApX!uo-nNr3?8u zJwBI@7wzNcVC^v$CUzn9BT>V_H^9V=wnOe*38)X%aa%>f43au}@MUa^Xs)Td?TON~OO z-?(bSMHLb7nzp2zqD2W+z^VkVRdxBrY6AUnC%P4CV@T{#+!7XfX1W#er44R-u8NmB zE}NLlz?fA8T25?rx`#ejBxp;D$Azfyx2DJr_6ggo$QNW8pd`weJj0c_M3l2T~3y*Fmbx*$!%neKbCw&NV z3MIBan+hx7RNr{&ORxFBoXcqe*U3*u>Ca~zXOUxqYBxzb+yv!2*BTWRhNik2RXe!L zx%Hw&1+@5U%$)zc48{6g@$!1}^9qor^%-MG$B!dz^BLxf<)KGOIhxWyQ6Jtn@;AT) z3~qIVyW9M?j!TdcE%*hu)>SGdB#FypUAMhQ*m#M@rz!j}U+0&YZUCI-m0PBUZ-<$? zo!>=_-*!NUOT#0EC0qT5c9DgFeOR(eN{X%K9Y#w)I&9`r$amT*bs+6x0_U<;;RwtJj1Y~NzGec=CnotFUzQh`;;f$-zZxc3R*L!|%Qq^txMqg`I zcig%<)#jv#(97=CjNn1@UWM7mlT1XN7{;@PAPeNvxPka(N+bI(QzDXIW8$Us2{7pW zUU^5@A(cafb*q1Q9}K>to!(K@z7@Q}*D9RVJ?GCNAg@|y%pZp~`6o@ZKm{np4A!BC ztX`b3vAAt-WAR~nZhOBXLcsJ+_EL(hR%mFnJEY=u_`FN}aKEB^UeD*U*l-K*w9*H@RGrAo40joG3eU9u`_L_B)H#lamV@!7KkAtWDzZ>OgnZnBqp z26C=}y5$kdsy0TJaUuEvg6!;0{>F~(wht8-JdAZ{AfbZ&mQ;zmccN;-^P|CQ(X-DS z>svg`b1Nmx=a$8ZizrUQ3rvxZuprw znOhsFzT16{-iX88y_c#@8N=<-h`Cc(M7SeYE*`5 z?`zCmo4p;3yNb?#?O&k+!t&fwtlozw6{!!V;KYGE8X1-v^agq@JzQITKzHG=q%}XF zxdsB9Ib6rpD((YamBt6Le&doY%`wFusliizLYjZOLQpdvkDk$9)mF@r_8kpnll26+aY0GnMEtp22|pZ(%})k^lI+t$+T!9*=}Ws}U(Qt*~aP6|_On(O0eC}|l+ z0M9Z13gzB0ww-!yWoZ^Ns7Z+hGfY`fJhVE;p0ykXr83v8hY-Pc;KnMd)E=?T%y^ni zKE|;LyHfV$OnL4nOtPP5+zoa$D4|DDg2y&twQ!q?-i4~O8Up@p_pzfY zzTI+q6L&B=t?qFx+G)4kC6bWAN-No})uKHhqxNRpViIwDVPjaqfOvQOLaxfE3Qr{Fs5sK52IT3LP=SfXuRpyEm=D%n&CkE%2e|t!V;l= z+2UBRgftP7pHRClsc91lgv9Nrs)TtOKkA<|N_5haYMz#6FMJ;6#Zt1jWBax;_1Z*7 zVFo-IuH=W85sFKo?izJRVFNoAS2|^jPl_%J-D`RvVtZQ)wz>*+4B9aLYTPNyM7N`3 zLHO0)bN2djkpQPGC&NtWnS>yZPWZfYR98%hp~NFYx1xZ6-s<=d0_EF!+!f!MGL5zi z!~Mt6t4R;pf>d*OZPrE)I&1PMWtNuyvE9qVuc6(OS@!FV@HZ*titVRi2V<5Q8E5aE zN;oSDaFEAUdADxb~@SE0bVr&do|vu z?|05eSROrSVlaZ;hE-3<8(H9Hfg#-ew8@ufeY;~p7S6hRr&sXZLnB9MpY!Ww*4842 zYm!A)a+C;td*wrHOHsKlI2z!$;p;xumtmhd)*GO#oX_7!*q$FQ7uY-PY+uj2*ayy8CLr zu{A;PUcQb`Aif7afER4$Xk)F)(jqX*4(Wn${J!EdhoT!9PTk=Oeoolg!~}c6xH;_rCmaw099e!0I4drJO5bGTBib zp{4s?`2dzT>J!%yo!;^Py~boez2m0QWz~5vBRUMQ`@A_8>P=aEgiM`htT{&(4VOVM zFk==xKb;%8AsURpEzSVSr9J5EF)>=9fC`wSlQZK-B>VMF(|s{}E8 zs;Z9%9Radmgde7&F&f$5*-27S?q=vYtlf5VU-(*&eswAgxw~dOvZ3A%?go2V0Z}i5 zZxSx3qTk<+pK6t6+5e{PPT7Bdxzm`P`D>!f*_||i=21k=x*vwErVz_zqG`~}zD%LZ z-H_$2WxW2FZv0-hV$yW$>090T=wflrf5@HCwsDYc?{=-o!`tLCi<%57!*O66IFH8% z)uCO}HPN5r@?Cwo*&&AWF|)X}%l6`i1pW;f=5OZx(Y77X<#E-bd+nJUk@M-b+7a`8 zb(vM`Nj=!vW8sm)S=Dt965VsZt#^I(b@{Jj+ZyLxr@^Hsi4E;y)5J%><9XHTV)Hvf z&2I7yEmX~?rg{2dy}>CoL)AO%9npmsW~gO+9#P2(u!{Vr8Pj5GKRk3cQ>mkm6b3{{T-wu)lboXZ`2t@bi=wUsOxt@}&0FVP8eEC!JbDs(&_V zt4_IWu97!ix41l#SluyRG-dpg1zLwl#ta^525E4|3QmV#0giurCA>$zUvn*tNy2ar zuA({GXM&x1xfP!GD*piBAOg1RRGlVPq6Ij04Qe!`h}Mp9<1&DLM1?6=qULscsvfty zwgPGV!?}FmlEdepfB2F>J_lpnx;(?ZihhpC3}fGQ>hZDRtbbY`R@0btG%28C+umps z+fme@Qgn*(@eim6cyfn&fYhdJ06p+-GM-kqPve?{s?=vP;TF45+*tPn9b4rDmU5M< zYq^PdXOxOcT!M@@S85b=wjZP;C8NG8Dr&XqZJ|mf6`egc8frDh9d5Ih*X9j9J<-(t zbntW{C};D#%`UUnl#2w?yeZ#5BlQlrM4icGF?cd=pEZ_pU_O~yo1=-Z>>-OF@IMnmS{U{}smeSCjib};bE+qkyjA#_H=uzM6pD6lw^-Meea*CN6 z&8nGFzY)Ecdz3!`&Wx~%qnsm)m~p(+$x4!9m)3=`w9aVc-BmYlFzVC%2`S?&7A5oH z!=_BJ=*&nMfACCnBRo?=q#q3YU7~fm=#$)W{(1N%VU={z-(osl%FxZ3c<<~TexVo@ zA{MtNT?-0g(Z-Jp5g}f%o26WQxVK=BIU7+@;|0%teC4ydwcqe;Mb~&0RWrBd+1uB7 zHm*BHp9DUC9_Hg9^Ko$hLidCL{9Oc2dauA=24CLGJ}QtsEW``sRL z%x>4_vY=db%@0zDe%Wcu#d7|I?GM z?tSQmQ$FvnJ7f4hIu86i7zf=;Il*DOa6jN5>wkHD?imzD|C^lSa-8&8A~;@UR6h_X zB?KW+3i!+Twfu}LUJi#UahEGz35CmX+Up~`{4n|vhv4}kj_aHt&mUUej<)dM1fNdf zKekju`44+8daA!fo954*>A{?I*_+>dnUot$JCV13=2;gE$ItlA%{PDNjQH>cXPrsw z+P9+QjR!eM|BUgI=pPqd{RQ0Zt%B(rANTr}x%nSk9v zQd*8W<|Xd2|6+ zIW>Tu3d>vt(sQUF4=%XQz)z|Mq&fZAsjMFWUGfu<1uxr2c>r_;{w$Ku`1+U7Plzta zGF`y#16}YFq6@N27i5Vp*MN-gAu?V+#pfT9&ms9U$l@L%i|c(JTD}<2slevtpdukXinJ+iFh{*wPG+^6`bEIp#9jtW+H&g7BZyZN8~ z+DCQB%4cf;f}gET!qYFn&;EesEb@!pXY1F0x)!@V@N_=}&F~Am|E4p-51>zUwln>X z&Or}=U6~}2`YN0J1WwX`_+f_AV|7LYO>i=*OSpuY78B#XIQ^C5+%UU?S#t2C8x&>81)5w*-*h24zOOz%O6C)247;N+Z&c`7a+L62LTufF0AmXVNK+X?67I0gSMX6 zkS!6o*_C|H2zv*tA-iDYa2~qjO`l|&-1M>^s=`HsArkHKSHj6?G#M@jdQA?KPG@$Q zQ}9oxgHOGIGQC*w*Bm-mJQ9h!bPnEVq;HMxNI9GK`X>**W$V_r9Gvufq)a8^man>6 z!ca63i6o*!LW|+yUV?|Sx%*^1%wjyuuEfI=Kye55x#d&x#w&Jlj#+hlzEGW8Y>a`I&8L31J8P zTkOW(*Syncw*blPrbpLBx=SHcD4$9Qu2?)9aKFZ#flMOm780p^h-3Y2{s?^oVg>=w zm0i_Y#g3^q41}!!t!N_@)+d_uzsAMr@+M5AkEMU;P<9X3Nn)TXZC1<=6jt-VXrMTJZFO6rS1GTg<>JyUoki)aX9WMub z1NAsuwZYZgci-R+IUh3iGtY@%Cyq8sem)< zPxR+RTOchaL*7V#&jw#2;5Hcp+5SvrRCMM7u~ydGUr2_;Fw0Hx$N0OrK=7;B09sqCW5q~3(#wRb`QRzM7hWQ_pbBN!!aR0*Q z_iaJGWvIJab{07irU~3PF5c$4NTnBCm?zA0uBM>v*~1< zHZx6@nTR0qwV3i-8lOc)Mo{-NG)Au-SZ}sMfr1VhE>&*?NrJ=kRofqt# zt5i1ihVZG#mAT#^sVznq;+TcA15!W2;iF^e9#o77p>nDN#MxfB^^c%UD$kDEdvO!IB^(YoNXs~UOmLj_A4_*bnq(%)P)&}x)UpryWTs02 zvEA^XR#sn2K9H>Gvj}<7tn}HHDOL(&@{zMN| z;(-bq;ZExHBeJN(Ixw}`*cH=x8>_?_e_ng2A;q_nh?Vzi@@1ztP!oL+tKu!K=yHQQ z7OW;c`GpH7rr&*Xk-57PoKTx*2BHI4QDj#{pQ3}u0B;S zBzNV*Wp}?D-D3_!qMNFfvR%-EyysK?*3Q9A=TF7j=iPsF^s+s@T9eIK4h7oBZr^dy zr>>c-?s@a34Hs|87b5A@5S6~3M8WAh2XJWVV8{{x#R zep}eY`1Hdc4Szd$NKx)@Pg%9d)<3PMKB98XVQ*m!2%qjy33l8EaUgJlQ%@)qCR;-> zbM)y$>yD@}yQI z%K9H*yAyHz<~t*9GT7Z_v)g7c*zl{}&?(N-F6N!gaMGvB=rpTGV^`z^)hDx{IgRW5Mm*nyFIOs_cq?;7k z{NO~Dlvh;daU!WyLQKuh914%>kM1POe2!6M{S-=Us6P`E)HznF&oXI zblevRWCK=LIOP=c#d_33dg-8h&;}S=69QW58sSbuxQ><{u22Her^hLjl+)>O&!Kv^ ze1le(bhC{BX|qBD+4PX=4Yp$c7L8!Fc?`&tss;x)7o|#l$L!=bjn->+`m|cDSu54D z=~!Sc9oCw3{Ifx)*$~VIEX`7)VKFxHt%1S1!{CY+5z1$hx$IOzl4~}6fagO%KU}jh z$!a!C6`a*Fv4%d~od|NF#_4t=xSM)XtdVTG8=l7BU4aaPdq4d*Q-l2A``^EL>(*h! zy+rFY0Ee?037i#N@1Ceo*E8XuZ5WNpUTh8AA+nR3X=fDqFe;W+YPVKkjnrr0mf&x+ zg`Kmz_RU6{X#p8yPOnyLbQq+JloDbNm+gmN;NPv`Cx(V*9Kp1Z^2Tz!rkcwXdNkH2 z7IB>!jBioX0yjAZaR^>=$HAh!wC++`yt-C&pt92Ov61Mp8*4+X(n4MtZU1jE7>a}g zCZ~Ay+;(%kGBLVsdVW`8^5_IQUMv?ScVQsqK#TT;mN42HpFOatw0pV)(!_;;Ruv6C z*+Rscvcl>sR__FGC!479-rf3-eMuuVI)A1^*+se!APsYx2fnp{v)F=|61R5172$H| zTT#xX$LE;Plj!LYBRIWdWit*s@Bu<>mSvvqXJ4;wLRwQc@nk4!^h%LY z8ca#WEi)6_^2uOKOxJ_KV$2mpk4FO*!R@sLs)-cZ;RjSX-4;jO9SgimXeI~7YNd3| z>Fy1O@*$heA9Drr)Rv(8(I%K5K0&s@^rOV|qg*B-$z>ACX?{{yXRa)X(9@C#wxUYc z^d2+%tSAx^;>lf7JLS>(v!k#cph z*{kR?aBudnE6>0ul#*xkO5N2ObR&Mowr%toZTyT|w{E?y`-~>KhkJ;}6?u5=3!6ZW zu6?NvpuNZ!kNdV69E#jW;JX4_A9T>)UuOw)QEs}I{+aA;6v@gBPr}qwjZLq5f1xiHqXVR`{84$lf3F%i z;v_!AeTm<*?z*G&(U0gI@Le}`I%V`wl9tGH(0*eD|jQewdZBk&qDJJuie7xz7M>ivkP5cPr$+tqLp+_sx^v*rs}33`T)r+Z9-{^AvZ2dk$bb6j%&k zUnj7g3aq&t;vQPQ6X#P^-+h$(2!ZWZV2S0EXaT*G;-y2+_o#9RMbVuUFAN4jG8#kg zrg&j6-}0+y1A%Ss!r;C`pRe`19zIpN+ z+f>i{HQGdA+Z9-H`Tg7p^cjkmj(kqZ`?;?Z*iHr3Tz-{%h&zwsMfvWX+(!s(w*pHb z4lVF^QM@d_f#L=ApeX-tiWdfp18j`Ho8pDReB6Ja4FtBi3xoR(k?+ncFhATk%fEx- zMSdQ@7Wwy4yf9b@zFQ&pZB<}txNn~P#x~XSmeD2x+pfTp+y}T5{9jSLFjx#=Unj7g z3arWf2lo)Vkm5!8?z_2<5ZG=77Dewxm*U>D=vG=^0G}@=pWjP#2)j-C)x5lLnnR3N}w`H5fes!Q*m^ zxvV1;@LPHeJ>Fa#p_ET_*`)g5%&h@~k@|90nES1oE5Vv&NO!_e1y>8<213*hhLjFp zF6Ep&4Qp>Ek;NLhrra&>`oh73zNspR&ESF&(#Y!r_OQe1cUvrO(Hu&Zn!c(e`t!ZP zMn-#GrgobdJ!iIAf~9z>6g2tcd3SEKkRQu?vT1$PfG*L6B3i6JMHur&pjU!KG}w>U zRH(NcVB@1HF|t0NRFyZ8PjpWj>v)GY+U9yU?GM$)QlU!Htr6|cFwbjETB+U6HKXWf z#qyr5nUSJs^CjF4hd&$xl`=FsRHJ_Id(ka`J1g)2#$C9AYfEX)*ioTjA;q0r>A0jm zB9$(QN~_w1w{fp<-HKM>84~nxwt&qR^jb5~aP*ezdh#`Y14muWfVUttZa47{8cmi^ zF+ScD!cl!9?aGdp3Zr?C&HhF`Ag;56&>Q1!JL!j)BtEK_lJ55|Mz}ZOfZQ8Ugzk~26GP4wyAg1fk1gQJ-NAuUv#^oDYGvdj`uhHqNP~c zvo$?j@^2dU*y;N6gQ%*x31~OS;rN~Ut3qWMhZsIuk4xiKQ8_^t4}_ zN+P|!MBM9(B{iF)x}Y~a>oMs9{M>Bgv)MfV^?JV$bh({QpG(l|jEVil z=S|V5;rkNtg#{Eu=MdZlxM@;fJPzZVs$k#O0=~=>*b0GngHri=PMtgMolQ zfIJRuj}+}~i?O$lST~KtyoU6qjYGcb#@e!}zK<1XcQ437nA^h9?6!@? z8aUfvbI8;)vuJr`isjOX$r_+yQ zYPTCh)mXKOJ_{uKfD}u7UJq~3#hCj)7xwoJ{u%JU2R+FBE$|rL^V;Uv=qfaZ6Y+nPT ztD9i%I9cL%6AtbHin>|%X!)>V?b6Dw?Z*ML@?CDFyRw%oOYjV?Wp(yI`HY(8PWiZ1 zbjx*{Lzz!zYHv55-+2G<*qK1`dqX=73b{M~coF_E_Az<<+!tW{zgfP?-TmD!ke?!a z#h$;D=_}Iru+H7Ub*(0Te!4;{?{TagRhDZ)EZJvgGLTo!=fTmk8Df__D~pJ7X=Qs! zY6&-Gp%HePi?T(GJm(^J;L+AsND0mkg^{TGtgJV*qok^YRQHAvf9Ty$Gv6%C4y=VE+z^_G-{icZC0l$emw(sGnB;_j9e@IrSTv*wOG*&K5k6~rL1U-D6%1Kf= zat!ym%#m}gauGVO* z6tcQL9E}>UjJvZVg~E8=<8-I=og)g*_QJUR#DjA&U(#3U9(Hd7e7lsqUAJ4Nk1TW3 zj;^Z?yH|^x_z|HVu!pokU&z%Hvelo&oXI~JOFKkwK+yW551C}PB)I|L#|(@oODqFf zBCp6knG-yUfYNt2!S*8t*j}w}nL0bLo_6bByAt{3-qhxacstlII3vzhP>ODyn26PU zJq?pf2t)!o{-CQjP#$pD=UN7R&gHY2Bjfp&)v}>!@VIS08$F{N-N(J6=_MVd@UjTS zo2f#rnN^W>Jv(e(Q01{zC(W}Jt5>XbDPJqLoYV939=pM1MW1&EGP%!5`uzurpYnV4 zCj6Toz|9@}{{io5n!|@-Q{94fjJ0wNMwagytaf}NXAbOHZ$;Ft!(iH_k#r*!@>vx5PR4tf&on#17bW5v-0#W$sHOg)mCo~qo!Kd$e5 z9|b^x=|A;|AxeLX&%kf_NPi>^`z?`09{4Oc+6#B}@$EhEd$f16g;>2)ALyRZtB1p0 z_)P8c0A1?9?E@G?Cp(SQJFgn z8wBmvd2kT)=iCB=?U|c}zlJmJ#H|^BiJa&d8E=irAJ)!Vrj@-)v>_k1ZaYCwK*2kc z*`e!FlP)i`+G=thD_ge8!=c7z8cB_k&TZX z*GH*e?F9U_U_4fc*XVi&Upe(@>f{J+dYZbv(MI6defN=bTy-t-ef&IuH(wA~p3xi) zEN`Z{eG&_5-br$&6~eQ5rmgb|{&B7&$Vw=J#6O`q5g(OjId>aHcJ!Lj;fG@$kHs4D z<~*L$#)+D$FKDsbyva$&AD=E_{LjoGPj+vwm_tUX>3kh?_=qRx4OuN7Pt1GzIdG22 zq}OJ*1bzQ<`Z@4i65WW#`3GPQ(QZAa7q2vXX+0*#YOiQmpj#1)6P3PdN&nGwrIN<~ z!o3+$%=CuYD|)n%FZA{n@{OvH?v2HpX+cOgGVuaoJ*e~ zC)DE{by{&MSmkH8QX7Y*dIephvBF~(-9M$ev9BU$DD%Tim0zf`b2u!>c*E{g7f<}f6D7k1#GRNH|4j5 zl`kg}iKy~br?(Z0^?ADAjVD~rRhQdd%wNUjJJ9#Q9_v5?r@9^V>zF!qRdE3;%CxR7 zF6fpHFoF_*U+IjGI~~*=@@bwKfa;YsG#%)^DYzmL$drQ?nc^~n$t61^{^$26PAe6DbM zq=!c@=xoW#NG?8HjcFJ67;g%=bk3-+m*>&9Fe}&K5AN+(BQ|0EUX<#-Wi{51p#b0T zDMx6Q6?amIDwlkj0_>v>#pjWB~tEp1GXSlCCooc&x z3}71q&H$g}ujTOBXe%pA*6cyIu6yoBm?(t zQ*3894Z*!iOMJr;O=OtKxA4&n*lb`_kh5=0)DKvGiPr+n zC%b2%uuZ956tKo1WMBRmndkt#M#)45Dsp)qru2Y=mNM3q>$u-zuW}whjg^?<*t<+Q zg49m1EIiCh>ct0h!kaFfN(K&?0TVg_cNT#+Unj-A;CsL^F;A3Vkrom*V~C-f`+F3>r7uxU?#R-oFK)+|fJ5SW-Y zz+R@$LH#>VMc$Dnwrz;%0w(;R9$5BUN;*eiLiR+plKj5&z(o6;wYp^6bxeEHo7#&LS>56u-j}Y2{Qh*Mq3c|S(rMzSEWf(^ zKHdlPZF8Gf?FqEfieerD7CZ%!9EgOcfD^Xd5_OI(q@v9Mx6{UvK6Yrsnq)3HR)7>q z*);Gjqm$&l2KY|RD1;XOVvK~s^NB{&l<+$xt3z+ny39QnUt!W(T%e&;R}3bt*{s)U zt!JV4&Mt;yflSyRcLx(Xt3JGAtbIj$_e9Md3nG*a`x5S8QfD=|%LAJ#H@Df|msils zAm=6E>L>6@APB8YCAxdifwNC!vO$uarW1>^g6JgK=wc<_H`ZBQCM0z{U}!O;7O(^+ ziMGPoKHT#ky&S0p{e`%w3z+-bJCCFrG5Zg`9Xj&}diwUHb>B8eqLpn3{3Ck^>2cC+4>|77Lk`fqndc>U#*o|ihN1AZNAv$R_9Vb@6<7Z5Kc}R*=g*&8 z^XHz?jAo>fW-RL%S(aqU7qYO|#=<8ULjW5GY*>dQUT0arm?gv<8+L6M5Z1LRV?u2T zV?zSe5{^(CiYsj40=9x7t_>TA#U>=HKl}QaLzb3ArLW(=^}1i5uixu_@AYcL)h1uUpo{x>Mq}vAMF^2C$%hQ07Bx*xF(lOj>B_4O7706j8#5G z!}vjN^M>fXNcoNgu>2>{&pXs^1O9tuW*57Ah{IwXIzHdG&{z3X?1H=!=s4O#Jur+5 z-pV$RUB=NT{A?9qH22K|li)A_D-LtmWsqNt!~QLWT`Kr!ek;(=I7~ml6gbQd4r8J) z%g}iaGf??J?7)X8%-xmW!+W_9=lQ%@I~)E~?Bn_D_+mp?3uQvaU^*Rac+}sccl#5;V1hj8 z-fHMcQttU|%Bd~wNvQK%IF6nd9u{=)_X=)nK92q!FM^UuHG6($i>hTiNLqcYJ0>4M zi!_Zx)y#XwZD2#}i)xtboGQ1_!-QtHd7$FHWZdu8aArALl@gLc(l zo?i*dqm@jAp;?G})R$A}7RdFxYWmcXBTFI6(CqyBiT~2N2dFv&dYV>KONSq>Y5Hop z5~GIlQh-g76eQJ0BMdGzjozgra$*AAKk@X_6UUCxei#%^p*PX*YJL@%&3_C=nxo)A z-@EIs^3lnor+)P-;LFsn=vI3?DP+0i0|Hnz$7pOGLX!FJ5LktSHdhYHhMxO`2g*Qqpc^p<;E} zEx-jeM4_9#cD*wiG~@?kR=?L|Ytqy|DLoQyL%+cxoItO`xW5fX`s>0D+FplX{NE2P zYvNL@Nar20QHNmD>(%d|`_;;iCg>Xe1>S%@g4M5PU&kH#e$AD9jW<)J>Bc;sX8gIH zhD0l~wjr!2x!5Pd7&CV7UK!Q*6iN|MSCg0ZAhHw`yuq=$E8w)dTO4v$>h3~V6c0#} z;)^tyt-9bpHHF&y;|MBX_Tv|00fT0p%hWSy4R=otsz>Ee%#qC(JiCn-8SIuON|){s zZ7@ul=?-_9w?~xrp_k0w8dW7mj4j+Gi|nzH-TNptP-cQc@r~L3z_jFcB9Vzwjs64^ zvrP=-0ffI5>t56uT^5h8QSXW^i8_*P?Vfn|5c+u%giLpCI2-BfZkMu`7RV7v{d?-O zbT*p{#PW-@!I+#1+Q}z!2Ma^d=twc_RI=`&1-_2O$>eBPEBj*ikyX5S66RMyxRLKU z`uGXU{Fk=P>F~zOvM#U#Alfd3Rn@^~gzlO)^AOwT&Qa16t84ot#D*=A?gYJkk(_6c zjpo`_jAeu;rGzWluJ{GaKbCt^M6?M@iuLEz18ATQNCxN~a=(>y+c zh{S<_mXeXtTD$cs4KWE?PpK|dkqKVaT?t}w);)eT^%XW^kXFj2Lpo1~?8`-*P0qkI zfi*o{Ys-=R#n<+4+8i62Dn=H_eSP7Dv7~R{@-e^5+cDDS$%dU+ie$qhSC4P~?xx(8 zYfEc-TOG1=-8O#+_`vrnW9S3?6>#8W$7&F2yO8tXgsziWFH;esM9q+Kks7&(a|8;y zm4$Wmj#)~s*s00&I-}OnjFG6*Xhe+C5lbQ&x3={d!d_QOHh%4YZ`C&I{HsewZ+=Bz zX{60%ShXW!l}uW4Z&|?8H2c4@e%61hJ_a7dL!uGdy{c==>6jQ1fs*?W9(rfpJy)Ij z=0VZ;zxSZqC)DTghx{Ia9LSFtQr5V7J?UP3Lw{>Xgr@EV4|=m1`bg<^6wu+vA3^^y zbN2I|1?X{geRDR8w=(C8ViF$~x`j)H*%zc)=Jlg_!Nt=6T~i@*Q!`pj-RmKKWdpIf z>mo!(&o*!Brc1yQBnon&yYXH#SWBcrNlZG`6TbGa(~%m?W(QLaXSm&`o^W2|xih#R z?ai#Zer)XeRT*!3LGVt`*|Qtv@pYRr$+2Q6R2)lYHmw_%H=eywYwumYzGLC$(L`co z%fj3xEBfu)8@cUwoZ4>Y=aXs4@{8ys(OH?xH61_XWOZ!`0!f}I&KKK}Y zVOZ(=&y(j-r~7vGa->67cb?p*zNx-@JL&Jv${nH!@U_)#%~J$ls%mRa)|RTpP=Y*F zTl4z94e@!CQ0B%_u?#@?Eg&E5d=UcSn%*Qk1+!Vnb)$HiX|VHK?aUZe$tG0-pQS|4 zcH=)nXvv^ovWMIN8Cu&ne68Y4Ndb3OlG4K$r&dfUgB$wHct_M(8%`6G$uZzLqccWQ|%m^vbrQp z^tuAn4BA8_kuyYQFmbCBvayjOu2h^ZW)xZ~%w7`%NC``^&VJOzZ0y-J&V?tnV(Pj@ z!+X+Qo%j9K(tVptrOo@6j_=#NVCF>)dREtz-Z8LfXIj*1z72#Y*WF*}8|$9hJ36{| zs++tG8kg>5OH-z^I}60+Uv-p*ge$M&6F3K}l)~43M2)zKml%PrUrjtjPtszt9(9A% z6T>G`YV4D=dK!(S&w`wkT5md+M!r1qrO&|>7Otv%iMOL^ZU_4DJhr(G%)3XifKE0IgF`p(nz@UQvCH*%MS=!w=(i^z4J3hB8O5BGslP>nsZq z{+MXwI3WK5!n@9yY6UuXR!wD7=*%Z+G@_oKQ?{mB*+{`)Xq6C1Ie2@Z53A1v$|1A{ z%Ju{Z)RSmbJr)=Yp~Ye^5eWnZ+U^P3cGWs+Sw0d6tEQmV`x;Er=1Mc z#}APmV4be@qJg%P5k*i*7C{6NOZZ{+Y^_Ad!h7?V*_0anWWMsD+8Seor9eyNk&=v| zXi&V#FfT}RUq*qU&b%8;WPpR@h_#g1fdHfb>YkrFq8xX>+Gl%iYnPbdn z*K7Dad=JsAydaH<_z}|@G1{XZMqAO=BKe~p2FNyHKRS)|)Sj^bZE+gXGAW4lbdZkj zc36|<^P`ryz$UiTAbp=tjgw_zJXL-B@==Kx&sE>iLLmyz{?@J~$>fr**6Mqp5s19A z6b>HZ@}_c1+)aHh89`p*wbYVYYMJe?K$mHPN|fdWBfvdny9!8$eT^->gdc*afW>)ZrQ zQ&PlQvYlxCah5cPGLZMu%4fKQV;oo24 zX*fl(vyh>-`@r&(Z84T5pswY*Q+@pSoH}c&ax)BfMMk|G)`Q-nRi3BL8ZPft)94jP zEg3;UljhX78QuI0TWWPCGoOwppp7fV<)hR4w2$EtT!VFU0b zF{%S_fp4-otSHfSadX?mF!6yJ6uEQL1QBqFmm{0ALDfvQp{&O2O@}%QF<(Rq%8t0S ze!`t@b-3I5q5(Jl*aecFH+69#yCLq#=2AJAJ!n&(n!2{hrO4il;?Us)_r3H}O#Jo{ zdcY{ThVQ~@I3>qCMAj=GS+WQb&OG|)qlbc@e;)iCZ%}`&{u;T}z36syySkU~jp#n% zC42_P_=WAs{4q8hxJO28A=w*jvN?^3F8s5WrfA6CmTi|VA^Rzi4|ZU+ z1@32*_(#P$;%Aik7bQMT;oC;PFT<@UhyNt#ag*?>!1f@wKwOr_wbbHbIEAjpUqGB$ zc!kI1@dC6N{{iBHwYW|^g*M{j5NEH&&6nSNcw;z^cH*}o&MLgd<7{{Y-G*O=IQQ4$ zNP>iZCH@rRoVB=%u@Ciwe5uFYT3il?(Pj~5CHB{F>;@b@qDP8dHMk8GFN#19>#-sb zZBue?@g>#>8$e2Hp5uR-j#K@ax<|YSh^_5jsl^n@Xv`k`p+~l-f|IWsh@N2O1>7TS z5xvmkWIxtPoSjjw&Peqrsis}cN<6`j0k`;4HaQ#(ntW!x)}8DM;PcIHM^o72i5pGk zV2i&!>NnE!3oj}{`Sds}yvWP_ecUQs0d39p$Mu}{IudmSpy5rK)}Z7`1s3Ag6_J!f z_M{5iXxi`Lp9nXIJH96E)V*PsPqMVi*WjOw+Ja`g&n|7JX&(Z-mjhlC_iflh(~1p4 zI?*0Td!&Hg7I19}<0FNXM{aVsy!I77lKvpz-ciFXa+_DNuJM!5%OQ*8b%pQsh)X0u zY!2E+!xZ-hoDv>|@k;h-iM-5~X9qbED9HQw?+@KkyaT7UZx8+p)ibYLf`2Uhvv}G3 z@OR&Rx9`A$1Ng^l)+h%LQuryH7k&U^H7Mk$Pe_T%69U)#AO>0z-)|urr>CGtELB}k z+NoskEfTN!Dkml)1={E3K+@YR*{sftrkE#Tm(AkLU|hs`x2MGuOgbI80k^jqLd{NN z`v5J=v%(L=37|=&EH2tdjb*9cVdkPvg-!_`a#(v|SsEOt*9$Z1$pa>f#RUcEYV)@H zTHH3fjeOu|B~P>66KS#;GDXSVZ1;tX4nrI9Z(8{Vo)R8_`B^>RV?2kbNXi2!qrQ!g zGoO@|%|Ndn5ZmX0JBo_xYhrs1t}Gmdxox9xMm`2@VdkoqX?lr?-h_nHmi}~lz?{ZX zq8FF_*`m)J>nudgzGBwT^4f~u5Dtr1{+YabNM7c?bh_U}^6J5Fcv2m1lag%@ncN*I zw#QRBjz@sTe9XtEu9jDwFAaBegd_Pp9?3=`nM@>-rRko;uL~0}*8cx=N-n3sgI{k` z!l_hPX`{9$=)R$C=KCn`jbh&Kb5Ko@W&4ycqHog$K!r~ zwECua7U5qAKZWu1=kPS1e-#?SdwKTnaeVj}kbNx1(9k#KZz>0{4`}aKR4$U~ENZEb zT%wx^Gtl-ms&awW)&P0j>5#(_O1t?RFH6eqM8Yj6^A>-~=S>AH<^X#$y!Yehg{!&V zA;H_i>qoR|?Pu6U0*$?qXedK=U?58#uixi`2S4A{nJQA)C!*vTaG=e~b8?4s$@-D;#eP8 z)=>B(>hFYdV-EsT(AOm`#+t#0J3@cql#C!Q6RnwNblNt@7k$N z0CSWpbN?KC&J(r~$o%G^UO8%RGI^|CZzN=HFWQDPIi02ri!P_^5Vw=O?}WT>0BX+4 z+XA`M@{%RGz>WR5-sz3bNV_ivb3Pyk%<@R6t9QRQ8xNVKo?t9&h&w$+;r{?$Gk&$>Gh_g#=Jy zEl^bfAP&~SXJ7m)9N}N#yN|xxzrx|GzxQ5dEdY8UWm#bl2i=KW-txUQtJ-m#Kfm?Y z&Mim&`x|^@e9QSczRCCp&L_^mjDP6-((%mr6X#23ZN@*s?td`jA3L8r|7ylRasJl% zcQgL9#_KcZ7q`AQ6sZwy&DBWfI$L4VOP5)I13C+*YM7-j(rEIi4NA{D$1mLHvdpVk zJfu}D3|_d~=M*iy)>$5=i4p=sPt_)#&(k7ElNF8I-+uEv_TTBWn6{(v;&JQ7oQ4c(7it+diFY2WkAE*evvoEuil0rE$Nd)?qO(ZK6)n zq)>f7*6Ob4e|Nv_)E^q1JGbxL9?wCZCGyf~vGz0O7lnaNau8T16C5FmUbm+P3!TX3 zo@{8&L-qJq>O@~;OF!Gd;t#+5 zJz3tlJsi26vll&=z|m@!LVGeIfw}{zx(7AyD>6fos=Nr}Wdswdb(%$!bvV&#qF2Cj z5o;U*l^~4(A{jqiX*DHMi!A+(4vM_RB$f-fM#0>8HOMsfLR&qZVu3~R19Gk~VEaU2 zGFygV9e{WoFX2gW7O@=&g8GW&@YOWanrBneVw%CDA?7=B!Sy^0=FBfwvA==&RX&GO z6Y+qUh={W;{H#cT|2$lXAFz{J-vmM@J-7>;CubE(#}wL-2c(ynXaTI{B&0!{PQqzu zc!4K$$-;{z#RG{PZIlleO_Le@2GI?}ouq}zk&@KKh9=`&M=QjL8XMq%K$rv(c+kOQ z14CrtN?<3ou^#vdiF1LViAWF~U+Bq%MolS9I5Ic!eUQs-_!)o!_S`RcDYKa)0mOMJ zEvZe?ZVOVAnIWjwA>%wcMOpIZ)<``sc4t5JeT?>Lr?4B=lU>sZ6D}P#;>>QM; z1GEwP11yAzAK5&&jS-~~2+f2I!LW>v% zb3d68Q8;q!i_2k}5~g*lg!rCi z+;Sj6>tLRQ0mNEoA=$F5(hE>YSve?^l&Bk%HKbwzhVJOB>v@O?^|d-0^p9wE18-Wq6Ioa@ zLC%3DCvTdGP)Z8&Y}8EI%cT6u-9vr}Tet<)Ig80Or7}Un0;YpdVr9aO4$bzQ0nLIa922n~y11R0}2g^T9#k|K^Iv_4NeRp5g^s}SQi)-Xfr|`O>$O~&JhC& zQ{agPO%i*fo~OCCXN=59`XO@nD%9&LalvCVw$C?kk95Z@msn-RuC5t?vW9;IQ_CcS*X2|If6+$z($8yGCYl%ys)mz4PO4|D}3?bNvBb3eUP@5FHQrs3FyLJt78Sj!yBl^P=19j^DP_Nq5{Q znkOLIQNzw?+&wz)bw+AJ?o5KwMfDNR30hb(uS0vq1@MW*gNg?dWrxkX{ggd?-;vZxRAbso2G~Z=^4P5 zI_{ixUb zW}&%Vhrlj6Z4^9qJ3SEeNQ|Am?Mt8aJc#tnkFXv`&XJQk3uohGPUy^>xl=gGdF(uN z9yw1i>NpduUpN|L54&=#YbVBU<#e6I39y>sJpJ@}ZQ``~T!eqh8I@FX{-*I;WADoB z^l);C?}6c+|uH&c5Q?Gd~ z$7%{aRYQUyPO3|GJcqU^^bL4+RnE7aZ=G+j8Uv?yI7xe^n2m7$0*JSrr~LUf_CCC! zW=(BE#@NTFU~5d+Qa;A-Fqg8HA7f9VoG{fnpF795uw3&nlAXdm!R!M*uUN-9ORt#n z5~~I4Lc7}^CCv$s6V~aaq4gi&;^SP*yvW-MoO%X19yn|M*JeC~SDWd^SS!GDftmmL z7*Ni=50K-&)53{0qdMOcCkk4pjGc1&tSQNIw_*Rg9~5`$|Ge+qac=Wxj9nsqg^|Y+ z7Xd3h)WSfNG^q5WSR;KCMuQ|+GEd=RW%Qs;55EWO8%cw5uR)=8NfvmtSH329D^tL} z7aDm8-3T*lrY(q6)`{>t<qv+uKOAo_f89QXUd(-e+%+Xeii=D1Jl4 z?~?tfFkVDHK(&SZX~J{#b7lN;!MR5`i7WxvBJo5U`62IDShrFwxN`jlvjO{Dt0u(~ ztCBT}nr_wEfTb3?Vq1;XsX0-h;$x@HT!cXtKM`l4890ST>%d4Jv;LBkB(v1xP9zlB zS0x@kOGh&4+TOIZ#gtJXoCM8xWfoj>E(kbEt$rjwW!jC2enMn!EH!E5fVh;To>>>X zx4>BZf6j4T&j(c|-OiihLnj<#K3kD8PhPXaZpN(3E%=DkOS7Y8JZp(@SkA=QIpH2A z+|o<*6uV^H3oXm~U{Q`39p7Zplx=Chi=>;HcPFf|;#?V-thy<8#w=&VDCS%V$6FpJ zJ`i$6i;NzYW5SdsrXyQ5yxm$`&Ii2PqH|#?O;jR6l3eh&NjY~F7R~Bd=~mDCB3-^y z{hA&;Fx=>Z2p@XTkJ+eX1XVd(Cr>$e>XtAm0)c(^Eod@ z#&^?(|D`y)tjSX4NUMEbdTp@>_q5jWggoAFfhu1dqbi-C=JxR!<1^sOODhLgbY2Gr zjj72$Rud}|>0Z^6Dfc0Q!mdT@QLOg%?58Fwh}S)wyMJT!tse%4XJ&A>J+O_z+*B;e z;nqjOMh>s%4Q-;a>a!~iTP7=nCXSmuSv@kEwyx@6Wt)Q=-54&jh4rd>yyqMn!B)nu zYfs;&>~HnnIoM;ByzKI=4q}_S`~!0$WGSMZe(pLyvR#Pu7q(9jue$19AU(i>cj#JH z${G3nnfPP;u&(RbPA$Bdu2)x|*z`VDKA$T~l><`txQU6X!mPB)TtIfcFx^qX+S;>+ z+(S3J4STBUYf^I$k=<3soo-oa7wzqy_G(XPl^ON~ zJ1p*sdy)d$*HOndUv})Jan^AT-R_)qN#zi(dLxu48{x;xy+t(Z^G(O&`A48TX z=4h+#Z<19-YHe&dGtYjCvSX_HaC;k(-g#zj=S{quy3@0a!c^(1!>e-Gwr5_heZ^^6 zJ{Pb(@W%8kLQ{HSU6Zit1Dk#F=E{z+eoK*lHoCIQUb44tuU5|<@(O`N6E4^7{_;+^Zg9oN!yx>fvqW3oqjgJ}7f zSXmnR?U|c&+x7d0Ae6I~@A*y_a&KMK>UCkB9xbk@hRyo7jf*^gmwWu8%(h~S>$=qD zT}Eg~{5SjQqG z``+}Pm^La-y^GsV_bR`UCwNkmo6jk#=O*=Mi!txfW&bx}zPagZGSkh=6Oe*!q-(kM zI*)G|zoU$|s8wsq6Yp5QwaNdphL`X5ghKE4!?~V~FGo6SRF(R3ijRw+%6FbNeCO&e zXSZV#$@X?=SieG=0N4K*h zrw7@)(1LUk*-!ahTJ@IA78M^s;X8nLY@D1Pe zPO z-&3A5)+3%h$L}Hb$$QHV>nzgtS%(v>i!LrpAeIn`j`&^ZTi)>!a*bJvA^V{0Y_WzT z{+ky%Ph4N|tVlL6RvvL5W2v+amLdn?|GMPtvHm@NOJqG{R}RIN?lIR9TfsHhcg#D@ zIy!=V<$)yMF~9%pu-@KYc`dc34fgqfkQ8?i!Ju{M@*Zj!Z@!WXfpp>kMuZ_q+mEScOjPg}t#4_Qh)Khy8H?Zordx95*7& zfviA;7S2EvzhMhK9E7Lg;0adZDSBB&AAV*vYw$dt!LxXdgYheeu$DtPjKlFEM{p#% zIEth35?;WIxCt?i;aHrBn>mi-If2{YV@~8GPUaL&#jAK3ub`XLIGr;%6JOz8&cdgh zjW6&G)*_B|NFu>GoQo9a;WDK0JHh!R)}se5>yY6B`We743^IfqveTsXPf5Pv$8+m8bD^p20JD7SHB6 zJeTM34?Le2@Iqe1i+KqzZu-pBj-03YOE`8PhqhxrH}pczvXxQp8w!KQG@UBJ?`SaFbNYe8Ry_!oQ+nT4jb3tDqMuK_yf+z z#kiV3@+Vw?3;A#U%wPB`|HJ?CH~!8o0)j$_0b-!25SH+WL84N4MV0W0YEdHwiy^pM z)QX{Em>7ZNx+|NlX?~ z#8fd&Ocyi6OfgH$7IVa0F;C1Fbz*_=i+~6YT-MpqAr`Liv?lF{n@(A+Vb|HtJu6D~ zG&EW(mDQ;2N(KYX)~XU#W6+peJ)PQfMW-82#i~0?{d+o1Csr$u-qrmD+NNc;ZkcU} zQQa~}hjL7>oc?`|=~Zm&UWGhy)2q0qRK)ADZlPmMRzjDW&>c(2j-|9IRobye)3F9m z+H@>k)-kuVH%*qS_Esd)saVF!l&&o{4QjEnrF{z-bDJk;`j%6D%a!#lXWG%H`_@-1 zc0kvfc>bTr|Fhmc$4%E|5_YEBqhO-T%I}gQ+bgv}*>2a7x~D6hbCry5Q0tlaM!BBJ zw>~9-6OVOgB_S184t&O+a$c#FY&z35NV-=*29Ut3Lr7Suf@mbeD4qf|Wl~!C-)dm7hS_b`=t;~ArnOsjsObNRCDE zDya@GDNE{AJ^3utQN2HsPA2UF%s+3MVLGX>X{E-=A}$mX zE))_j6cX+)BwQ>cTr4D9C?wopNVva{aIuhZc_HDg3JI4K67DY~Y%+_c(n*z>0x~lR zOlA`5%rugjDW1$s@pNVi>dX{TWhPNcW>PK9OzMTq)P9|r+OIN8<&v(-OaYmh1ST^H zb!HmL%oI;%rg%Ct1$AbMs4|nNBr~a&W+wGQW@^9AOhQYa0V}LUL<@aJEPbl1E-hkO z=u=?DwOFggIxP}fB(>1z$kJ!r>d|7o7W#}^87=hrv~pT((4tohee|tOTJ)Lo7;|m& zbW}O&Qdf9jd(KVkH$zKMUps9rMz$&$3^aJvEnL@?e`?KT<<}H{lQ+|of0Wgd&nziL zPA%IVccYd0sVR`D%$w90x_xSZ8fU8H;0*Sui5bO2Z_y#!8no_jG}nZYfl#HqPLp=l ziE2xW-^fOf?YimSoVj3H%mriW474;?s&#n}8;h>I!Iamqu+d0uZ)ym7@>iN2Gaeh- zLPi>1Ta#Xori{MG>@WBWDA^eB8>#iCK&UF2%fusgB9+#!@1Q?qrV%pl>$Wx{7iy_< z%F9+G+bY#tzRpf$Yt?BDJBf5}BpH?##R>WSK6MJDvGC#v`2#+69LkNs+DP1u0z^hkQ~(ZaVRUW)4gdxK000000RRF32mlNK0smV70RR910C?J+mU(OyRT#z3 znb%fY=wd;Xwn$|uJCw2%5fP-6tzf}|P}bK4T79(GSD+LGgvJG{AOa#*M1q7r5DD;y zF@_Lhh#~$#Ohi${C5V7X3rGP)@XXf{NhmLkd3nD(_s%!>-Z|g-W(EWhg>zw_!^z0Z z%0W!PUtWR%2-7%j-bAdLa7DzT724n-q@X)e(I12G7&0&#t>GJ%J0cl_hEL2%#_XJl zW0UcMcO?;l=7__6NI-jZMi2DS%#UCwMqrG^#KFNmXn}h*Pa+;f2XsMCq#+%HF$|d) z>qYs{4AF?k{YXMPbVOJ5LSGETqj(%6k>y2&ArdiYi3iXY$>@Y`=#74O7(*}|qc9HR z{r*5Xj~Y)HPZ`e}>+}7=Lf&xcgc+lZamLmKC8hJ6Bx8GH7h^ADzd2?8d}oj`!#LhJ z#h4c;p6ho4#xi4tahb6yP_kg2v)Z`UxY1Z++!iR!4>&uGyN&xbT;_aiJZL;*{KEKU zse9Eo#uLVq#c;p=MIL2WOPV23(1&}Z2rILR&Au79Zf%? zo&}*8cUQL5lOt76grTbRY)rvy1W=Bps6sW?qXyft3;Xd&gAbeo4H@?h@O)A2wX3~$ zm)9Qh+8>oucb_LvN2g(oQC>ULYjeGJw%1mA?N+b#=HfYT5Ah9|bK)BMzU}&disf*` zct$arUD=J@*@HdVi@ll3K1^d@_G5nzU^+)C@*rZkh!tGSN-p72KF4KT&J|q6Dn8GZ zirAuvVm{4h7~njXu$1%pEX%ln3mIg&)?9~0x-++>ug0sC_*)~}ZX0oY+kKlgw)WPT zBogTlg-w@;z?T)zI!n za}38ai{m(+PcWMkIFXY$nNKoD5u*^sr#OXErLW^0QT#Mc=M2u|EY7B%dCX@4=dy@} zoTK=TdQTn0xA+dn@xAi(gL3y1enu_oZ~+%_34h=+>Tv~E6&<1I#?D;BpZE*c@i%VZ zCY3a0-EmGU`XqkADg27lID@nJ4d?LtU7`=)WhafzKxc>iPiLpqq+1U$y80_sehQ9? zUGcTpN3&Mr(L3~Rn%a%+vXL>VeY^L1$#wrZj?PSFy_+g+h~B!nD8fQj*g9;*Zq?Qy z9MNu%>mJW*x9@WeBIM3uWq6wIx>mgkIdKf9OMyD|7R!}mIYVk(P_I%B&EiZcb5Xq| za_czGl1i7;#Bq)bD4^8)lE>|D`c9ESF)TroWs64Ta7sGZM2qD zM^;b!lszhAj#iFjq>7{kTS(N_Y^&?ru^pn=fnCs?natE%z)_};NiCHW!|Yr~J?Gps z4AePFyA|H^-^V?oqtzE`-~)are>6l?+53$;Q`QixJ??X3^);2Qk@eW1uP?nN7|sMH zxjWJCq!a1Vn-Zy}L?0>925C%WA_kZq>Fgvu2AUp&UEQQ!ie_}zr>W9hyG}r~?L5X5iZk8Z zAMF0gJyIw3AF`kDQ+V3#TwRPD)s;Rq)Ao33X8cFvpRsBD19%`fhA{@?oe+%ewy_;& z7CXk+7@Nph?Xq4!#KS*0*(?u}NGqXvKzZoZ3ZgV%(5fFov>Iubhb@UjS+!P*71hJC zyDG)l$OWs(LurkFdcS+_x%JmoJu^1bI8yrRR99EsI``aj&)+@wR+B|UHXWlg)Uma^ zdmqg`{`ANRT22LAr$&Q1@HLATQRn7^+g8wuEsyP6L3izYY}X39PwrbZTh2PDOU^oJ zj+_;!o9w^--uF+?LwwxI$DMo}=Hvd8fA!M$=t({v<>N6v{v{ueqkTnV-fZJ{j`WrsoM173_zv}qq(lT6Ki{Bdn zn{n+7zFmynS=9Ul=jQ+y8iBQ{;aVF3n;O1VCfnK$c%6p8oxa8du=uowF*(5G0n-Tm zBc6OyVM8lt@vX7>bRMmIiaHm7VP(Su<`H17S)1^?jNjYQ!s|2uI+x*zHGs9iumMkQ zZj94gG*2)p`g~yY1fx%%;mMUuYYiCdz~%#60Bl8!-kYd7SNa~H?*aFHb7K@ZZQxXt zc?u7nKZ@tag`$9|vA8elc#alJU&le!I4~TgAEV!AB!KXeIj8Ru8|2@(DGHl9vjM;sF`Jz|K!g#`KKh*jQS~uwnkpVUSB%`;AM{6iU zu8zP%lwkWyu=*v~`x5m4dI3sO<^tw%%L9-=Wi3i{Ghi{!mncaB&VIl$oG-`sEx3Lw z;C6s2cLKKIUKy|*umkWYU?*S~U^n1ffIWc60DA%Z0N(-Z2Rsfq0C)m$5O4_aB;YXM zDd0W=I0|?g@Lj-hT>l%u3BXDG9sxWHcn-gx2fP4y5%3b=Wxy+dR{^I$`wsv=MBTpy z{0Q)Oxc(a8O@OusC3+jz-vPV}I1P9Y8Zj3z4=|rf)&d%|7UKIReBTDR126zs57+>B z0I&(L74^3on?pgued@=f4I{W7Aym-LBA8 zV_j1%eagM6a0?3SY1An&rMiCsuGHC9`-x$D|Vl@Mas8(}CC+MVrGuM$@N97+92KqGjV9IDP>IYJ@G+uP6x% z?>o$C<&$)zq{i0ah{|XATM&z;lvj2kjV?x`F22i!#EdI>V+$C0Le)o)EnzQ45U~kb zSlZYPOwX_sonb9gdQ;O8llIK;SDx5U72`k;LSLmu)yUo%_U*1nMj%nr1mdnD(*i8a zu}i3P8E^&G|0-my1K7Lq-P;%iCq~hNt7KF~4m1qY%&>y2}YW<4gj_A!2|F{#VQcvS+Rf+aUpput)iNCN@F*y*gMLGc z;_*>F*3@-?2Z?ggOOLO8z~@zf`c``2wu$GbQk0J{<<+nPBmjO!9qXXXP+mvDGdQaW zHWSm5Tqw96%sFow8#eqEOi&n$(u*7@XmbQ&{CFgY`qb%Xgqi!sx z8yh7*N9JdqVu$TQ(eO!Abd8qHZmVsniB+T<%R^2>&TFh~0o&xLSGCZ}XipS`(&ELX zMaKv#Td8%#==RJ?OWL1i-AP=(LB>XSXS0TSX)hx7#fy8*Dd6`;&&Eq@hs7_S-UuJ|S|JPR`XWwF_V zMo;M)?dLnkB#1-Mw$p5P@}(xKtF6+^QZDnexQyyKj^=hV&oiVZ96vWn?aWXfwQsy( zf`%Yf=Z4a_nbg}qQJxpKh)j4apViPh_{LtSNLZ{y&@#rglXj-fQ9wPWv#$2|0B1T> zgf?boZHjAn6pvPNcw3xgUQukTxD>;9%S+GS)GV3jcs9>6d4`#^*OAv@9B$|bblfSq zur_5eg2YTu(e6sdBFLg3VKKc}k6oGDdNUmvaBKAp@1*kpwdq8IOl{C^yQ4Elt>#3n z?zA^HkzA;nWjd{*Q=Mzcwj(As_+#|2UqL)rjY*@O&NE^*KLGzT#u;5d9{aIQ*y6oH z`w`O57INm}#AN;@KKhb{c0|XD%@#ivlSTHth#r?hEHh;1qkM|^qmjHBj^;G;*b$u= zkTn`NE9BHBLc- zScV!$@$DI3n$S?~pVXM0ll5%BF#@?7i}j>}Yh%3fSm(IelN?lVeKsW?3r6EDUc4B2 z?){xuLHMBl`ADUqmz4Xd~+IvN1 zk)TjUr@V83cNs8s9|Dh^*we+iDjtOzw=5Pp8Rbf=eyDf8$#Es@*Eq*Mp7>Cadv3iL zTVV>OWfj%v%#sY?gjhvC1mDDeao?0PI1RVdhZ`=Zk6p*Aaj*S+e->wNxO7qp9qt+JROv zS9zD3AKLRMR`kN$ftx#TE@EyvqA-CwCGcM&{`5Q}yfR_5PFwgEBWus}E}9%WU(c4V zDMm+S8p4S>9)vG8G5;`^AwU@yPGG(mNh$Acg*_`L_c?^NqAX9DkHUQn*oS$9;FnQ< zSY{Q+aAkAVPzWyzlTlg=@NulP+5JDI6YW)BiH zPadb2S>}{v9s>tLX@P7j**uBy^p%{O*{)h+5s99c;!BC^4B$ESWb`?~xR2pm`};v0 z4}!7*zNgw&PY$L$YFx7QGx-+R$;~S}@fEJLx65oR`5EMSm5#^#3TtvFGRFXFDT=Q1nu zGIA0@(&9I-_;K7_&#+_;+saXS6Cs#<=B)BB$+s=owvKZIZ!!iG;rkJ#Y%3MTO|2{% z-&gNSIEmi5tuh9aXUftsQRKzBy?V61A(;$6DN!6NH|>py=W!;_cz&s?PU+qaOhr%f z=2)!Xm?`Tu@7VQ0UiTkl{8=-AQVzya3R6k04aF?Axjz`A*q$ccI^I&VhK;meI}6zr20>SCJPfpbuuE1(Dov(jdqT^ zv1m21XUXIM({q((ix*}@r(_kc&Ew_fJEpM$8JlrB#@Dmgj9Xl1I?^(Q`C>gG^|go! z&JgK5gO{8uWn_gbU&cD*b&Y|Ouvl*D{VG=^-EWbf8WBF4IB-9?Vq`OEJGy5Ve1ot5;; z3CjY%dz`56W@@>kbGopG`pr|>$D!T@j=hgn)vcKorbzGk{Z*|U=FL`lhgq`0wVYMY znq<9P&ij=3+m&~9%^m?ilX9I~b=8`Yw5M{?yUnVJWONng3e#5)ch~xf`SECSHo#e6 zmBF?1G?}TYwv+>}#j0Y->_OqtHScejU3IpsUBup)(QjwB+I6RGag^hdtn|kr?~2Ti zx|~Pv%Qvqk$LB=F1P_Xmoiy_mJCxxX=g-YvJe?Ps(3wf8lRIw?HPnu*j>*htNK3|^ z5`TD&zcdBUbX`mN$~$>Ib&AFmtkX6N)<6%3)+EdFCHx~B8 zHS;BtRgC@_C9PFD-p=ij%{Jc+chE+*Wehg5B0eE7@6*T_+eZ2)pARH6|6zXGpYod$ zc1!D9&*W(7I%c-9tY!8L;ad01BqSztet;H-&D$i?L~qd^>V#%>Qy(p$n`kjDp{3MM z%V;^RrZx0++CYcsDLO(&>1p~doumM=>>X`UZR)j6?&CU(GTb~dXN5v{+0fX zeoHQ$rBCQQeM%STGrCA$&?UM|SLmumR)^JX^;o@DpS99jWo@)JS!HXxwZr z-nC9!?^*9#A6dV$er=th4q6EM4uR6c^e#PtHe9OG@9A?oLl>2>aIcKEZbe&Fw0;^bt+qZyYj;?`vFg@3@T1fE zce;)4MvH6Fdv)a=x)-GbbN%)Bz7HJf1l&&#&_;R?yqis3w2A(VhUgpg5Ph4rU>>!d zcG7OT8QlFg&UWI?H|Q47e+d0h+&n^eF;DMqD(lehT5emlo-Frpxi?W1RqH|RdQfJ{ zhE!PxYVT)?b=k<}!BpAAy-?-rR6uXiWea+z$|KyzWZBMTH_ErT?B=3+{|IQ)JlGj> zB3`zDE2BDoof%UNZ2iwfg(~#gbv=!1bkDjEJI9q~iS)Z># z(g)}c$o_oPT!orT>0y*_qCAZIbJ;H3isN@s_S54G2T*p?T?pGwmi#-0woaiiU385*rOe_oJ5{>47pkbbOESvJ+|tXX#8Rw^ zI$OcL?+babLO78w`g#w_ZBp*wvM5#7FvnC`2@BD~<$k(2^uw}rqo{xA>xN7mWUYLH)Gp0=(BB0N%5p0IrQjCayG6=s*t|!e z;d4W1t`)z#4Obr^{cqLL40a)``pvLoyI`ljmQm85n=;Dvezb>JAAaA>K43E+*Yowe zWA|0Wr|YO+k28h?eB2L<*ZjFBvnXG)4zL;?N1cW1ZtR2Z{eQ#qDwhBN0C?KXn0Y*u zTOYum8Ds3iFm@(OcFv4FN*ZgHh=|rPGcjUDV=SW*LzcKHNu)w5OL7Zol}cJHw_7P& zM0>iSkZxMuXU5Xh_1^owf4ra1JI`l6&vSlf`Td@Ae!uVeod<#-1n=VBA%!#WT^8c~ z6ixz;LOEJQKgA_wLINR#EaE5}fJM1T1OhJxM9_i;k^)F2K?so0q6TOL3c;~NB2Yy> zz#ACyNmP!gC8$8QylXiW1Vus&C=8-PEcm~edx80UgP~*<2RN3}@oi;M;Q`3;P4}H! z!+p*baWFZ6BQOO2{fh*U2qaP}e(#&ftv5Ua2Hg(Cw4*=U0Et;s5rVK$i5Wa21y-Wa z7-XP5UJhWm1!0W1KQ)p?Wzum(QUnz*3uL%rA&i(q6f=lKkEVr%QStNO(O{`42JIU{ zieXXlsz8}55W~n$32;OzlSSJ|Ba>J(1|6>sRJqjx80>VlFD)F_LJE(d(SvbBd!QyS zfhXVz1U%sV0_7zL08cOl1XFWsbL&8`j?dVYJ~Qe>F|t1Fa1xzGCF6(;W(0#dr49h& zDRnxt)m()*pBarlRAw}dOpSz9L zwxRZ{gVv_D^^P`o9eyLqM9OnAXtf3{`D&F+k;W ze|wq#@@wW3f4fCDvL7w`xW)7tTXb?HD$V}jwbl@xE6vTbtPLZeQJu6o6x( zB=HkSoZu~`sw4`Fl3jmboW7>Dm35%KciXUC&mZmy#=U@m7KVLWP*4bgKrH}TKx3v1 z5GmLY7As<*i3x)o8DY%gxq>m75zg~5RSW|04J8cF@C}K8fE`z+j;CkeCPwh!kY8hqniSis6tmpPq`SUR=&WueDr%d_^Jl zmqC?m5eNEs_?uN*!K*)Mzi38^$uOMDtE{Cz>Ypw+rPR3VO+YSm@;7mh>fiClh1clE zeSQ+B>hE4gRd~%_5~Q6=zj@O#G-t56M@5^u$%_&UHr zmB107F&*)ecgC!4eQhwOqdG(Ll$E@Gj`;s|3{Ax_z+3$g!vyP@7!LZc^qaws#M5u^ zPx^gm!E`Ep5vSZ&?%lTZ*mE%6W3X zq3jI4l;`GlT_&-`R^N6{iGJQsbko>3bj^TxwXid!cGr^SLp!X_OE+o0r>q*0BQQMu zi>uO(B0Kce+S~?u$q(ey39C=7%MUC&r0XRqKa|@;vT^iQy(8l%mhJrcMAe6li<~PX zm@l(mu5Xh%e?5tkqgbz2-j+lo{oE85M;ehyM!^JQGL;Ezr)XdfOaZ>g zq{xWBHx~$h(;G&?e;VZkKDasEpp{52lT~}*-o1h>Z@13klEe$3&aKu&DFAH3-1Pg2 z5?r5)wW-~s54n$I1p&+0l4KnrhC+3p_M@Wq9D#}yPwm13O9WJUe|ySqnID4gt|Qcj zH;frBAe%mOrG!hoXbhH|5Ikxgwly7l<8}4p>es!v8=L2~?PEQvThmu>sZNZ25qqXh z7lkXSc;|LKO>d86!d>aly=$WB%hyRdI@!}DP7PWeIK8l2WV6&~6?SdHmP*>#mxFcU zSc7-lSBoqvSp5Xsj7bcKjIAWf^s)>Gs>cG$5x>eEG&FHl?$Nl|_%$}iyD{Z7CvEM> zqFV1_wyA;fmh+ErBACr@LKRovd36l<8>YM3oxijFcEe(g5VFsKdK#;;N!50Hc7Nj~ zl}=O?;0T7os9G_Nsjz_I@&RZ-@+ta4R==Khz+V!R<{vpB59FpeA?ZhD(zwBHh;yZr zjc1YyF${L50_V$&ie%wDsjL_Va}$0cu$pRs*Cp%W2mn~%ejEa3h7*H{BSo=77))9m zm4b_kq~aL#FgD&15T{(kc6M-L7%4ImXNvQR3JRlPmRT5b9rPw z#YA`qv;59PZqZ_fiHVv26%@a}@^>iy@XCvT&6L?@-}_IS?HJ3V(kbve`jNtDlqqY8 z3<{OU&*?PmpYWMM{I&RcnMd32LpLq16zyb3>UPFFzv6q-eB$C;<-$S#i2Ey*brj26 z`VoRvg6~hhM62FKmz_*KuaIn_rYaJ2zgJ>hz7{ant%$~E`fX|2y^yo*%*jD-z64uQ@p}gU=LrMmWHX4}`h^&UN@esKB4;M8hr=3D5Gs&2^|;84k4$tO0>& z6#NK*6=1>4a7YAJX?nPrm>3@CU@zlgjvNsQ!)>M=5~wKsyOzud5^OLJqDH^~=oRS{ zX{TuNrBwVznnaLErbfZ$Jb0>3> zlT!!BQfu9Nq+D$#9?R{%ko@ti^PAOFuhEiao29T@R0hT$zHRXGV|>i7Dfg~(s=Bei z|7C%=+~SM6Tks{&sBuQBi%dFaSY*Ac`0m5EKIE2cIS_@p52h)wy@Z2N53Wv^JjsLMB@O*Y7+yBi;zAIKY%ETmmGUTKWT-4>rLo)8^n z(elNKG)8MxIz%zJfTF*aUePU+UmSQU>G~z-gyT9MP@IK;?PXFPxusBWC}GD?@4oDb zA+L7wqpYJ^>;{;&=`d|KPtz8;tF%aZ)r-xak`8$&+}COR3vK_u0L0~`DX=sJv%JKc z151MWEHB6K7$A)nn?60;A`t>Sv$;DupAac4>_818#gLe@N7H#2S(w<-B>3>ToEc1_ z)8eMyNQ&pcC_#)6!P3kMPq6-RKDgSr$6|3&B5d_W29r)B;ibVm-l14r*oQ>NEn`Gd z@vyt|=1pA5p27%%--!($qQfJ(+syRzQ7L#CAjO+KaS>m31Qp(U=&YHJ0h#Qgj5 zPES{0@)W&n)X`5*1ZCbj-PPuCL90?!b@-0=`Lo~r)JkO@>qNP&=zFE$!rtmV&qPr7 z9+v7s810rZmkC~Qegk8iOwF*h40?BQ+_}|SV@YYdXrJGyKP7i!lLPf0l7$$aX)8b2 zpNLj&Nz)!{EjaVmW7G5Yochj|p-Y)h^a5WaUv>0}7$ne^reB%dn`5(kokPw_qjj8i z?C9<@H;R)Ef7*$$7ScrrdFIy@SX;|!=X^UlW*5`+%ZuT<9r+*4Is)7d`iX^ZOK#Yd zEA)JZ%Uj?XiQyewU;^m??IO(?PzehZ!HI-8W~GnOjAs~4FF0?xRWZCAcmlT}I zxASZS6ky1=^WgZk&6$Lo@g?Cu*fv)hK4lx6f%C(7PFl|a;~4!*MvSki3RRO9+Z`@b zT$-+iC!cZ)N|N#IuxZv0T(8}vaK6`e)u)GkoqO7Y`o|u{q?a{44@)p#tJ2Sspd=Dk z_?gK0`}HGj@*HBzbZN~4?JgbfPDC6Rp;+8?6zHRjy*D>0%o}GOu4E?XK0tTIC4Fcm z-%%N+WMv`;cACeD9C&!=iZ{Z^Ggn{t@(%m)zLCf5gFfu_=*QXB-V+b@>n+fy+Yd@7 zrll=$t};yDN?z0AdU=rO{UB+_SV+yVea@c8xYP9;SreyJgnH!`)ebb5lWJHiJatCr z)v-N={GZ5c)T>VRt8M$-o_jEjI(gNpd+m+APqdyM5xTkxABE?jQehY;ArT0WSp0tm z+c`Fe@821V5-Z`2duBmJ1n}bgA2ERnUr7uv3HWQ}fadp(C_KEmcMD^b;~%*=1#5~N zroTa)C2a^U1@3%Z#PN%PZPCI6E653AKy-)&;ov6{6b{j#Fo+G8d|-JL#DvHYl~+(U(wpVl1q6gI~PJg_%hlX)egt0ehbbDUD} zn8ie%R_meY?fd;3zq&j=*2;JvVTwb>yuZ6aW!UFE6RVHVikI8t6(RJ;Qqe?tH!3Z+ z1=q06blexJdCO^T>{B^XvFmJ1=56`-qn4E5#bkBIh@9iSsz$eL{de^dhBmG32niW! z>&jfBxs8=LO6c7GB`<8de=!Fs1~^Ee?`wg^a}Xb4LXL6Wk@>&=9yG@XDL(gF3l#Xh zOYHl1bOh{Nvo(VFd2k9~2F$phf=w;WEdu}ITuUcj+_Sv;y7%bQBz5E|%l>j`@wGYJ zLHS`{pWPR2OCQMLLFuCS_1(*ss2W(5IqrTKZL_U2cJ$L;y&KnTFJHu`llR9GP4WUB zr=MG6O!zRlZ;hghuZr`BxPsD%#3kmC|Ghl(Uxe8E>RnG4h!VT&{By+ID>9FyExAbl zLV1>Ye4p07!95nHU4rNG2_?(7zBK*3Yawx2tcL!VV1&3}s7Tp|tcrt)?gtF6b~ks) zZ-FcgXj-9u)jOVBITh|*m*sgU^`x-z8{%@QvFJ;I*ro0P8F%A_(}U6&dOJPL76j#N zsEq{q(6-5a>I*mYINt1fyX$aXoaO!Ox~wg} QJ&hM32>KVoT7vcf00b!O^8f$< literal 0 HcmV?d00001 diff --git a/SourceSerifPro-Regular.woff b/SourceSerifPro-Regular.woff new file mode 100644 index 0000000000000000000000000000000000000000..e8c43b852e10e1556268d6c17b47bd0644d6edec GIT binary patch literal 49960 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%0AHnr$&HP)99eOG;&C)H59oX7tVW8CpZqiv(kJ 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 T#x!RM8#a#Gm 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 T`>xjor2he>K@jvWkwJRWB`#{9 literal 0 HcmV?d00001 diff --git a/intro.md b/intro.md deleted file mode 100644 index 939ba4fa21294..0000000000000 --- a/intro.md +++ /dev/null @@ -1,267 +0,0 @@ -% The Unsafe Rust Programming Language - -**This document is about advanced functionality and low-level development practices -in the Rust Programming Language. Most of the things discussed won't matter -to the average Rust programmer. However if you wish to correctly write unsafe -code in Rust, this text contains invaluable information.** - -This document seeks to complement [The Rust Programming Language Book][] (TRPL). -Where TRPL introduces the language and teaches the basics, TURPL dives deep into -the specification of the language, and all the nasty bits necessary to write -Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know -the basics of the language and systems programming. We will not explain the -stack or heap, we will not explain the syntax. - - - - -# Chapters - -* [Data Layout](data.html) -* [Ownership and Lifetimes](lifetimes.html) -* [Conversions](conversions.html) -* [Uninitialized Memory](uninitialized.html) -* [Ownership-oriented resource management (RAII)](raii.html) -* [Concurrency](concurrency.html) -* [Example: Implementing Vec](vec.html) - - - - -# A Tale Of Two Languages - -Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. -Any time someone opines the guarantees of Rust, they are almost surely talking about -Safe Rust. However Safe Rust is not sufficient to write every program. For that, -we need the Unsafe Rust superset. - -Most fundamentally, writing bindings to other languages -(such as the C exposed by your operating system) is never going to be safe. Rust -can't control what other languages do to program execution! However Unsafe Rust is -also necessary to construct fundamental abstractions where the type system is not -sufficient to automatically prove what you're doing is sound. - -Indeed, the Rust standard library is implemented in Rust, and it makes substantial -use of Unsafe Rust for implementing IO, memory allocation, collections, -synchronization, and other low-level computational primitives. - -Upon hearing this, many wonder why they would not simply just use C or C++ in place of -Rust (or just use a "real" safe language). If we're going to do unsafe things, why not -lean on these much more established languages? - -The most important difference between C++ and Rust is a matter of defaults: -Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular -action. In deciding to work with unchecked uninitialized memory, this does not -suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, -one does not have to suddenly worry about indexing out of bounds on `y`. -C and C++, by contrast, have pervasive unsafety baked into the language. Even the -modern best practices like `unique_ptr` have various safety pitfalls. - -It should also be noted that writing Unsafe Rust should be regarded as an exceptional -action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs -to make FFI bindings or define core abstractions. These fundamental libraries then expose -a *safe* interface for intermediate libraries and applications to build upon. And these -safe interfaces make an important promise: if your application segfaults, it's not your -fault. *They* have a bug. - -And really, how is that different from *any* safe language? Python, Ruby, and Java libraries -can internally do all sorts of nasty things. The languages themselves are no -different. Safe languages regularly have bugs that cause critical vulnerabilities. -The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different. -However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of -C to do the nasty things that need to get done. - - - - -# What does `unsafe` mean? - -Rust tries to model memory safety through the `unsafe` keyword. Interestingly, -the meaning of `unsafe` largely revolves around what -its *absence* means. If the `unsafe` keyword is absent from a program, it should -not be possible to violate memory safety under *any* conditions. The presence -of `unsafe` means that there are conditions under which this code *could* -violate memory safety. - -To be more concrete, Rust cares about preventing the following things: - -* Dereferencing null/dangling pointers -* Reading uninitialized memory -* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell) -* Invoking Undefined Behaviour (in e.g. compiler intrinsics) -* Producing invalid primitive values: - * dangling/null references - * a `bool` that isn't 0 or 1 - * an undefined `enum` discriminant - * a `char` larger than char::MAX - * A non-utf8 `str` -* Unwinding into an FFI function -* Causing a data race - -That's it. That's all the Undefined Behaviour in Rust. Libraries are free to -declare arbitrary requirements if they could transitively cause memory safety -issues, but it all boils down to the above actions. Rust is otherwise -quite permisive with respect to other dubious operations. Rust considers it -"safe" to: - -* Deadlock -* Leak memory -* Fail to call destructors -* Access private fields -* Overflow integers -* Delete the production database - -However any program that does such a thing is *probably* incorrect. Rust just isn't -interested in modeling these problems, as they are much harder to prevent in general, -and it's literally impossible to prevent incorrect programs from getting written. - -There are several places `unsafe` can appear in Rust today, which can largely be -grouped into two categories: - -* There are unchecked contracts here. To declare you understand this, I require -you to write `unsafe` elsewhere: - * On functions, `unsafe` is declaring the function to be unsafe to call. Users - of the function must check the documentation to determine what this means, - and then have to write `unsafe` somewhere to identify that they're aware of - the danger. - * On trait declarations, `unsafe` is declaring that *implementing* the trait - is an unsafe operation, as it has contracts that other unsafe code is free to - trust blindly. - -* I am declaring that I have, to the best of my knowledge, adhered to the -unchecked contracts: - * On trait implementations, `unsafe` is declaring that the contract of the - `unsafe` trait has been upheld. - * On blocks, `unsafe` is declaring any unsafety from an unsafe - operation within to be handled, and therefore the parent function is safe. - -There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for -historical reasons and is in the process of being phased out. See the section on -destructors for details. - -Some examples of unsafe functions: - -* `slice::get_unchecked` will perform unchecked indexing, allowing memory - safety to be freely violated. -* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is - not "in bounds" as defined by LLVM (see the lifetimes section for details). -* `mem::transmute` reinterprets some value as having the given type, - bypassing type safety in arbitrary ways. (see the conversions section for details) -* All FFI functions are `unsafe` because they can do arbitrary things. - C being an obvious culprit, but generally any language can do something - that Rust isn't happy about. (see the FFI section for details) - -As of Rust 1.0 there are exactly two unsafe traits: - -* `Send` is a marker trait (it has no actual API) that promises implementors - are safe to send to another thread. -* `Sync` is a marker trait that promises that threads can safely share - implementors through a shared reference. - -All other traits that declare any kind of contract *really* can't be trusted -to adhere to their contract when memory-safety is at stake. For instance Rust has -`PartialOrd` and `Ord` to differentiate between types which can "just" be -compared and those that implement a total ordering. However you can't actually -trust an implementor of `Ord` to actually provide a total ordering if failing to -do so causes you to e.g. index out of bounds. But if it just makes your program -do a stupid thing, then it's "fine" to rely on `Ord`. - -The reason this is the case is that `Ord` is safe to implement, and it should be -impossible for bad *safe* code to violate memory safety. Rust has traditionally -avoided making traits unsafe because it makes `unsafe` pervasive in the language, -which is not desirable. The only reason `Send` and `Sync` are unsafe is because -thread safety is a sort of fundamental thing that a program can't really guard -against locally (even by-value message passing still requires a notion Send). - - - - -# Working with unsafe - -Rust generally only gives us the tools to talk about safety in a scoped and -binary manner. Unfortunately reality is significantly more complicated than that. -For instance, consider the following toy function: - -```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { - if idx < arr.len() { - unsafe { - Some(*arr.get_unchecked(idx)) - } - } else { - None - } -} -``` - -Clearly, this function is safe. We check that the index is in bounds, and if it -is, index into the array in an unchecked manner. But even in such a trivial -function, the scope of the unsafe block is questionable. Consider changing the -`<` to a `<=`: - -```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { - if idx <= arr.len() { - unsafe { - Some(*arr.get_unchecked(idx)) - } - } else { - None - } -} -``` - -This program is now unsound, an yet *we only modified safe code*. This is the -fundamental problem of safety: it's non-local. The soundness of our unsafe -operations necessarily depends on the state established by "safe" operations. -Although safety *is* modular (we *still* don't need to worry about about -unrelated safety issues like uninitialized memory), it quickly contaminates the -surrounding code. - -Trickier than that is when we get into actual statefulness. Consider a simple -implementation of `Vec`: - -```rust -// Note this defintion is insufficient. See the section on lifetimes. -struct Vec { - ptr: *mut T, - len: usize, - cap: usize, -} - -// Note this implementation does not correctly handle zero-sized types. -// We currently live in a nice imaginary world of only positive fixed-size -// types. -impl Vec { - fn push(&mut self, elem: T) { - if self.len == self.cap { - // not important for this example - self.reallocate(); - } - unsafe { - ptr::write(self.ptr.offset(len as isize), elem); - self.len += 1; - } - } -} -``` - -This code is simple enough to reasonably audit and verify. Now consider -adding the following method: - -```rust - fn make_room(&mut self) { - // grow the capacity - self.cap += 1; - } -``` - -This code is safe, but it is also completely unsound. Changing the capacity -violates the invariants of Vec (that `cap` reflects the allocated space in the -Vec). This is not something the rest of `Vec` can guard against. It *has* to -trust the capacity field because there's no way to verify it. - -`unsafe` does more than pollute a whole function: it pollutes a whole *module*. -Generally, the only bullet-proof way to limit the scope of unsafe code is at the -module boundary with privacy. - diff --git a/rust.css b/rust.css new file mode 100644 index 0000000000000..cd158283180a2 --- /dev/null +++ b/rust.css @@ -0,0 +1,407 @@ +/** + * Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT + * file at the top-level directory of this distribution and at + * http://rust-lang.org/COPYRIGHT. + * With elements taken from Bootstrap v3.0.2 (MIT licensed). + * + * Licensed under the Apache License, Version 2.0 or the MIT license + * , at your + * option. This file may not be copied, modified, or distributed + * except according to those terms. + */ +@font-face { + font-family: 'Fira Sans'; + font-style: normal; + font-weight: 400; + src: local('Fira Sans'), url("FiraSans-Regular.woff") format('woff'); +} +@font-face { + font-family: 'Fira Sans'; + font-style: normal; + font-weight: 500; + src: local('Fira Sans Medium'), url("FiraSans-Medium.woff") format('woff'); +} +@font-face { + font-family: 'Source Serif Pro'; + font-style: normal; + font-weight: 400; + src: local('Source Serif Pro'), url("SourceSerifPro-Regular.woff") format('woff'); +} +@font-face { + font-family: 'Source Serif Pro'; + font-style: italic; + font-weight: 400; + src: url("Heuristica-Italic.woff") format('woff'); +} +@font-face { + font-family: 'Source Serif Pro'; + font-style: normal; + font-weight: 700; + src: local('Source Serif Pro Bold'), url("SourceSerifPro-Bold.woff") format('woff'); +} +@font-face { + font-family: 'Source Code Pro'; + font-style: normal; + font-weight: 400; + src: local('Source Code Pro'), url("SourceCodePro-Regular.woff") format('woff'); +} + +*:not(body) { + -webkit-box-sizing: border-box; + -moz-box-sizing: border-box; + box-sizing: border-box; +} + +/* General structure */ + +body { + background-color: white; + margin: 0 auto; + padding: 0 15px; + font-family: "Source Serif Pro", Georgia, Times, "Times New Roman", serif; + font-size: 18px; + color: #333; + line-height: 1.428571429; + + -webkit-font-feature-settings: "kern", "liga"; + -moz-font-feature-settings: "kern", "liga"; + font-feature-settings: "kern", "liga"; +} +@media (min-width: 768px) { + body { + max-width: 750px; + } +} + +h1, h2, h3, h4, h5, h6, nav, #versioninfo { + font-family: "Fira Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; +} +h1, h2, h3, h4, h5, h6 { + color: black; + font-weight: 400; + line-height: 1.1; +} +h1, h2, h3 { + margin-top: 20px; + margin-bottom: 15px; +} +h1 { + margin-bottom: 20px; +} +h4, h5, h6 { + margin-top: 12px; + margin-bottom: 10px; + padding: 5px 10px; +} +h5, h6 { + text-decoration: underline; +} + +h1 { + font-size: 28px; + font-weight: 500; + padding: .1em .4em; + border-bottom: 2px solid #ddd; +} +h1.title { + line-height: 1.5em; +} +h2 { + font-size: 26px; + padding: .2em .5em; + border-bottom: 1px solid #ddd; +} +h3 { + font-size: 24px; + padding: .2em .7em; + border-bottom: 1px solid #DDE8FC; +} +h4 { + font-size: 22px; +} +h5 { + font-size: 20px; +} +h6 { + font-size: 18px; +} +@media (min-width: 992px) { + h1 { + font-size: 36px; + } + h2 { + font-size: 30px; + } + h3 { + font-size: 26px; + } +} + +nav { + column-count: 2; + -moz-column-count: 2; + -webkit-column-count: 2; + font-size: 15px; + margin: 0 0 1em 0; +} +p { + margin: 0 0 1em 0; +} + +strong { + font-weight: bold; +} + +em { + font-style: italic; +} + +footer { + border-top: 1px solid #ddd; + font-size: 14.3px; + font-style: italic; + padding-top: 5px; + margin-top: 3em; + margin-bottom: 1em; +} + +/* Links layout */ + +a { + text-decoration: none; + color: #428BCA; + background: transparent; +} +a:hover, a:focus { + color: #2A6496; + text-decoration: underline; +} +a:focus { + outline: thin dotted #333; + outline: 5px auto -webkit-focus-ring-color; + outline-offset: -2px; +} +a:hover, a:active { + outline: 0; +} + +h1 a:link, h1 a:visited, h2 a:link, h2 a:visited, +h3 a:link, h3 a:visited, h4 a:link, h4 a:visited, +h5 a:link, h5 a:visited {color: black;} +h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, +h5 a:hover {text-decoration: none;} + +/* Code */ + +pre, code { + font-family: "Source Code Pro", Menlo, Monaco, Consolas, "DejaVu Sans Mono", monospace; + word-wrap: break-word; +} +pre { + border-left: 2px solid #eee; + white-space: pre-wrap; + padding: 14px; + padding-right: 0; + margin: 20px 0; + font-size: 13px; + word-break: break-all; +} +code { + padding: 0 2px; + color: #8D1A38; +} +pre code { + padding: 0; + font-size: inherit; + color: inherit; +} + +a > code { + color: #428BCA; +} + +/* Code highlighting */ +pre.rust .kw { color: #8959A8; } +pre.rust .kw-2, pre.rust .prelude-ty { color: #4271AE; } +pre.rust .number, pre.rust .string { color: #718C00; } +pre.rust .self, pre.rust .boolval, pre.rust .prelude-val, +pre.rust .attribute, pre.rust .attribute .ident { color: #C82829; } +pre.rust .comment { color: #8E908C; } +pre.rust .doccomment { color: #4D4D4C; } +pre.rust .macro, pre.rust .macro-nonterminal { color: #3E999F; } +pre.rust .lifetime { color: #B76514; } + +/* The rest */ + +#versioninfo { + text-align: center; + margin: 0.5em; + font-size: 1.1em; +} +@media (min-width: 992px) { + #versioninfo { + font-size: 0.8em; + position: fixed; + bottom: 0px; + right: 0px; + } + .white-sticker { + background-color: #fff; + margin: 2px; + padding: 0 2px; + border-radius: .2em; + } +} +#versioninfo a.hash { + color: gray; + font-size: 80%; +} + +blockquote { + color: #000; + margin: 20px 0; + padding: 15px 20px; + background-color: #f2f7f9; + border-top: .1em solid #e5eef2; + border-bottom: .1em solid #e5eef2; +} +blockquote p { + font-size: 17px; + font-weight: 300; + line-height: 1.4; +} +blockquote p:last-child { + margin-bottom: 0; +} + +ul, ol { + padding-left: 25px; +} +ul ul, ol ul, ul ol, ol ol { + margin-bottom: 0; +} +dl { + margin-bottom: 20px; +} +dd { + margin-left: 0; +} + +nav ul { + list-style-type: none; + margin: 0; + padding-left: 0px; +} + +/* Only display one level of hierarchy in the TOC */ +nav ul ul { + display: none; +} + +sub, +sup { + font-size: 75%; + line-height: 0; + position: relative; +} + +hr { + margin-top: 20px; + margin-bottom: 20px; + border: 0; + border-top: 1px solid #eeeeee; +} + +table { + border-collapse: collapse; + border-spacing: 0; + overflow-x: auto; + display: block; +} + +table tr.odd { + background: #eee; +} + +table td, +table th { + border: 1px solid #ddd; + padding: 5px; +} + +/* Code snippets */ + +.rusttest { display: none; } +pre.rust { position: relative; } +.test-arrow { + display: inline-block; + position: absolute; + top: 0; + right: 10px; + font-size: 150%; + -webkit-transform: scaleX(-1); + transform: scaleX(-1); +} + +.unstable-feature { + border: 2px solid red; + padding: 5px; +} + +@media (min-width: 1170px) { + pre { + font-size: 15px; + } +} + +@media print { + * { + text-shadow: none !important; + color: #000 !important; + background: transparent !important; + box-shadow: none !important; + } + a, a:visited { + text-decoration: underline; + } + p a[href]:after { + content: " (" attr(href) ")"; + } + footer a[href]:after { + content: ""; + } + a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + pre, blockquote { + border: 1px solid #999; + page-break-inside: avoid; + } + @page { + margin: 2cm .5cm; + } + h1:not(.title), h2, h3 { + border-bottom: 0px none; + } + p, h2, h3 { + orphans: 3; + widows: 3; + } + h2, h3 { + page-break-after: avoid; + } + table { + border-collapse: collapse !important; + } + table td, table th { + background-color: #fff !important; + } +} + +#keyword-table-marker + table thead { display: none; } +#keyword-table-marker + table td { border: none; } +#keyword-table-marker + table { + margin-left: 2em; + margin-bottom: 1em; +} diff --git a/vec.md b/vec.md index d38265b429e4b..71b950b12215a 100644 --- a/vec.md +++ b/vec.md @@ -11,7 +11,7 @@ project will only work on nightly (as of Rust 1.2.0). First off, we need to come up with the struct layout. Naively we want this design: -``` +```rust struct Vec { ptr: *mut T, cap: usize, @@ -30,7 +30,7 @@ As we saw in the lifetimes chapter, we should use `Unique` in place of `*mut when we have a raw pointer to an allocation we own: -``` +```rust #![feature(unique)] use std::ptr::{Unique, self}; @@ -474,6 +474,7 @@ impl DoubleEndedIterator for IntoIter { } } } +``` Because IntoIter takes ownership of its allocation, it needs to implement Drop to free it. However it *also* wants to implement Drop to drop any elements it From fa6fff585f5c23146e6d8db7899f4bb1d71399b4 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 24 Jun 2015 16:21:17 -0700 Subject: [PATCH 025/104] vec 1.0 --- vec.md | 520 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 509 insertions(+), 11 deletions(-) diff --git a/vec.md b/vec.md index 71b950b12215a..a2fecf8238251 100644 --- a/vec.md +++ b/vec.md @@ -1,11 +1,11 @@ % Example: Implementing Vec -TODO: audit for non-ZST offsets from heap::empty - To bring everything together, we're going to write `std::Vec` from scratch. Because the all the best tools for writing unsafe code are unstable, this project will only work on nightly (as of Rust 1.2.0). + + # Layout First off, we need to come up with the struct layout. Naively we want this @@ -63,16 +63,19 @@ as `std::rt::heap::EMPTY`. There are quite a few places where we'll want to use `heap::EMPTY` because there's no real allocation to talk about but `null` would make the compiler angry. -All of the `heap` API is totally unstable under the `alloc` feature, though. +All of the `heap` API is totally unstable under the `heap_api` feature, though. We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of the `heap` API anyway, so let's just get that dependency over with. + + + # Allocating Memory So: ```rust -#![feature(alloc)] +#![feature(heap_api)] use std::rt::heap::EMPTY; use std::mem; @@ -184,6 +187,10 @@ fn grow(&mut self) { Nothing particularly tricky here. Just computing sizes and alignments and doing some careful multiplication checks. + + + + # Push and Pop Alright. We can initialize. We can allocate. Let's actually implement some @@ -240,6 +247,10 @@ pub fn pop(&mut self) -> Option { } ``` + + + + # Deallocating Next we should implement Drop so that we don't massively leaks tons of resources. @@ -270,6 +281,10 @@ impl Drop for Vec { } ``` + + + + # Deref Alright! We've got a decent minimal ArrayStack implemented. We can push, we can @@ -311,6 +326,10 @@ impl DerefMut for Vec { Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, `iter_mut`, and all other sorts of bells and whistles provided by slice. Sweet! + + + + # Insert and Remove Something *not* provided but slice is `insert` and `remove`, so let's do those next. @@ -362,6 +381,10 @@ pub fn remove(&mut self, index: usize) -> T { } ``` + + + + # IntoIter Let's move on to writing iterators. `iter` and `iter_mut` have already been @@ -410,7 +433,22 @@ struct IntoIter { } ``` -And initialize it like this: +One last subtle detail: if our Vec is empty, we want to produce an empty iterator. +This will actually technically fall out doing the naive thing of: + +```text +start = ptr +end = ptr.offset(len) +``` + +However because `offset` is marked as a GEP inbounds instruction, this will tell +llVM that ptr is allocated and won't alias other allocated memory. This is fine +for zero-sized types, as they can't alias anything. However if we're using +heap::EMPTY as a sentinel for a non-allocation for a *non-zero-sized* type, +this can cause undefined behaviour. Alas, we must therefore special case either +cap or len being 0 to not do the offset. + +So this is what we end up with for initialization: ```rust impl Vec { @@ -428,7 +466,12 @@ impl Vec { buf: ptr, cap: cap, start: *ptr, - end: ptr.offset(len as isize), + end: if cap == 0 { + // can't offset off this pointer, it's not allocated! + *ptr + } else { + ptr.offset(len as isize) + } } } } @@ -635,6 +678,10 @@ impl Vec { Much better. + + + + # Drain Let's move on to Drain. Drain is largely the same as IntoIter, except that @@ -674,7 +721,11 @@ impl RawValIter { unsafe fn new(slice: &[T]) -> Self { RawValIter { start: slice.as_ptr(), - end: slice.as_ptr().offset(slice.len() as isize), + end: if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } } } } @@ -771,6 +822,8 @@ impl Vec { ``` + + # Handling Zero-Sized Types It's time. We're going to fight the spectre that is zero-sized types. Safe Rust @@ -781,13 +834,14 @@ zero-sized types. We need to be careful of two things: * The raw allocator API has undefined behaviour if you pass in 0 for an allocation size. * raw pointer offsets are no-ops for zero-sized types, which will break our - C-style pointer iterator + C-style pointer iterator. Thankfully we abstracted out pointer-iterators and allocating handling into RawValIter and RawVec respectively. How mysteriously convenient. + ## Allocating Zero-Sized Types So if the allocator API doesn't support zero-sized allocations, what on earth @@ -797,13 +851,457 @@ to be considered to store or load them. This actually extends to `ptr::read` and `ptr::write`: they won't actually look at the pointer at all. As such we *never* need to change the pointer. -TODO +Note however that our previous reliance on running out of memory before overflow is +no longer valid with zero-sized types. We must explicitly guard against capacity +overflow for zero-sized types. + +Due to our current architecture, all this means is writing 3 guards, one in each +method of RawVec. + +```rust +impl RawVec { + fn new() -> Self { + unsafe { + // -1 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { -1 } else { 0 }; + + // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } + } + } + + fn grow(&mut self) { + unsafe { + let elem_size = mem::size_of::(); + + // since we set the capacity to usize::MAX when elem_size is + // 0, getting to here necessarily means the Vec is overfull. + assert!(elem_size != 0, "capacity overflow"); + + let align = mem::min_align_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + +impl Drop for RawVec { + fn drop(&mut self) { + let elem_size = mem::size_of::(); + + // don't free zero-sized allocations, as they were never allocated. + if self.cap != 0 && elem_size != 0 { + let align = mem::min_align_of::(); + + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +That's it. We support pushing and popping zero-sized types now. Our iterators +(that aren't provided by slice Deref) are still busted, though. + + + ## Iterating Zero-Sized Types -TODO +Zero-sized offsets are no-ops. This means that our current design will always +initialize `start` and `end` as the same value, and our iterators will yield +nothing. The current solution to this is to cast the pointers to integers, +increment, and then cast them back: -## Advanced Drain +``` +impl RawValIter { + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if mem::size_of::() == 0 { + ((slice.as_ptr() as usize) + slice.len()) as *const _ + } else if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} +``` + +Now we have a different bug. Instead of our iterators not running at all, our +iterators now run *forever*. We need to do the same trick in our iterator impls: + +``` +impl Iterator for RawValIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = if mem::size_of::() == 0 { + (self.start as usize + 1) as *const _ + } else { + self.start.offset(1); + } + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let len = self.end as usize - self.start as usize; + (len, Some(len)) + } +} + +impl DoubleEndedIterator for RawValIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = if mem::size_of::() == 0 { + (self.end as usize - 1) as *const _ + } else { + self.end.offset(-1); + } + Some(ptr::read(self.end)) + } + } + } +} +``` + +And that's it. Iteration works! + + + +# Advanced Drain TODO? Not clear if informative + + + + +# The Final Code + +```rust +#![feature(unique)] +#![feature(heap_api)] + +use std::ptr::{Unique, self}; +use std::rt::heap; +use std::mem; +use std::ops::{Deref, DerefMut}; +use std::marker::PhantomData; + +struct RawVec { + ptr: Unique, + cap: usize, +} + +impl RawVec { + fn new() -> Self { + unsafe { + // -1 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { -1 } else { 0 }; + + // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } + } + } + + fn grow(&mut self) { + unsafe { + let elem_size = mem::size_of::(); + + // since we set the capacity to usize::MAX when elem_size is + // 0, getting to here necessarily means the Vec is overfull. + assert!(elem_size != 0, "capacity overflow"); + + let align = mem::min_align_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + +impl Drop for RawVec { + fn drop(&mut self) { + let elem_size = mem::size_of::(); + if self.cap != 0 && elem_size != 0 { + let align = mem::min_align_of::(); + + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} + +pub struct Vec { + buf: RawVec, + len: usize, +} + +impl Vec { + fn ptr(&self) -> *mut T { *self.buf.ptr } + + fn cap(&self) -> usize { self.buf.cap } + + pub fn new() -> Self { + Vec { buf: RawVec::new(), len: 0 } + } + pub fn push(&mut self, elem: T) { + if self.len == self.cap() { self.buf.grow(); } + + unsafe { + ptr::write(self.ptr().offset(self.len as isize), elem); + } + + // Can't fail, we'll OOM first. + self.len += 1; + } + + pub fn pop(&mut self) -> Option { + if self.len == 0 { + None + } else { + self.len -= 1; + unsafe { + Some(ptr::read(self.ptr().offset(self.len as isize))) + } + } + } + + pub fn insert(&mut self, index: usize, elem: T) { + assert!(index <= self.len, "index out of bounds"); + if self.cap() == self.len { self.buf.grow(); } + + unsafe { + if index < self.len { + ptr::copy(self.ptr().offset(index as isize), + self.ptr().offset(index as isize + 1), + self.len - index); + } + ptr::write(self.ptr().offset(index as isize), elem); + self.len += 1; + } + } + + pub fn remove(&mut self, index: usize) -> T { + assert!(index < self.len, "index out of bounds"); + unsafe { + self.len -= 1; + let result = ptr::read(self.ptr().offset(index as isize)); + ptr::copy(self.ptr().offset(index as isize + 1), + self.ptr().offset(index as isize), + self.len - index); + result + } + } + + pub fn into_iter(self) -> IntoIter { + unsafe { + let iter = RawValIter::new(&self); + let buf = ptr::read(&self.buf); + mem::forget(self); + + IntoIter { + iter: iter, + _buf: buf, + } + } + } + + pub fn drain(&mut self) -> Drain { + // this is a mem::forget safety thing. If this is forgotten, we just + // leak the whole Vec's contents. Also we need to do this *eventually* + // anyway, so why not do it now? + self.len = 0; + unsafe { + Drain { + iter: RawValIter::new(&self), + vec: PhantomData, + } + } + } +} + +impl Drop for Vec { + fn drop(&mut self) { + while let Some(_) = self.pop() {} + // allocation is handled by RawVec + } +} + +impl Deref for Vec { + type Target = [T]; + fn deref(&self) -> &[T] { + unsafe { + ::std::slice::from_raw_parts(self.ptr(), self.len) + } + } +} + +impl DerefMut for Vec { + fn deref_mut(&mut self) -> &mut [T] { + unsafe { + ::std::slice::from_raw_parts_mut(self.ptr(), self.len) + } + } +} + + + + + +struct RawValIter { + start: *const T, + end: *const T, +} + +impl RawValIter { + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if mem::size_of::() == 0 { + ((slice.as_ptr() as usize) + slice.len()) as *const _ + } else if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} + +impl Iterator for RawValIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = self.start.offset(1); + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let len = self.end as usize - self.start as usize; + (len, Some(len)) + } +} + +impl DoubleEndedIterator for RawValIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = self.end.offset(-1); + Some(ptr::read(self.end)) + } + } + } +} + + + + +pub struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + iter: RawValIter, +} + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { self.iter.next() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl Drop for IntoIter { + fn drop(&mut self) { + for _ in &mut *self {} + } +} + + + + +pub struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec>, + iter: RawValIter, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { self.iter.next_back() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl<'a, T> DoubleEndedIterator for Drain<'a, T> { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl<'a, T> Drop for Drain<'a, T> { + fn drop(&mut self) { + // pre-drain the iter + for _ in &mut self.iter {} + } +} + +/// Abort the process, we're out of memory! +/// +/// In practice this is probably dead code on most OSes +fn oom() { + ::std::process::exit(-1); +} +``` From a9143a8e2a4bdaa5e642f4041677049f046dd65a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 24 Jun 2015 22:49:02 -0700 Subject: [PATCH 026/104] fix vec size_hint --- vec.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/vec.md b/vec.md index a2fecf8238251..9f7250c951af6 100644 --- a/vec.md +++ b/vec.md @@ -496,7 +496,8 @@ impl Iterator for IntoIter { } fn size_hint(&self) -> (usize, Option) { - let len = self.end as usize - self.start as usize; + let len = (self.end as usize - self.start as usize) + / mem::size_of::(); (len, Some(len)) } } @@ -949,7 +950,10 @@ impl RawValIter { ``` Now we have a different bug. Instead of our iterators not running at all, our -iterators now run *forever*. We need to do the same trick in our iterator impls: +iterators now run *forever*. We need to do the same trick in our iterator impls. +Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll +basically be treating the two pointers as if they point to bytes, we'll just +map size 0 to divide by 1. ``` impl Iterator for RawValIter { @@ -971,7 +975,9 @@ impl Iterator for RawValIter { } fn size_hint(&self) -> (usize, Option) { - let len = self.end as usize - self.start as usize; + let elem_size = mem::size_of::(); + let len = (self.end as usize - self.start as usize) + / if elem_size == 0 { 1 } else { elem_size }; (len, Some(len)) } } @@ -1018,6 +1024,10 @@ use std::mem; use std::ops::{Deref, DerefMut}; use std::marker::PhantomData; + + + + struct RawVec { ptr: Unique, cap: usize, @@ -1079,6 +1089,10 @@ impl Drop for RawVec { } } + + + + pub struct Vec { buf: RawVec, len: usize, @@ -1231,7 +1245,9 @@ impl Iterator for RawValIter { } fn size_hint(&self) -> (usize, Option) { - let len = self.end as usize - self.start as usize; + let elem_size = mem::size_of::(); + let len = (self.end as usize - self.start as usize) + / if elem_size == 0 { 1 } else { elem_size }; (len, Some(len)) } } From 8b60fe99ec7d52cf6de435d1414ea968105c11d4 Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Thu, 25 Jun 2015 13:45:52 +0530 Subject: [PATCH 027/104] The Unsafe English Language demands tribute --- vec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vec.md b/vec.md index 9f7250c951af6..31cc70a913910 100644 --- a/vec.md +++ b/vec.md @@ -253,7 +253,7 @@ pub fn pop(&mut self) -> Option { # Deallocating -Next we should implement Drop so that we don't massively leaks tons of resources. +Next we should implement Drop so that we don't massively leak tons of resources. The easiest way is to just call `pop` until it yields None, and then deallocate our buffer. Note that calling `pop` is uneeded if `T: !Drop`. In theory we can ask Rust if T needs_drop and omit the calls to `pop`. However in practice LLVM From 3f6692874fdac72a7d0cbf578ed096ca8d0cbd1d Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Thu, 25 Jun 2015 13:47:04 +0530 Subject: [PATCH 028/104] lowercase level Virtual Machine --- vec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vec.md b/vec.md index 31cc70a913910..fd69e4b262ba3 100644 --- a/vec.md +++ b/vec.md @@ -442,7 +442,7 @@ end = ptr.offset(len) ``` However because `offset` is marked as a GEP inbounds instruction, this will tell -llVM that ptr is allocated and won't alias other allocated memory. This is fine +LLVM that ptr is allocated and won't alias other allocated memory. This is fine for zero-sized types, as they can't alias anything. However if we're using heap::EMPTY as a sentinel for a non-allocation for a *non-zero-sized* type, this can cause undefined behaviour. Alas, we must therefore special case either From 414f7301978b7d84c12bdbd46242daae254e963d Mon Sep 17 00:00:00 2001 From: Manish Goregaokar Date: Thu, 25 Jun 2015 13:53:05 +0530 Subject: [PATCH 029/104] If you prick a code block, does it not bleed? --- vec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vec.md b/vec.md index fd69e4b262ba3..94bc65fcac081 100644 --- a/vec.md +++ b/vec.md @@ -444,7 +444,7 @@ end = ptr.offset(len) However because `offset` is marked as a GEP inbounds instruction, this will tell LLVM that ptr is allocated and won't alias other allocated memory. This is fine for zero-sized types, as they can't alias anything. However if we're using -heap::EMPTY as a sentinel for a non-allocation for a *non-zero-sized* type, +`heap::EMPTY` as a sentinel for a non-allocation for a *non-zero-sized* type, this can cause undefined behaviour. Alas, we must therefore special case either cap or len being 0 to not do the offset. From 0f924555e50bbc9b5e7d408c5230510d4a5bc9de Mon Sep 17 00:00:00 2001 From: Pascal Hertleif Date: Thu, 25 Jun 2015 11:24:14 +0200 Subject: [PATCH 030/104] Fix Typo --- vec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vec.md b/vec.md index 9f7250c951af6..825104d0943a5 100644 --- a/vec.md +++ b/vec.md @@ -1,7 +1,7 @@ % Example: Implementing Vec To bring everything together, we're going to write `std::Vec` from scratch. -Because the all the best tools for writing unsafe code are unstable, this +Because all the best tools for writing unsafe code are unstable, this project will only work on nightly (as of Rust 1.2.0). From 758895718c8883376f9faff883247b8abe937bca Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Thu, 25 Jun 2015 09:46:59 -0700 Subject: [PATCH 031/104] rewrap uninit --- uninitialized.md | 174 ++++++++++++++++++++++++++--------------------- 1 file changed, 98 insertions(+), 76 deletions(-) diff --git a/uninitialized.md b/uninitialized.md index 89d0a93f6385a..88cc7deac4725 100644 --- a/uninitialized.md +++ b/uninitialized.md @@ -1,8 +1,14 @@ % 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. +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: +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() { @@ -17,8 +23,11 @@ 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: +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() { @@ -68,76 +77,88 @@ fn main() { } ``` -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: +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 + let z2 = y; // y is now logically uninitialized because Box isn't 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! +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: @@ -164,16 +185,17 @@ fn main() { } ``` -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. +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. +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. +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. From d2e802b827d5020c89e1d3290fe13602386a4b33 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 26 Jun 2015 09:29:42 -0700 Subject: [PATCH 032/104] tweak usize::MAX --- vec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/vec.md b/vec.md index e45782c45ce97..2b4e35e7653f8 100644 --- a/vec.md +++ b/vec.md @@ -863,8 +863,8 @@ method of RawVec. impl RawVec { fn new() -> Self { unsafe { - // -1 is usize::MAX. This branch should be stripped at compile time. - let cap = if mem::size_of::() == 0 { -1 } else { 0 }; + // !0 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { !0 } else { 0 }; // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } @@ -1036,8 +1036,8 @@ struct RawVec { impl RawVec { fn new() -> Self { unsafe { - // -1 is usize::MAX. This branch should be stripped at compile time. - let cap = if mem::size_of::() == 0 { -1 } else { 0 }; + // !0 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { !0 } else { 0 }; // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } From a1f6bbc67ae532be0f1bfbe7a631ae39c230c717 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 26 Jun 2015 16:52:20 -0700 Subject: [PATCH 033/104] niko fixes --- README.md | 1 - lifetimes.md | 221 +++++++++++++++++++++++++++++---------------------- 2 files changed, 126 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 19fd3f232d3e7..04cfe58b3b0a6 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,6 @@ quite permisive with respect to other dubious operations. Rust considers it * Deadlock * Leak memory * Fail to call destructors -* Access private fields * Overflow integers * Delete the production database diff --git a/lifetimes.md b/lifetimes.md index fe4dc6270e194..48bfcb029913e 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -102,59 +102,11 @@ more than a local lint against incorrect usage of a value. -# Weird Lifetimes - -Given the following code: - -```rust -struct Foo; - -impl Foo { - fn mutate_and_share(&mut self) -> &Self { &*self } - fn share(&self) {} -} - -fn main() { - let mut foo = Foo; - let loan = foo.mutate_and_share(); - foo.share(); -} -``` - -One might expect it to compile. We call `mutate_and_share`, which mutably borrows -`foo` *temporarily*, but then returns *only* a shared reference. Therefore we -would expect `foo.share()` to succeed as `foo` shouldn't be mutably borrowed. - -However when we try to compile it: - -```text -:11:5: 11:8 error: cannot borrow `foo` as immutable because it is also borrowed as mutable -:11 foo.share(); - ^~~ -:10:16: 10:19 note: previous borrow of `foo` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `foo` until the borrow ends -:10 let loan = foo.mutate_and_share(); - ^~~ -:12:2: 12:2 note: previous borrow ends here -:8 fn main() { -:9 let mut foo = Foo; -:10 let loan = foo.mutate_and_share(); -:11 foo.share(); -:12 } - ^ -``` - -What happened? Well, the lifetime of `loan` is derived from a *mutable* borrow. -This makes the type system believe that `foo` is mutably borrowed as long as -`loan` exists, even though it's a shared reference. To my knowledge, this is not -a bug. - - - # Lifetime Elision In order to make common patterns more ergonomic, Rust allows lifetimes to be -*elided* in function, impl, and type signatures. +*elided* in function signatures. A *lifetime position* is anywhere you can write a lifetime in a type: @@ -336,16 +288,18 @@ In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are derive from scopes, we can partially order them based on an *outlives* relationship. We can even express this as a generic bound: `T: 'a` specifies that `T` *outlives* `'a`. -We can then define subtyping on lifetimes in terms of lifetimes: `'a : 'b` implies -`'a <: b` -- if `'a` outlives `'b`, then `'a` is a subtype of `'b`. This is a very +We can then define subtyping on lifetimes in terms of lifetimes: if `'a : 'b` +("a outlives b"), then `'a` is a subtype of `b`. This is a large source of confusion, because a bigger scope is a *sub type* of a smaller scope. This does in fact make sense. The intuitive reason for this is that if you expect an -`&'a u8`, then it's totally fine for me to hand you an `&'static u8`, in the same way +`&'a u8`, then it's totally fine for me to hand you an `&'static u8` in the same way that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. (Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary construct that some disagree with. I just find that it simplifies this analysis.) +TODO: higher rank lifetime subtyping + Variance is where things get really harsh. Variance is a property that *type constructors* have. A type constructor in Rust @@ -356,21 +310,27 @@ take a lifetime and a type. A type constructor's *variance* is how the subtypes of its inputs affects the subtypes of its outputs. There are three kinds of variance: -* F is *covariant* if `T <: U` implies `F <: F` -* F is *contravariant* if `T <: U` implies `F <: F` +* F is *variant* if `T` being a subtype of `U` implies `F` is a subtype of `F` * F is *invariant* otherwise (no subtyping relation can be derived) +(For those of you who are familiar with variance from other languages, what we refer +to as "just" variant is in fact *covariant*. Rust does not have contravariance. +Historically Rust did have some contravariance but it was scrapped due to poor +interactions with other features.) + Some important variances: -* `&` is covariant (as is *const by metaphor) +* `&` is variant (as is *const by metaphor) * `&mut` is invariant (as is *mut by metaphor) -* `Fn(T)` is contravariant with respect to `T` -* `Box`, `Vec`, and all other collections are covariant +* `Fn(T) -> U` is invariant with respect to `T`, but variant with respect to `U` +* `Box`, `Vec`, and all other collections are variant * `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" types are invariant To understand why these variances are correct and desirable, we will consider several -examples. We have already covered why `&` should be covariant. +examples. We have already covered why `&` should be variant when introducing subtyping: +it's desirable to be able to pass longer-lived things where shorter-lived things are +needed. To see why `&mut` should be invariant, consider the following code: @@ -391,28 +351,29 @@ fn overwrite(input: &mut T, new: &mut T) { The signature of `overwrite` is clearly valid: it takes mutable references to two values of the same type, and replaces one with the other. We have seen already that `&` is -covariant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a +variant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a subtype of `&'a str`. Therefore, if `&mut` was -*also* covariant, then the lifetime of the `&'static str` would successfully be +*also* variant, then the lifetime of the `&'static str` would successfully be "shrunk" down to the shorter lifetime of the string, and `replace` would be called successfully. The string would subsequently be dropped, and `forever_str` would point to freed memory when we print it! -Therefore `&mut` should be invariant. This is the general theme of covariance vs -invariance: if covariance would allow you to *store* a short-lived value in a +Therefore `&mut` should be invariant. This is the general theme of variance vs +invariance: if variance would allow you to *store* a short-lived value in a longer-lived slot, then you must be invariant. -`Box` and `Vec` are interesting cases because they're covariant, but you can +`Box` and `Vec` are interesting cases because they're variant, but you can definitely store values in them! This is fine because *you can only store values in them through a mutable reference*! The mutable reference makes the whole type invariant, and therefore prevents you from getting in trouble. -Being covariant allows them to be covariant when shared immutably (so you can pass +Being variant allows them to be variant when shared immutably (so you can pass a `&Box<&'static str>` where a `&Box<&'a str>` is expected). It also allows you to forever weaken the type by moving it into a weaker slot. That is, you can do: ```rust fn get_box<'a>(&'a u8) -> Box<&'a str> { + // string literals are `&'static str`s Box::new("hello") } ``` @@ -424,51 +385,67 @@ The variance of the cell types similarly follows. `&` is like an `&mut` for a cell, because you can still store values in them through an `&`. Therefore cells must be invariant to avoid lifetime smuggling. -`Fn` is the most confusing case, largely because contravariance is easily the -most confusing kind of variance, and basically never comes up. To understand it, -consider a function `len` that takes a function `F`. +`Fn` is the most subtle case, because it has mixed variance. To see why +`Fn(T) -> U` should be invariant over T, consider the following function +signature: ```rust -fn len(func: F) -> usize - where F: Fn(&'static str) -> usize -{ - func("hello") -} +// 'a is derived from some parent scope +fn foo(&'a str) -> usize; ``` -We require that F is a Fn that can take an `&'static str` and returns a usize. Now -say we have a function that can take an `&'a str` (for *some* `'a`). Such a function actually -accepts *more* inputs, since `&'static str` is a subtype of `&'a str`. Therefore -`len` should happily accept such a function! +This signature claims that it can handle any &str that lives *at least* as long +as `'a`. Now if this signature was variant with respect to &str, that would mean + +```rust +fn foo(&'static str) -> usize; +``` -So a `Fn(&'a str)` is a subtype of a `Fn(&'static str)` because -`&'static str` is a subtype of `&'a str`. Exactly contravariance. +could be provided in its place, as it would be a subtype. However this function +has a *stronger* requirement: it says that it can *only* handle `&'static str`s, +and nothing else. Therefore functions are not variant over their arguments. -The variance of `*const` and `*mut` is basically arbitrary as they're not at all -type or memory safe, so their variance is determined in analogy to & and &mut -respectively. +To see why `Fn(T) -> U` should be *variant* over U, consider the following +function signature: + +```rust +// 'a is derived from some parent scope +fn foo(usize) -> &'a str; +``` + +This signature claims that it will return something that outlives `'a`. It is +therefore completely reasonable to provide + +```rust +fn foo(usize) -> &'static str; +``` + +in its place. Therefore functions *are* variant over their return type. + +`*const` has the exact same semantics as &, so variance follows. `*mut` on the +other hand can dereference to an &mut whether shared or not, so it is marked +as invariant in analogy to cells. This is all well and good for the types the standard library provides, but -how is variance determined for type that *you* define? A struct informally -speaking inherits the variance of its fields. If a struct `Foo` +how is variance determined for type that *you* define? A struct, informally +speaking, inherits the variance of its fields. If a struct `Foo` has a generic argument `A` that is used in a field `a`, then Foo's variance over `A` is exactly `a`'s variance. However this is complicated if `A` is used in multiple fields. -* If all uses of A are covariant, then Foo is covariant over A -* If all uses of A are contravariant, then Foo is contravariant over A +* If all uses of A are variant, then Foo is variant over A * Otherwise, Foo is invariant over A ```rust struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { - a: &'a A, // covariant over 'a and A + a: &'a A, // variant over 'a and A b: &'b mut B, // invariant over 'b and B - c: *const C, // covariant over C + c: *const C, // variant over C d: *mut D, // invariant over D - e: Vec, // covariant over E + e: Vec, // variant over E f: Cell, // invariant over F - g: G // covariant over G - h1: H // would also be covariant over H except... + g: G // variant over G + h1: H // would also be variant over H except... h2: Cell // invariant over H, because invariance wins } ``` @@ -497,8 +474,9 @@ correct variance and drop checking. We do this using *PhantomData*, which is a special marker type. PhantomData consumes no space, but simulates a field of the given type for the purpose of -variance. This was deemed to be less error-prone than explicitly telling the -type-system the kind of variance that you want. +static analysis. This was deemed to be less error-prone than explicitly telling +the type-system the kind of variance that you want, while also providing other +useful information. Iter logically contains `&'a T`, so this is exactly what we tell the PhantomData to simulate: @@ -526,16 +504,16 @@ However the one exception is with PhantomData. Given a struct like Vec: ``` struct Vec { - data: *const T, // *const for covariance! + data: *const T, // *const for variance! len: usize, cap: usize, } ``` -dropck will generously determine that Vec does not contain any values of +dropck will generously determine that Vec does not own any values of type T. This will unfortunately allow people to construct unsound Drop implementations that access data that has already been dropped. In order to -tell dropck that we *do* own values of type T and may call destructors of that +tell dropck that we *do* own values of type T, and may call destructors of that type, we must add extra PhantomData: ``` @@ -700,3 +678,56 @@ Bar is *also* live. Since IterMut is always live when `next` can be called, if to it exist! + + + +# Weird Lifetimes + +Given the following code: + +```rust +struct Foo; + +impl Foo { + fn mutate_and_share(&mut self) -> &Self { &*self } + fn share(&self) {} +} + +fn main() { + let mut foo = Foo; + let loan = foo.mutate_and_share(); + foo.share(); +} +``` + +One might expect it to compile. We call `mutate_and_share`, which mutably borrows +`foo` *temporarily*, but then returns *only* a shared reference. Therefore we +would expect `foo.share()` to succeed as `foo` shouldn't be mutably borrowed. + +However when we try to compile it: + +```text +:11:5: 11:8 error: cannot borrow `foo` as immutable because it is also borrowed as mutable +:11 foo.share(); + ^~~ +:10:16: 10:19 note: previous borrow of `foo` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `foo` until the borrow ends +:10 let loan = foo.mutate_and_share(); + ^~~ +:12:2: 12:2 note: previous borrow ends here +:8 fn main() { +:9 let mut foo = Foo; +:10 let loan = foo.mutate_and_share(); +:11 foo.share(); +:12 } + ^ +``` + +What happened? Well, the lifetime of `loan` is derived from a *mutable* borrow. +This makes the type system believe that `foo` is mutably borrowed as long as +`loan` exists, even though it's a shared reference. This isn't a bug, although +one could argue it is a limitation of the design. In particular, to know if +the mutable part of the borrow is *really* expired we'd have to peek into +implementation details of the function. Currently, type-checking a function +does not need to inspect the bodies of any other functions or types. + + From 65a0c1753e7eaa2ee1a77a4591d328afc85766be Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 11:35:09 -0700 Subject: [PATCH 034/104] poke at data and conversions more --- conversions.md | 186 +++++++++++++++++-------------------------------- data.md | 56 +++++++++------ 2 files changed, 100 insertions(+), 142 deletions(-) diff --git a/conversions.md b/conversions.md index b35409553f740..ad5d240f2a741 100644 --- a/conversions.md +++ b/conversions.md @@ -32,21 +32,6 @@ more ergonomic alternatives. -# Auto-Deref - -(Maybe nix this in favour of receiver coercions) - -Deref is a trait that allows you to overload the unary `*` to specify a type -you dereference to. This is largely only intended to be implemented by pointer -types like `&`, `Box`, and `Rc`. The dot operator will automatically perform -automatic dereferencing, so that foo.bar() will work uniformly on `Foo`, `&Foo`, ` -&&Foo`, `&Rc>>` and so-on. Search bottoms out on the *first* match, -so implementing methods on pointers is generally to be avoided, as it will shadow -"actual" methods. - - - - # Coercions Types can implicitly be coerced to change in certain contexts. These changes are @@ -58,88 +43,42 @@ Here's all the kinds of coercion: Coercion is allowed between the following types: -* `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) - of `U` (the 'identity' case); - -* `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` - (transitivity case); - -* `&mut T` to `&T`; - -* `*mut T` to `*const T`; - -* `&T` to `*const T`; - -* `&mut T` to `*mut T`; - -* `T` to `U` if `T` implements `CoerceUnsized` (see below) and `T = Foo<...>` - and `U = Foo<...>`; - -* From TyCtor(`T`) to TyCtor(coerce_inner(`T`)); - -where TyCtor(`T`) is one of `&T`, `&mut T`, `*const T`, `*mut T`, or `Box`. -And where coerce_inner is defined as - -* coerce_inner(`[T, ..n]`) = `[T]`; - -* coerce_inner(`T`) = `U` where `T` is a concrete type which implements the - trait `U`; - -* coerce_inner(`T`) = `U` where `T` is a sub-trait of `U`; - -* coerce_inner(`Foo<..., T, ...>`) = `Foo<..., coerce_inner(T), ...>` where - `Foo` is a struct and only the last field has type `T` and `T` is not part of - the type of any other fields; - -* coerce_inner(`(..., T)`) = `(..., coerce_inner(T))`. - -Coercions only occur at a *coercion site*. Exhaustively, the coercion sites -are: - -* In `let` statements where an explicit type is given: in `let _: U = e;`, `e` - is coerced to to have type `U`; - -* In statics and consts, similarly to `let` statements; - -* In argument position for function calls. The value being coerced is the actual - parameter and it is coerced to the type of the formal parameter. For example, - where `foo` is defined as `fn foo(x: U) { ... }` and is called with `foo(e);`, - `e` is coerced to have type `U`; - -* Where a field of a struct or variant is instantiated. E.g., where `struct Foo - { x: U }` and the instantiation is `Foo { x: e }`, `e` is coerced to to have - type `U`; - -* The result of a function, either the final line of a block if it is not semi- - colon terminated or any expression in a `return` statement. For example, for - `fn foo() -> U { e }`, `e` is coerced to to have type `U`; - -If the expression in one of these coercion sites is a coercion-propagating -expression, then the relevant sub-expressions in that expression are also -coercion sites. Propagation recurses from these new coercion sites. Propagating -expressions and their relevant sub-expressions are: - -* array literals, where the array has type `[U, ..n]`, each sub-expression in - the array literal is a coercion site for coercion to type `U`; - -* array literals with repeating syntax, where the array has type `[U, ..n]`, the - repeated sub-expression is a coercion site for coercion to type `U`; - -* tuples, where a tuple is a coercion site to type `(U_0, U_1, ..., U_n)`, each - sub-expression is a coercion site for the respective type, e.g., the zero-th - sub-expression is a coercion site to `U_0`; - -* the box expression, if the expression has type `Box`, the sub-expression is - a coercion site to `U`; - -* parenthesised sub-expressions (`(e)`), if the expression has type `U`, then - the sub-expression is a coercion site to `U`; - -* blocks, if a block has type `U`, then the last expression in the block (if it - is not semicolon-terminated) is a coercion site to `U`. This includes blocks - which are part of control flow statements, such as `if`/`else`, if the block - has a known type. - +* Subtyping: `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) + of `U` +* Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` +* Pointer Weakening: + * `&mut T` to `&T` + * `*mut T` to `*const T` + * `&T` to `*const T` + * `&mut T` to `*mut T` +* Unsizing: `T` to `U` if `T` implements `CoerceUnsized` + +`CoerceUnsized> for Pointer` where T: Unsize is implemented +for all pointer types (including smart pointers like Box and Rc). Unsize is +only implemented automatically, and enables the following transformations: + +* `[T, ..n]` => `[T]` +* `T` => `Trait` where `T: Trait` +* `SubTrait` => `Trait` where `SubTrait: Trait` (TODO: is this now implied by the previous?) +* `Foo<..., T, ...>` => `Foo<..., U, ...>` where: + * T: Unsize + * `Foo` is a struct + * Only the last field has type `T` + * `T` is not part of the type of any other fields + (note that this also applies to to tuples as an anonymous struct `Tuple3`) + +Coercions occur at a *coercion site*. Any location that is explicitly typed +will cause a coercion to its type. If inference is necessary, the coercion will +not be performed. Exhaustively, the coercion sites for an expression `e` to +type `U` are: + +* let statements, statics, and consts: `let x: U = e` +* Arguments to functions: `takes_a_U(e)` +* Any expression that will be returned: `fn foo() -> U { e }` +* Struct literals: `Foo { some_u: e }` +* Array literals: `let x: [U; 10] = [e, ..]` +* Tuple literals: `let x: (U, ..) = (e, ..)` +* The last expression in a block: `let x: U = { ..; e }` Note that we do not perform coercions when matching traits (except for receivers, see below). If there is an impl for some type `U` and `T` coerces to @@ -147,29 +86,32 @@ receivers, see below). If there is an impl for some type `U` and `T` coerces to following will not type check, even though it is OK to coerce `t` to `&T` and there is an impl for `&T`: -``` -struct T; +```rust trait Trait {} fn foo(t: X) {} -impl<'a> Trait for &'a T {} +impl<'a> Trait for &'a i32 {} fn main() { - let t: &mut T = &mut T; - foo(t); //~ ERROR failed to find an implementation of trait Trait for &mut T + let t: &mut i32 = &mut 0; + foo(t); } ``` -In a cast expression, `e as U`, the compiler will first attempt to coerce `e` to -`U`, only if that fails will the conversion rules for casts (see below) be -applied. - +```text +:10:5: 10:8 error: the trait `Trait` is not implemented for the type `&mut i32` [E0277] +:10 foo(t); + ^~~ +``` +# The Dot Operator -TODO: receiver coercions? +The dot operator will perform a lot of magic to convert types. It will perform +auto-referencing, auto-dereferencing, and coercion until types match. +TODO: steal information from http://stackoverflow.com/questions/28519997/what-are-rusts-exact-auto-dereferencing-rules/28552082#28552082 # Casts @@ -178,21 +120,21 @@ cast, but some conversions *require* a cast. These "true casts" are generally re as dangerous or problematic actions. True casts revolve around raw pointers and the primitive numeric types. True casts aren't checked. -Here's an exhaustive list of all the true casts: - - * `e` has type `T` and `T` coerces to `U`; *coercion-cast* - * `e` has type `*T`, `U` is `*U_0`, and either `U_0: Sized` or - unsize_kind(`T`) = unsize_kind(`U_0`); *ptr-ptr-cast* - * `e` has type `*T` and `U` is a numeric type, while `T: Sized`; *ptr-addr-cast* - * `e` is an integer and `U` is `*U_0`, while `U_0: Sized`; *addr-ptr-cast* - * `e` has type `T` and `T` and `U` are any numeric types; *numeric-cast* - * `e` is a C-like enum and `U` is an integer type; *enum-cast* - * `e` has type `bool` or `char` and `U` is an integer; *prim-int-cast* - * `e` has type `u8` and `U` is `char`; *u8-char-cast* - * `e` has type `&[T; n]` and `U` is `*const T`; *array-ptr-cast* - * `e` is a function pointer type and `U` has type `*T`, - while `T: Sized`; *fptr-ptr-cast* - * `e` is a function pointer type and `U` is an integer; *fptr-addr-cast* +Here's an exhaustive list of all the true casts. For brevity, we will use `*` +to denote either a `*const` or `*mut`, and `integer` to denote any integral primitive: + + * `*T as *U` where `T, U: Sized` + * `*T as *U` TODO: explain unsized situation + * `*T as integer` + * `integer as *T` + * `number as number` + * `C-like-enum as integer` + * `bool as integer` + * `char as integer` + * `u8 as char` + * `&[T; n] as *const T` + * `fn as *T` where `T: Sized` + * `fn as integer` where `&.T` and `*T` are references of either mutability, and where unsize_kind(`T`) is the kind of the unsize info diff --git a/data.md b/data.md index f9163caa4e003..d5259c1348a02 100644 --- a/data.md +++ b/data.md @@ -7,7 +7,7 @@ represented in Rust. -# The rust repr +# The Rust repr Rust gives you the following ways to lay out composite data: @@ -16,12 +16,14 @@ Rust gives you the following ways to lay out composite data: * arrays (homogeneous product types) * enums (named sum types -- tagged unions) -For all these, individual fields are aligned to their preferred alignment. -For primitives this is equal to -their size. For instance, a u32 will be aligned to a multiple of 32 bits, and a u16 will -be aligned to a multiple of 16 bits. Composite structures will have their size rounded -up to be a multiple of the highest alignment required by their fields, and an alignment -requirement equal to the highest alignment required by their fields. So for instance, +An enum is said to be *C-like* if none of its variants have associated data. + +For all these, individual fields are aligned to their preferred alignment. For +primitives this is usually equal to their size. For instance, a u32 will be +aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 +bits. Composite structures will have their size rounded up to be a multiple of +the highest alignment required by their fields, and an alignment requirement +equal to the highest alignment required by their fields. So for instance, ```rust struct A { @@ -127,6 +129,9 @@ In principle enums can use fairly elaborate algorithms to cache bits throughout with special constrained representations. As such it is *especially* desirable that we leave enum layout unspecified today. + + + # Dynamically Sized Types (DSTs) Rust also supports types without a statically known size. On the surface, @@ -219,15 +224,14 @@ struct Foo { ``` For details as to *why* this is done, and how to make it not happen, check out -[SOME OTHER SECTION]. +[TODO: SOME OTHER SECTION]. # Alternative representations -Rust allows you to specify alternative data layout strategies from the default Rust -one. +Rust allows you to specify alternative data layout strategies from the default. @@ -241,32 +245,44 @@ to soundly do more elaborate tricks with data layout such as reintepretting valu as a different type. However, the interaction with Rust's more exotic data layout features must be kept -in mind. Due to its dual purpose as a "for FFI" and "for layout control", repr(C) +in mind. Due to its dual purpose as "for FFI" and "for layout control", `repr(C)` can be applied to types that will be nonsensical or problematic if passed through the FFI boundary. * ZSTs are still zero-sized, even though this is not a standard behaviour -in C, and is explicitly contrary to the behaviour of an empty type in C++, which -still consumes a byte of space. + in C, and is explicitly contrary to the behaviour of an empty type in C++, which + still consumes a byte of space. -* DSTs are not a concept in C +* DSTs, tuples, and tagged unions are not a concept in C and as such are never + FFI safe. * **The drop flag will still be added** -* This is equivalent to repr(u32) for enums (see below) +* This is equivalent to `repr(u32)` for enums (see below) ## repr(packed) -`repr(packed)` forces rust to strip any padding it would normally apply. -This may improve the memory footprint of a type, but will have negative -side-effects from "field access is heavily penalized" to "completely breaks -everything" based on target platform. +`repr(packed)` forces rust to strip any padding, and only align the type to a +byte. This may improve the memory footprint, but will likely have other +negative side-effects. + +In particular, most architectures *strongly* prefer values to be aligned. This +may mean the unaligned loads are penalized (x86), or even fault (ARM). In +particular, the compiler may have trouble with references to unaligned fields. + +`repr(packed)` is not to be used lightly. Unless you have extreme requirements, +this should not be used. +This repr is a modifier on `repr(C)` and `repr(rust)`. ## repr(u8), repr(u16), repr(u32), repr(u64) -These specify the size to make a c-like enum (one which has no values in its variants). +These specify the size to make a C-like enum. If the discriminant overflows the +integer it has to fit in, it will be an error. You can manually ask Rust to +allow this by setting the overflowing element to explicitly be 0. However Rust +will not allow you to create an enum where two variants. +These reprs have no affect on struct or non-C-like enum. From 9c6a46b0eee9f991a7ae6e72164550f781654c66 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 15:43:51 -0700 Subject: [PATCH 035/104] fiddlin' --- README.md | 7 ++++++- data.md | 51 ++++++++++++++++++++++++++++++--------------------- 2 files changed, 36 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 04cfe58b3b0a6..b86f6209f35af 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,14 @@ % The Unsafe Rust Programming Language +# NOTE: This is a draft document, and may contain serious errors + **This document is about advanced functionality and low-level development practices in the Rust Programming Language. Most of the things discussed won't matter to the average Rust programmer. However if you wish to correctly write unsafe code in Rust, this text contains invaluable information.** -This document seeks to complement [The Rust Programming Language Book][trpl] (TRPL). +The Unsafe Rust Programming Language (TURPL) seeks to complement +[The Rust Programming Language Book][trpl] (TRPL). Where TRPL introduces the language and teaches the basics, TURPL dives deep into the specification of the language, and all the nasty bits necessary to write Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know @@ -13,6 +16,8 @@ the basics of the language and systems programming. We will not explain the stack or heap, we will not explain the syntax. + + # A Tale Of Two Languages Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. diff --git a/data.md b/data.md index d5259c1348a02..599415bfe4b95 100644 --- a/data.md +++ b/data.md @@ -21,23 +21,25 @@ An enum is said to be *C-like* if none of its variants have associated data. For all these, individual fields are aligned to their preferred alignment. For primitives this is usually equal to their size. For instance, a u32 will be aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 -bits. Composite structures will have their size rounded up to be a multiple of -the highest alignment required by their fields, and an alignment requirement -equal to the highest alignment required by their fields. So for instance, +bits. Composite structures will have a preferred alignment equal to the maximum +of their fields' preferred alignment, and a size equal to a multiple of their +preferred alignment. This ensures that arrays of T can be correctly iterated +by offsetting by their size. So for instance, ```rust struct A { a: u8, - c: u64, - b: u32, + c: u32, + b: u16, } ``` -will have a size that is a multiple of 64-bits, and 64-bit alignment. +will have a size that is a multiple of 32-bits, and 32-bit alignment. There is *no indirection* for these types; all data is stored contiguously as you would -expect in C. However with the exception of arrays, the layout of data is not by -default specified in Rust. Given the two following struct definitions: +expect in C. However with the exception of arrays (which are densely packed and +in-order), the layout of data is not by default specified in Rust. Given the two +following struct definitions: ```rust struct A { @@ -91,9 +93,9 @@ struct Foo { ``` The latter case quite simply wastes space. An optimal use of space therefore requires -different monomorphizations to *have different field orderings*. +different monomorphizations to have *different field orderings*. -**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0.0** +**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0** Enums make this consideration even more complicated. Naively, an enum such as: @@ -120,14 +122,15 @@ such a representation is ineffiecient. The classic case of this is Rust's "null pointer optimization". Given a pointer that is known to not be null (e.g. `&u32`), an enum can *store* a discriminant bit *inside* the pointer by using null as a special value. The net result is that -`sizeof(Option<&T>) == sizeof<&T>` +`size_of::>() == size_of::<&T>()` -There are many types in Rust that are, or contain, "not null" pointers such as `Box`, `Vec`, -`String`, `&T`, and `&mut T`. Similarly, one can imagine nested enums pooling their tags into -a single descriminant, as they are by definition known to have a limited range of valid values. -In principle enums can use fairly elaborate algorithms to cache bits throughout nested types -with special constrained representations. As such it is *especially* desirable that we leave -enum layout unspecified today. +There are many types in Rust that are, or contain, "not null" pointers such as +`Box`, `Vec`, `String`, `&T`, and `&mut T`. Similarly, one can imagine +nested enums pooling their tags into a single descriminant, as they are by +definition known to have a limited range of valid values. In principle enums can +use fairly elaborate algorithms to cache bits throughout nested types with +special constrained representations. As such it is *especially* desirable that +we leave enum layout unspecified today. @@ -135,8 +138,8 @@ enum layout unspecified today. # Dynamically Sized Types (DSTs) Rust also supports types without a statically known size. On the surface, -this is a bit nonsensical: Rust must know the size of something in order to -work with it. DSTs are generally produced as views, or through type-erasure +this is a bit nonsensical: Rust *must* know the size of something in order to +work with it! DSTs are generally produced as views, or through type-erasure of types that *do* have a known size. Due to their lack of a statically known size, these types can only exist *behind* some kind of pointer. They consequently produce a *fat* pointer consisting of the pointer and the information that @@ -144,7 +147,7 @@ produce a *fat* pointer consisting of the pointer and the information that For instance, the slice type, `[T]`, is some statically unknown number of elements stored contiguously. `&[T]` consequently consists of a `(&T, usize)` pair that specifies -where the slice starts, and how many elements it contains. Similarly Trait Objects +where the slice starts, and how many elements it contains. Similarly, Trait Objects support interface-oriented type erasure through a `(data_ptr, vtable_ptr)` pair. Structs can actually store a single DST directly as their last field, but this @@ -158,6 +161,8 @@ struct Foo { } ``` +**NOTE: As of Rust 1.0 struct DSTs are broken if the last field has +a variable position based on its alignment.** @@ -235,6 +240,7 @@ Rust allows you to specify alternative data layout strategies from the default. + ## repr(C) This is the most important `repr`. It has fairly simple intent: do what C does. @@ -262,6 +268,7 @@ the FFI boundary. + ## repr(packed) `repr(packed)` forces rust to strip any padding, and only align the type to a @@ -278,6 +285,8 @@ this should not be used. This repr is a modifier on `repr(C)` and `repr(rust)`. + + ## repr(u8), repr(u16), repr(u32), repr(u64) These specify the size to make a C-like enum. If the discriminant overflows the @@ -285,4 +294,4 @@ integer it has to fit in, it will be an error. You can manually ask Rust to allow this by setting the overflowing element to explicitly be 0. However Rust will not allow you to create an enum where two variants. -These reprs have no affect on struct or non-C-like enum. +These reprs have no affect on a struct or non-C-like enum. From 10af239aad8024f1eed093947b8516ecf873d735 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 17:13:15 -0700 Subject: [PATCH 036/104] unwinding start --- raii.md | 34 +++++++++------------- unwinding.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 20 deletions(-) create mode 100644 unwinding.md diff --git a/raii.md b/raii.md index 679c1dd3d5993..f85562bd809bb 100644 --- a/raii.md +++ b/raii.md @@ -1,6 +1,6 @@ % The Perils Of RAII -Ownership Based Resource Management (AKA RAII: Resource Acquisition is Initialization) is +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 @@ -38,10 +38,8 @@ 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 implicitly initialized (see [working with uninitialized memory][uninit] for details). -Default is basically only useful for generic programming. - -In concrete contexts, a type will provide a static `new` method for any +[aren't implicitly initialized][uninit]. Default is basically only useful for generic +programming. In concrete contexts, 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. @@ -59,20 +57,16 @@ 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 +Rust will recursively try to drop all of the fields of `self`**. This is a convenience feature so that you don't have to write "destructor boilerplate" to drop children. If a struct has no special logic for being dropped other than dropping its children, then it means `Drop` doesn't need to be implemented at all! -**There is no way to prevent this behaviour in Rust 1.0**. +**There is no stable way to prevent this behaviour in Rust 1.0**. Note that taking `&mut self` means that even if you *could* suppress 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 (they don't contain pointers to elsewhere). -* There's no additional state passed into drop to try to send things. -* `self` is about to be marked as uninitialized (and therefore inaccessible). +is totally fine. For instance, a custom implementation of `Box` might write `Drop` like this: @@ -120,7 +114,7 @@ impl Drop for SuperBox { } ``` -because after we deallocate the `box`'s ptr in SuperBox's destructor, Rust will +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. @@ -216,7 +210,7 @@ refers to it. The collection will sit around uselessly, holding on to its precious resources until the program terminates (at which point all those resources would have been reclaimed by the OS anyway). -We may consider a more restricted form of leak: failing to free memory that +We may consider a more restricted form of leak: failing to drop a value that is unreachable. Rust also doesn't prevent this. In fact Rust has a *function for doing this*: `mem::forget`. This function consumes the value it is passed *and then doesn't run its destructor*. @@ -232,18 +226,18 @@ It is reasonable for safe code to assume that destructor leaks do not happen, as any program that leaks destructors is probably wrong. However *unsafe* code cannot rely on destructors to be run to be *safe*. For most types this doesn't matter: if you leak the destructor then the type is *by definition* inaccessible, -so it doesn't matter, right? e.g. if you leak a `Box` then you waste some -memory but that's hardly going to violate memory-safety. +so it doesn't matter, right? For instance, if you leak a `Box` then you +waste some memory but that's hardly going to violate memory-safety. However where we must be careful with destructor leaks are *proxy* types. These are types which manage access to a distinct object, but don't actually own it. Proxy objects are quite rare. Proxy objects you'll need to care about -are even rarer. However we'll focus on two interesting examples in the +are even rarer. However we'll focus on three interesting examples in the standard library: * `vec::Drain` * `Rc` - +* `thread::scoped::JoinGuard` @@ -251,7 +245,7 @@ standard library: `drain` is a collections API that moves data out of the container without consuming the container. This enables us to reuse the allocation of a `Vec` -after claiming ownership over all of its contents. drain produces an iterator +after claiming ownership over all of its contents. It produces an iterator (Drain) that returns the contents of the Vec by-value. Now, consider Drain in the middle of iteration: some values have been moved out, @@ -376,7 +370,7 @@ in memory. -## thread::scoped +## thread::scoped::JoinGuard The thread::scoped API intends to allow threads to be spawned that reference data on the stack without any synchronization over that data. Usage looked like: diff --git a/unwinding.md b/unwinding.md new file mode 100644 index 0000000000000..cd9ca58304d35 --- /dev/null +++ b/unwinding.md @@ -0,0 +1,82 @@ +% Unwinding + +Rust has a *tiered* error-handling scheme: + +* If something might reasonably be absent, Option is used +* If something goes wrong and can reasonably be handled, Result is used +* If something goes wrong and cannot reasonably be handled, the thread panics +* If something catastrophic happens, the program aborts + +Option and Result are overwhelmingly preferred in most situations, especially +since they can be promoted into a panic or abort at the API user's discretion. +However, anything and everything *can* panic, and you need to be ready for this. +Panics cause the thread to halt normal execution and unwind its stack, calling +destructors as if every function instantly returned. + +As of 1.0, Rust is of two minds when it comes to panics. In the long-long-ago, +Rust was much more like Erlang. Like Erlang, Rust had lightweight tasks, +and tasks were intended to kill themselves with a panic when they reached an +untenable state. Unlike an exception in Java or C++, a panic could not be +caught at any time. Panics could only be caught by the owner of the task, at which +point they had to be handled or *that* task would itself panic. + +Unwinding was important to this story because if a task's +destructors weren't called, it would cause memory and other system resources to +leak. Since tasks were expected to die during normal execution, this would make +Rust very poor for long-running systems! + +As the Rust we know today came to be, this style of programming grew out of +fashion in the push for less-and-less abstraction. Light-weight tasks were +killed in the name of heavy-weight OS threads. Still, panics could only be +caught by the parent thread. This meant catching a panic required spinning up +an entire OS thread! Although Rust maintains the philosophy that panics should +not be used for "basic" error-handling like C++ or Java, it is still desirable +to not have the entire program crash in the face of a panic. + +In the near future there will be a stable interface for catching panics in an +arbitrary location, though we would encourage you to still only do this +sparingly. In particular, Rust's current unwinding implementation is heavily +optimized for the "doesn't unwind" case. If a program doesn't unwind, there +should be no runtime cost for the program being *ready* to unwind. As a +consequence, *actually* unwinding will be more expensive than in e.g. Java. +Don't build your programs to unwind under normal circumstances. Ideally, you +should only panic for programming errors. + + + + +# Exception Safety + +Being ready for unwinding is often referred to as "exception safety" +in the broader programming world. In Rust, their are two levels of exception +safety that one may concern themselves with: + +* In unsafe code, we *must* be exception safe to the point of not violating + memory safety. + +* In safe code, it is *good* to be exception safe to the point of your program + doing the right thing. + +As is the case in many places in Rust, unsafe code must be ready to deal with +bad safe code, and that includes code that panics. Code that transiently creates +unsound states must be careful that a panic does not cause that state to be +used. Generally this means ensuring that only non-panicing code is run while +these states exist, or making a guard that cleans up the state in the case of +a panic. This does not necessarily mean that the state a panic witnesses is a +fully *coherent* state. We need only guarantee that it's a *safe* state. + +For instance, consider extending a Vec: + +```rust + +impl Extend for Vec { + fn extend>(&mut self, iterable: I) { + let mut iter = iterable.into_iter(); + let size_hint = iter.size_hint().0; + self.reserve(size_hint); + self.set_len(self.len() + size_hint()); + + for + } +} + From 5d4f854b4acf01c9e0355eccb779d90c75313ad1 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 21:42:27 -0700 Subject: [PATCH 037/104] so much unwinding --- unwinding.md | 244 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 228 insertions(+), 16 deletions(-) diff --git a/unwinding.md b/unwinding.md index cd9ca58304d35..925f304236623 100644 --- a/unwinding.md +++ b/unwinding.md @@ -28,10 +28,9 @@ Rust very poor for long-running systems! As the Rust we know today came to be, this style of programming grew out of fashion in the push for less-and-less abstraction. Light-weight tasks were killed in the name of heavy-weight OS threads. Still, panics could only be -caught by the parent thread. This meant catching a panic required spinning up -an entire OS thread! Although Rust maintains the philosophy that panics should -not be used for "basic" error-handling like C++ or Java, it is still desirable -to not have the entire program crash in the face of a panic. +caught by the parent thread. This means catching a panic requires spinning up +an entire OS thread! This unfortunately stands in conflict to Rust's philosophy +of zero-cost abstractions. In the near future there will be a stable interface for catching panics in an arbitrary location, though we would encourage you to still only do this @@ -40,14 +39,14 @@ optimized for the "doesn't unwind" case. If a program doesn't unwind, there should be no runtime cost for the program being *ready* to unwind. As a consequence, *actually* unwinding will be more expensive than in e.g. Java. Don't build your programs to unwind under normal circumstances. Ideally, you -should only panic for programming errors. +should only panic for programming errors or *extreme* problems. # Exception Safety -Being ready for unwinding is often referred to as "exception safety" +Being ready for unwinding is often referred to as *exception safety* in the broader programming world. In Rust, their are two levels of exception safety that one may concern themselves with: @@ -60,23 +59,236 @@ safety that one may concern themselves with: As is the case in many places in Rust, unsafe code must be ready to deal with bad safe code, and that includes code that panics. Code that transiently creates unsound states must be careful that a panic does not cause that state to be -used. Generally this means ensuring that only non-panicing code is run while +used. Generally this means ensuring that only non-panicking code is run while these states exist, or making a guard that cleans up the state in the case of a panic. This does not necessarily mean that the state a panic witnesses is a fully *coherent* state. We need only guarantee that it's a *safe* state. -For instance, consider extending a Vec: +Most unsafe code is leaf-like, and therefore fairly easy to make exception-safe. +It controls all the code that runs, and most of that code can't panic. However +it is often the case that code that works with arrays works with temporarily +uninitialized data while repeatedly invoking caller-provided code. Such code +needs to be careful, and consider exception-safety. + + + + + +## Vec::push_all + +`Vec::push_all` is a temporary hack to get extending a Vec by a slice reliably +effecient without specialization. Here's a simple implementation: + +```rust,ignore +impl Vec { + fn push_all(&mut self, to_push: &[T]) { + self.reserve(to_push.len()); + unsafe { + // can't overflow because we just reserved this + self.set_len(self.len() + to_push.len()); + + for (i, x) in to_push.iter().enumerate() { + self.ptr().offset(i as isize).write(x.clone()); + } + } + } +} +``` + +We bypass `push` in order to avoid redundant capacity and `len` checks on the +Vec that we definitely know has capacity. The logic is totally correct, except +there's a subtle problem with our code: it's not exception-safe! `set_len`, +`offset`, and `write` are all fine, but *clone* is the panic bomb we over-looked. + +Clone is completely out of our control, and is totally free to panic. If it does, +our function will exit early with the length of the Vec set too large. If +the Vec is looked at or dropped, uninitialized memory will be read! + +The fix in this case is fairly simple. If we want to guarantee that the values +we *did* clone are dropped we can set the len *in* the loop. If we just want to +guarantee that uninitialized memory can't be observed, we can set the len *after* +the loop. + + + + + +## BinaryHeap::sift_up + +Bubbling an element up a heap is a bit more complicated than extending a Vec. +The pseudocode is as follows: + +```text +bubble_up(heap, index): + while index != 0 && heap[index] < heap[parent(index)]: + heap.swap(index, parent(index)) + index = parent(index) + +``` + +A literal transcription of this code to Rust is totally fine, but has an annoying +performance characteristic: the `self` element is swapped over and over again +uselessly. We would *rather* have the following: + +```text +bubble_up(heap, index): + let elem = heap[index] + while index != 0 && element < heap[parent(index)]: + heap[index] = heap[parent(index)] + index = parent(index) + heap[index] = elem +``` + +This code ensures that each element is copied as little as possible (it is in +fact necessary that elem be copied twice in general). However it now exposes +some exception-safety trouble! At all times, there exists two copies of one +value. If we panic in this function something will be double-dropped. +Unfortunately, we also don't have full control of the code: that comparison is +user-defined! + +Unlike Vec, the fix isn't as easy here. One option is to break the user-defined +code and the unsafe code into two separate phases: + +```text +bubble_up(heap, index): + let end_index = index; + while end_index != 0 && heap[end_index] < heap[parent(end_index)]: + end_index = parent(end_index) + + let elem = heap[index] + while index != end_index: + heap[index] = heap[parent(index)] + index = parent(index) + heap[index] = elem +``` + +If the user-defined code blows up, that's no problem anymore, because we haven't +actually touched the state of the heap yet. Once we do start messing with the +heap, we're working with only data and functions that we trust, so there's no +concern of panics. + +Perhaps you're not happy with this design. Surely, it's cheating! And we have +to do the complex heap traversal *twice*! Alright, let's bite the bullet. Let's +intermix untrusted and unsafe code *for reals*. + +If Rust had `try` and `finally` like in Java, we could do the following: + +```text +bubble_up(heap, index): + let elem = heap[index] + try: + while index != 0 && element < heap[parent(index)]: + heap[index] = heap[parent(index)] + index = parent(index) + finally: + heap[index] = elem +``` + +The basic idea is simple: if the comparison panics, we just toss the loose +element in the logically uninitialized index and bail out. Anyone who observes +the heap will see a potentially *inconsistent* heap, but at least it won't +cause any double-drops! If the algorithm terminates normally, then this +operation happens to coincide precisely with the how we finish up regardless. + +Sadly, Rust has no such construct, so we're going to need to roll our own! The +way to do this is to store the algorithm's state in a separate struct with a +destructor for the "finally" logic. Whether we panic or not, that destructor +will run and clean up after us. ```rust +struct Hole<'a, T: 'a> { + data: &'a mut [T], + /// `elt` is always `Some` from new until drop. + elt: Option, + pos: usize, +} -impl Extend for Vec { - fn extend>(&mut self, iterable: I) { - let mut iter = iterable.into_iter(); - let size_hint = iter.size_hint().0; - self.reserve(size_hint); - self.set_len(self.len() + size_hint()); +impl<'a, T> Hole<'a, T> { + fn new(data: &'a mut [T], pos: usize) -> Self { + unsafe { + let elt = ptr::read(&data[pos]); + Hole { + data: data, + elt: Some(elt), + pos: pos, + } + } + } - for - } + fn pos(&self) -> usize { self.pos } + + fn removed(&self) -> &T { self.elt.as_ref().unwrap() } + + unsafe fn get(&self, index: usize) -> &T { &self.data[index] } + + unsafe fn move_to(&mut self, index: usize) { + let index_ptr: *const _ = &self.data[index]; + let hole_ptr = &mut self.data[self.pos]; + ptr::copy_nonoverlapping(index_ptr, hole_ptr, 1); + self.pos = index; + } } +impl<'a, T> Drop for Hole<'a, T> { + fn drop(&mut self) { + // fill the hole again + unsafe { + let pos = self.pos; + ptr::write(&mut self.data[pos], self.elt.take().unwrap()); + } + } +} + +impl BinaryHeap { + fn sift_up(&mut self, pos: usize) { + unsafe { + // Take out the value at `pos` and create a hole. + let mut hole = Hole::new(&mut self.data, pos); + + while hole.pos() != 0 { + let parent = parent(hole.pos()); + if hole.removed() <= hole.get(parent) { break } + hole.move_to(parent); + } + // Hole will be unconditionally filled here; panic or not! + } + } +} +``` + + + + +## Poisoning + +Although all unsafe code *must* ensure some minimal level of exception safety, +some types may choose to explicitly *poison* themselves if they witness a panic. +The most notable example of this is the standard library's Mutex type. A Mutex +will poison itself if one of its MutexGuards (the thing it returns when a lock +is obtained) is dropped during a panic. Any future attempts to lock the Mutex +will return an `Err`. + +Mutex poisons not for *true* safety in the sense that Rust normally cares about. It +poisons as a safety-guard against blindly using the data that comes out of a Mutex +that has witnessed a panic while locked. The data in such a Mutex was likely in the +middle of being modified, and as such may be in an inconsistent or incomplete state. +It is important to note that one cannot violate memory safety with such a type +if it is correctly written. After all, it must be exception safe! + +However if the Mutex contained, say, a BinaryHeap that does not actually have the +heap property, it's unlikely that any code that uses it will do +what the author intended. As such, the program should not proceed normally. +Still, if you're double-plus-sure that you can do *something* with the value, +the Err exposes a method to get the lock anyway. It *is* safe, after all. + + + +# FFI + +Rust's unwinding strategy is not specified to be fundamentally compatible +with any other language's unwinding. As such, unwinding into Rust from another +language, or unwinding into another language from Rust is Undefined Behaviour. +What you do at that point is up to you, but you must *absolutely* catch any +panics at the FFI boundary! At best, your application will crash and burn. At +worst, your application *won't* crash and burn, and will proceed with completely +clobbered state. From b26958caf745a05b4fa45b655ffeab18445cdb9b Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 21:44:07 -0700 Subject: [PATCH 038/104] add unwinding section to index --- SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SUMMARY.md b/SUMMARY.md index d136ebcebd4e8..91a07b79e389a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,5 +5,6 @@ * [Conversions](conversions.md) * [Uninitialized Memory](uninitialized.md) * [Ownership-oriented resource management (RAII)](raii.md) +* [Unwinding](unwinding.md) * [Concurrency](concurrency.md) * [Example: Implementing Vec](vec.md) \ No newline at end of file From 108a697b1c225dafef16a77076e30149b1d0ebe7 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 29 Jun 2015 22:30:10 -0700 Subject: [PATCH 039/104] conversion corrections --- conversions.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/conversions.md b/conversions.md index ad5d240f2a741..55b7b20e50d1d 100644 --- a/conversions.md +++ b/conversions.md @@ -53,7 +53,7 @@ Coercion is allowed between the following types: * `&mut T` to `*mut T` * Unsizing: `T` to `U` if `T` implements `CoerceUnsized` -`CoerceUnsized> for Pointer` where T: Unsize is implemented +`CoerceUnsized> for Pointer where T: Unsize` is implemented for all pointer types (including smart pointers like Box and Rc). Unsize is only implemented automatically, and enables the following transformations: @@ -65,7 +65,6 @@ only implemented automatically, and enables the following transformations: * `Foo` is a struct * Only the last field has type `T` * `T` is not part of the type of any other fields - (note that this also applies to to tuples as an anonymous struct `Tuple3`) Coercions occur at a *coercion site*. Any location that is explicitly typed will cause a coercion to its type. If inference is necessary, the coercion will @@ -106,6 +105,9 @@ fn main() { ^~~ ``` + + + # The Dot Operator The dot operator will perform a lot of magic to convert types. It will perform @@ -113,6 +115,9 @@ auto-referencing, auto-dereferencing, and coercion until types match. TODO: steal information from http://stackoverflow.com/questions/28519997/what-are-rusts-exact-auto-dereferencing-rules/28552082#28552082 + + + # Casts Casts are a superset of coercions: every coercion can be explicitly invoked via a @@ -171,6 +176,8 @@ For numeric casts, there are quite a few cases to consider: + + # Conversion Traits TODO? From 18067e41090938ff5d642bbef05604c939e542dc Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 1 Jul 2015 13:11:13 -0700 Subject: [PATCH 040/104] start on proper atomics --- concurrency.md | 49 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/concurrency.md b/concurrency.md index fc04bd83811af..71cfec3393e53 100644 --- a/concurrency.md +++ b/concurrency.md @@ -154,15 +154,44 @@ only to data races? # Atomics -Rust pretty blatantly just inherits LLVM's model for atomics, which in turn is -largely based off of the C11 model for atomics. This is not due these models -being particularly excellent or easy to understand. Indeed, these models are -quite complex and are known to have several flaws. Rather, it is a pragmatic -concession to the fact that *everyone* is pretty bad at modeling atomics. At very -least, we can benefit from existing tooling and research around C's model. +Rust pretty blatantly just inherits C11's memory model for atomics. This is not +due this model being particularly excellent or easy to understand. Indeed, this +model is quite complex and known to have [several flaws][C11-busted]. Rather, +it is a pragmatic concession to the fact that *everyone* is pretty bad at modeling +atomics. At very least, we can benefit from existing tooling and research around +C. -Trying to fully explain these models is fairly hopeless, so we're just going to -drop that problem in LLVM's lap. +Trying to fully explain the model is fairly hopeless. If you want all the +nitty-gritty details, you should check out [C's specification][C11-model]. +Still, we'll try to cover the basics and some of the problems Rust developers +face. + +The C11 memory model is fundamentally about trying to bridge the gap between C's +single-threaded semantics, common compiler optimizations, and hardware peculiarities +in the face of a multi-threaded environment. It does this by splitting memory +accesses into two worlds: data accesses, and atomic accesses. + +Data accesses are the bread-and-butter of the programming world. They are +fundamentally unsynchronized and compilers are free to aggressively optimize +them. In particular data accesses are free to be reordered by the compiler +on the assumption that the program is single-threaded. The hardware is also free +to propagate the changes made in data accesses as lazily and inconsistently as +it wants to other threads. Mostly critically, data accesses are where we get data +races. These are pretty clearly awful semantics to try to write a multi-threaded +program with. + +Atomic accesses are the answer to this. Each atomic access can be marked with +an *ordering*. The set of orderings Rust exposes are: + +* Sequentially Consistent (SeqCst) +* Release +* Acquire +* Relaxed + +(Note: We explicitly do not expose the C11 *consume* ordering) + +TODO: give simple "basic" explanation of these +TODO: implementing Arc example (why does Drop need the trailing barrier?) @@ -184,5 +213,5 @@ with everyone else's stuff. -[llvm-conc]: http://llvm.org/docs/Atomics.html -[trpl-conc]: https://doc.rust-lang.org/book/concurrency.html +[C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf +[C11-model]: http://en.cppreference.com/w/c/atomic/memory_order From ccb08a52fee9756f39696253e1cd1d1b3b55fc85 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 1 Jul 2015 13:12:11 -0700 Subject: [PATCH 041/104] TODO --- lifetimes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lifetimes.md b/lifetimes.md index 48bfcb029913e..cd6f5ad288422 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -9,6 +9,8 @@ language-design problem. # The Tagged Union Problem +TODO: rewrite this to use Box instead? + The core of the lifetime and mutability system derives from a simple problem: internal pointers to tagged unions. For instance, consider the following code: From e4f718ad1c91e4da0438cf925a2baad39fa70181 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 1 Jul 2015 13:37:17 -0700 Subject: [PATCH 042/104] uninit cleanup --- uninitialized.md | 55 ++++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/uninitialized.md b/uninitialized.md index 88cc7deac4725..983c320c7382c 100644 --- a/uninitialized.md +++ b/uninitialized.md @@ -6,7 +6,7 @@ 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 +Like C, all stack variables in Rust are uninitialized until a value is explicitly assigned to them. Unlike C, Rust statically prevents you from ever reading them until you do: @@ -32,9 +32,6 @@ or anything like that. So this compiles: ```rust fn main() { let x: i32; - let y: i32; - - y = 1; if true { x = 1; @@ -42,7 +39,7 @@ fn main() { x = 2; } - println!("{} {}", x, y); + println!("{}", x); } ``` @@ -98,13 +95,13 @@ 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, 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 +As of Rust 1.0, the drop flags are actually not-so-secretly stashed in a hidden 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 @@ -115,7 +112,7 @@ 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. +Safe Rust lets you work with them, but you're never in danger. 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 @@ -125,23 +122,23 @@ 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 +`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. +Unfortunately, this opens us up to all kinds of problems. 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 uninitialized 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. +This is also a problem if you're working with a raw system allocator, which +returns a pointer to uninitialized memory. -To handle this, we must use the `std::ptr` module. In particular, it provides +To handle this, we must use the `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`. @@ -157,7 +154,7 @@ evaluating the old value: `write`, `copy`, and `copy_nonoverlapping`. 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 +are allocated. However the ways writing arbitrary bits to arbitrary locations of memory can break things are basically uncountable! Putting this all together, we get the following: @@ -177,6 +174,7 @@ fn main() { x = mem::uninitialized(); for i in 0..SIZE { // very carefully overwrite each index without reading it + // NOTE: exception safety is not a concern; Box can't panic ptr::write(&mut x[i], Box::new(i)); } } @@ -186,15 +184,16 @@ fn main() { ``` 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. +shenanigans with types which don't implement Drop or +contain Drop types, because Rust knows not to try to Drop them. Similarly you +should be able to assign to fields of partially initialized structs +directly if those fields don't contain any Drop types. -However when working with uninitialized memory you need to be ever vigilant for +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. +Every control path through that variable's scope must initialize the value +before it ends, if has a destructor. +*[This includes code panicking](unwinding.html)*. 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 From dd98edd60e845f0c020526a45bc56103365f121d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Thu, 2 Jul 2015 23:57:28 -0700 Subject: [PATCH 043/104] lifetiiiiimes --- conversions.md | 2 +- lifetimes.md | 384 ++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 321 insertions(+), 65 deletions(-) diff --git a/conversions.md b/conversions.md index 55b7b20e50d1d..25d849dfbc189 100644 --- a/conversions.md +++ b/conversions.md @@ -61,7 +61,7 @@ only implemented automatically, and enables the following transformations: * `T` => `Trait` where `T: Trait` * `SubTrait` => `Trait` where `SubTrait: Trait` (TODO: is this now implied by the previous?) * `Foo<..., T, ...>` => `Foo<..., U, ...>` where: - * T: Unsize + * `T: Unsize` * `Foo` is a struct * Only the last field has type `T` * `T` is not part of the type of any other fields diff --git a/lifetimes.md b/lifetimes.md index cd6f5ad288422..976b4d53e2c91 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -2,106 +2,360 @@ Ownership is the breakout feature of Rust. It allows Rust to be completely memory-safe and efficient, while avoiding garbage collection. Before getting -into the ownership system in detail, we will consider a simple but *fundamental* -language-design problem. +into the ownership system in detail, we will consider the motivation of this +design. +TODO: Interior Mutability section -# The Tagged Union Problem -TODO: rewrite this to use Box instead? -The core of the lifetime and mutability system derives from a simple problem: -internal pointers to tagged unions. For instance, consider the following code: +# Living Without Garbage Collection + +We will assume that you accept that garbage collection is not always an optimal +solution, and that it is desirable to manually manage memory to some extent. +If you do not accept this, might I interest you in a different language? + +Regardless of your feelings on GC, it is pretty clearly a *massive* boon to +making code safe. You never have to worry about things going away *too soon* +(although whether you still *wanted* to be pointing at that thing is a different +issue...). This is a pervasive problem that C and C++ need to deal with. +Consider this simple mistake that all of us who have used a non-GC'd language +have made at one point: + +```rust,ignore +fn as_str(data: &u32) -> &str { + // compute the string + let s = format!("{}", data); + + // OH NO! We returned a reference to something that + // exists only in this function! + // Dangling pointer! Use after free! Alas! + // (this does not compile in Rust) + &s +} +``` + +This is exactly what Rust's ownership system was built to solve. +Rust knows the scope in which the `&s` lives, and as such can prevent it from +escaping. However this is a simple case that even a C compiler could plausibly +catch. Things get more complicated as code gets bigger and pointers get fed through +various functions. Eventually, a C compiler will fall down and won't be able to +perform sufficient escape analysis to prove your code unsound. It will consequently +be forced to accept your program on the assumption that it is correct. + +This will never happen to Rust. It's up to the programmer to prove to the +compiler that everything is sound. + +Of course, rust's story around ownership is much more complicated than just +verifying that references don't escape the scope of their referrent. That's +because ensuring pointers are always valid is much more complicated than this. +For instance in this code, + +```rust,ignore +let mut data = vec![1, 2, 3]; +// get an internal reference +let x = &data[0]; + +// OH NO! `push` causes the backing storage of `data` to be reallocated. +// Dangling pointer! User after free! Alas! +// (this does not compile in Rust) +data.push(4); + +println!("{}", x); +``` + +naive scope analysis would be insufficient to prevent this bug, because `data` +does in fact live as long as we needed. However it was *changed* while we had +a reference into it. This is why Rust requires any references to freeze the +referrent and its owners. + + + +# References + +There are two kinds of reference: + +* Shared reference: `&` +* Mutable reference: `&mut` + +Which obey the following rules: + +* A reference cannot outlive its referrent +* A mutable reference cannot be aliased + +To define aliasing, we must define the notion of *paths* and *liveness*. + + + + +## Paths + +If all Rust had were values, then every value would be uniquely owned +by a variable or composite structure. From this we naturally derive a *tree* +of ownership. The stack itself is the root of the tree, with every variable +as its direct children. Each variable's direct children would be their fields +(if any), and so on. + +From this view, every value in Rust has a unique *path* in the tree of ownership. +References to a value can subsequently be interpretted as a path in this tree. +Of particular interest are *prefixes*: `x` is a prefix of `y` if `x` owns `y` + +However much data doesn't reside on the stack, and we must also accomodate this. +Globals and thread-locals are simple enough to model as residing at the bottom +of the stack. However data on the heap poses a different problem. + +If all Rust had on the heap was data uniquely by a pointer on the stack, +then we can just treat that pointer as a struct that owns the value on +the heap. Box, Vec, String, and HashMap, are examples of types which uniquely +own data on the heap. + +Unfortunately, data on the heap is not *always* uniquely owned. Rc for instance +introduces a notion of *shared* ownership. Shared ownership means there is no +unique path. A value with no unique path limits what we can do with it. In general, only +shared references can be created to these values. However mechanisms which ensure +mutual exclusion may establish One True Owner temporarily, establishing a unique path +to that value (and therefore all its children). + +The most common way to establish such a path is through *interior mutability*, +in contrast to the *inherited mutability* that everything in Rust normally uses. +Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. These +types provide exclusive access through runtime restrictions. However it is also +possible to establish unique ownership without interior mutability. For instance, +if an Rc has refcount 1, then it is safe to mutate or move its internals. + + + + +## Liveness + +Roughly, a reference is *live* at some point in a program if it can be +dereferenced. Shared references are always live unless they are literally unreachable +(for instance, they reside in freed or leaked memory). Mutable references can be +reachable but *not* live through the process of *reborrowing*. + +A mutable reference can be reborrowed to either a shared or mutable reference. +Further, the reborrow can produce exactly the same reference, or point to a +path it is a prefix of. For instance, a mutable reference can be reborrowed +to point to a field of its referrent: ```rust -enum Foo { - A(u32), - B(f64), +let x = &mut (1, 2); +{ + // reborrow x to a subfield + let y = &mut x.0; + // y is now live, but x isn't + *y = 3; } +// y goes out of scope, so x is live again +*x = (5, 7); +``` -let mut x = B(2.0); -if let B(ref mut y) = x { - *x = A(7); - // OH NO! a u32 has been interpretted as an f64! Type-safety hole! - // (this does not actually compile) - println!("{}", y); +It is also possible to reborrow into *multiple* mutable references, as long as +they are to *disjoint*: no reference is a prefix of another. Rust +explicitly enables this to be done with disjoint struct fields, because +disjointness can be statically proven: +``` +let x = &mut (1, 2); +{ + // reborrow x to two disjoint subfields + let y = &mut x.0; + let z = &mut x.1; + // y and z are now live, but x isn't + *y = 3; + *z = 4; } +// y and z go out of scope, so x is live again +*x = (5, 7); ``` -The problem here is an intersection of 3 choices: +However it's often the case that Rust isn't sufficiently smart to prove that +multiple borrows are disjoint. *This does not mean it is fundamentally illegal +to make such a borrow*, just that Rust isn't as smart as you want. -* data in a tagged union is inline with the tag -* tagged unions are mutable -* being able to take a pointer into a tagged union +To simplify things, we can model variables as a fake type of reference: *owned* +references. Owned references have much the same semantics as mutable references: +they can be re-borrowed in a mutable or shared manner, which makes them no longer +live. Live owned references have the unique property that they can be moved +out of (though mutable references *can* be swapped out of). This is +only given to *live* owned references because moving its referrent would of +course invalidate all outstanding references prematurely. -Remove *any* of these 3 and the problem goes away. Traditionally, functional -languages have avoided this problem by removing the mutable -option. This means that they can in principle keep their data inline (ghc has -a pragma for this). A garbage collected imperative language like Java could alternatively -solve this problem by just keeping all variants elsewhere, so that changing the -variant of a tagged union just overwrites a pointer, and anyone with an outstanding -pointer to the inner data is unaffected thanks to The Magic Of Garbage Collection. +As a local lint against inappropriate mutation, only variables that are marked +as `mut` can be borrowed mutably. -Rust, by contrast, takes a subtler approach. Rust allows mutation, -allows pointers to inner data, and its enums have their data allocated inline. -However it prevents anything from being mutated while there are outstanding -pointers to it! And this is all done at compile time. +It is also interesting to note that Box behaves exactly like an owned +reference. It can be moved out of, and Rust understands it sufficiently to +reason about its paths like a normal variable. -Interestingly, Rust's `std::cell` module exposes two types that offer an alternative -approach to this problem: -* The `Cell` type allows mutation of aliased data, but -instead forbids internal pointers to that data. The only way to read or write -a Cell is to copy the bits in or out. -* The `RefCell` type allows mutation of aliased data *and* internal pointers, but -manages this through *runtime* checks. It is effectively a thread-unsafe -read-write lock. -For more details see Dan Grossman's *Existential Types for Imperative Languages*: +## Aliasing -* [paper][grossman-paper] (Advanced) -* [slides][grossman-slides] (Simple) +With liveness and paths defined, we can now properly define *aliasing*: -[grossman-paper]: http://homes.cs.washington.edu/~djg/papers/exists_imp.pdf -[grossman-slides]: https://homes.cs.washington.edu/~djg/slides/esop02_talk.pdf +**A mutable reference is aliased if there exists another live reference to it or +one of its prefixes.** + +That's it. Super simple right? Except for the fact that it took us two pages +to define all of the terms in that defintion. You know: Super. Simple. + +Actually it's a bit more complicated than that. In addition to references, +Rust has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent +ownership or aliasing semantics. As a result, Rust makes absolutely no effort +to track that they are used correctly, and they are wildly unsafe. + +**It is an open question to what degree raw pointers have alias semantics. +However it is important for these definitions to be sound that the existence +of a raw pointer does not imply some kind of live path.** # Lifetimes -Rust's static checks are managed by the *borrow checker* (borrowck), which tracks -mutability and outstanding loans. This analysis can in principle be done without -any help locally. However as soon as data starts crossing the function boundary, -we have some serious trouble. In principle, borrowck could be a massive -whole-program analysis engine to handle this problem, but this would be an -atrocious solution. It would be terribly slow, and errors would be horribly -non-local. +Rust enforces these rules through *lifetimes*. Lifetimes are effectively +just names for scopes on the stack, somewhere in the program. Each reference, +and anything that contains a reference, is tagged with a lifetime specifying +the scope it's valid for. -Instead, Rust tracks ownership through *lifetimes*. Every single reference and value -in Rust is tagged with a lifetime that indicates the scope it is valid for. -Rust has two kinds of reference: +Within a function body, Rust generally doesn't let you explicitly name the +lifetimes involved. This is because it's generally not really *necessary* +to talk about lifetimes in a local context; rust has all the information and +can work out everything. -* Shared reference: `&` -* Mutable reference: `&mut` +However once you cross the function boundary, you need to start talking about +lifetimes. Lifetimes are denoted with an apostrophe: `'a`, `'static`. To dip +our toes with lifetimes, we're going to pretend that we're actually allowed +to label scopes with lifetimes, and desugar the examples from the start of +this chapter. -The main rules are as follows: +Our examples made use of *aggressive* sugar around scopes and lifetimes, +because writing everything out explicitly is *extremely noisy*. All rust code +relies on aggressive inference and elision of "obvious" things. -* A shared reference can be aliased -* A mutable reference cannot be aliased -* A reference cannot outlive its referrent (`&'a T -> T: 'a`) +One particularly interesting piece of sugar is that each `let` statement implicitly +introduces a scope. For the most part, this doesn't really matter. However it +does matter for variables that refer to each other. As a simple example, let's +completely desugar this simple piece of Rust code: -However non-mutable variables have some special rules: +```rust +let x = 0; +let y = &x; +let z = &y; +``` -* You cannot mutate or mutably borrow a non-mut variable, +becomes: -Only variables marked as mutable can be borrowed mutably, though this is little -more than a local lint against incorrect usage of a value. +```rust,ignore +// NOTE: `'a:` and `&'a x` is not valid syntax! +'a: { + let x: i32 = 0; + 'b: { + let y: &'a i32 = &'a x; + 'c: { + let z: &'b &'a i32 = &'b y; + } + } +} +``` +Wow. That's... awful. Let's all take a moment to thank Rust for being a huge +pile of sugar with sugar on top. +Anyway, let's look at some of those examples from before: + +```rust,ignore +fn as_str(data: &u32) -> &str { + let s = format!("{}", data); + &s +} +``` + +desugars to: + +```rust,ignore +fn as_str<'a>(data: &'a u32) -> &'a str { + 'b: { + let s = format!("{}", data); + return &'b s + } +} +``` + +This signature of `as_str` takes a reference to a u32 with *some* lifetime, and +promises that it can produce a reference to a str that can live *just as long*. +Already we can see why this signature might be trouble. That basically implies +that we're going to *find* a str somewhere in the scope that u32 originated in, +or somewhere *even* earlier. That's uh... a big ask. + +We then proceed to compute the string `s`, and return a reference to it. +Unfortunately, since `s` was defined in the scope `'b`, the reference we're +returning can only live for that long. From the perspective of the compiler, +we've failed *twice* here. We've failed to fulfill the contract we were asked +to fulfill (`'b` is unrelated to `'a`); and we've also tried to make a reference +outlive its referrent by returning an `&'b`, where `'b` is in our function. + +Shoot! + +Of course, the right way to right this function is as follows: + +```rust +fn to_string(data: &u32) -> String { + format!("{}", data) +} +``` + +We must produce an owned value inside the function to return it! The only way +we could have returned an `&'a str` would have been if it was in a field of the +`&'a u32`, which is obviously not the case. + +(Actually we could have also just returned a string literal, though this limits +the behaviour of our function *just a bit*.) + +How about the other example: + +```rust,ignore +let mut data = vec![1, 2, 3]; +let x = &data[0]; +data.push(4); +println!("{}", x); +``` + +```rust,ignore +'a: { + let mut data: Vec = vec![1, 2, 3]; + 'b: { + let x: &'a i32 = Index::index(&'a data, 0); + 'c: { + // Exactly what the desugar for Vec::push is is up to Rust. + // This particular desugar is a decent approximation for our + // purpose. In particular methods oft invoke a temporary borrow. + let temp: &'c mut Vec = &'c mut data; + // NOTE: Vec::push is not valid syntax + Vec::push(temp, 4); + } + println!("{}", x); + } +} +``` + +Here the problem is that we're trying to mutably borrow the `data` path, while +we have a reference into something it's a prefix of. Rust subsequently throws +up its hands in disgust and rejects our program. The correct way to write this +is to just re-order the code so that we make `x` *after* we push: + +TODO: convince myself of this. + +```rust +let mut data = vec![1, 2, 3]; +data.push(4); + +let x = &data[0]; +println!("{}", x); +``` @@ -213,7 +467,9 @@ these are unstable due to their awkward nature and questionable utility. -# Higher-Rank Lifetimes +# Higher-Rank Trait Bounds + +// TODO: make aturon less mad Generics in Rust generally allow types to be instantiated with arbitrary associated lifetimes, but this fixes the lifetimes they work with once From a42a41520584e28a8fb5e4f0b8b2e89900377011 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Fri, 3 Jul 2015 09:49:30 -0700 Subject: [PATCH 044/104] rework unsafe intro to be 1000% more adorable --- README.md | 185 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 131 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index b86f6209f35af..55e4bc5c87271 100644 --- a/README.md +++ b/README.md @@ -13,26 +13,66 @@ Where TRPL introduces the language and teaches the basics, TURPL dives deep into the specification of the language, and all the nasty bits necessary to write Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know the basics of the language and systems programming. We will not explain the -stack or heap, we will not explain the syntax. +stack or heap, we will not explain the basic syntax. -# A Tale Of Two Languages +# Meet Safe and Unsafe + +Safe and Unsafe are Rust's chief engineers. + +TODO: ADORABLE PICTURES OMG + +Unsafe handles all the dangerous internal stuff. They build the foundations +and handle all the dangerous materials. By all accounts, Unsafe is really a bit +unproductive, because the nature of their work means that they have to spend a +lot of time checking and double-checking everything. What if there's an earthquake +on a leap year? Are we ready for that? Unsafe better be, because if they get +*anything* wrong, everything will blow up! What Unsafe brings to the table is +*quality*, not quantity. Still, nothing would ever get done if everything was +built to Unsafe's standards! + +That's where Safe comes in. Safe has to handle *everything else*. Since Safe needs +to *get work done*, they've grown to be fairly carless and clumsy! Safe doesn't worry +about all the crazy eventualities that Unsafe does, because life is too short to deal +with leap-year-earthquakes. Of course, this means there's some jobs that Safe just +can't handle. Safe is all about quantity over quality. + +Unsafe loves Safe to bits, but knows that tey *can never trust them to do the +right thing*. Still, Unsafe acknowledges that not every problem needs quite the +attention to detail that they apply. Indeed, Unsafe would *love* if Safe could do +*everything* for them. To accomplish this, Unsafe spends most of their time +building *safe abstractions*. These abstractions handle all the nitty-gritty +details for Safe, and choose good defaults so that the simplest solution (which +Safe will inevitably use) is usually the *right* one. Once a safe abstraction is +built, Unsafe ideally needs to never work on it again, and Safe can blindly use +it in all their work. + +Unsafe's attention to detail means that all the things that they mark as ok for +Safe to use can be combined in arbitrarily ridiculous ways, and all the rules +that Unsafe is forced to uphold will never be violated. If they *can* be violated +by Safe, that means *Unsafe*'s the one in the wrong. Safe can work carelessly, +knowing that if anything blows up, it's not *their* fault. Safe can also call in +Unsafe at any time if there's a hard problem they can't quite work out, or if they +can't meet the client's quality demands. Of course, Unsafe will beg and plead Safe +to try their latest safe abstraction first! + +In addition to being adorable, Safe and Unsafe are what makes Rust possible. Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. Any time someone opines the guarantees of Rust, they are almost surely talking about -Safe Rust. However Safe Rust is not sufficient to write every program. For that, -we need the Unsafe Rust superset. +Safe. However Safe is not sufficient to write every program. For that, +we need the Unsafe superset. Most fundamentally, writing bindings to other languages (such as the C exposed by your operating system) is never going to be safe. Rust -can't control what other languages do to program execution! However Unsafe Rust is +can't control what other languages do to program execution! However Unsafe is also necessary to construct fundamental abstractions where the type system is not sufficient to automatically prove what you're doing is sound. Indeed, the Rust standard library is implemented in Rust, and it makes substantial -use of Unsafe Rust for implementing IO, memory allocation, collections, +use of Unsafe for implementing IO, memory allocation, collections, synchronization, and other low-level computational primitives. Upon hearing this, many wonder why they would not simply just use C or C++ in place of @@ -47,46 +87,40 @@ one does not have to suddenly worry about indexing out of bounds on `y`. C and C++, by contrast, have pervasive unsafety baked into the language. Even the modern best practices like `unique_ptr` have various safety pitfalls. -It should also be noted that writing Unsafe Rust should be regarded as an exceptional -action. Unsafe Rust is often the domain of *fundamental libraries*. Anything that needs +It cannot be emphasized enough that Unsafe should be regarded as an exceptional +thing, not a normal one. Unsafe is often the domain of *fundamental libraries*: anything that needs to make FFI bindings or define core abstractions. These fundamental libraries then expose -a *safe* interface for intermediate libraries and applications to build upon. And these +a safe interface for intermediate libraries and applications to build upon. And these safe interfaces make an important promise: if your application segfaults, it's not your fault. *They* have a bug. And really, how is that different from *any* safe language? Python, Ruby, and Java libraries can internally do all sorts of nasty things. The languages themselves are no -different. Safe languages regularly have bugs that cause critical vulnerabilities. -The fact that Rust is written with a healthy spoonful of Unsafe Rust is no different. +different. Safe languages *regularly* have bugs that cause critical vulnerabilities. +The fact that Rust is written with a healthy spoonful of Unsafe is no different. However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of C to do the nasty things that need to get done. -# What does `unsafe` mean? -Rust tries to model memory safety through the `unsafe` keyword. Interestingly, -the meaning of `unsafe` largely revolves around what -its *absence* means. If the `unsafe` keyword is absent from a program, it should -not be possible to violate memory safety under *any* conditions. The presence -of `unsafe` means that there are conditions under which this code *could* -violate memory safety. +# What do Safe and Unsafe really mean? -To be more concrete, Rust cares about preventing the following things: +Rust cares about preventing the following things: -* Dereferencing null/dangling pointers -* Reading uninitialized memory -* Breaking the pointer aliasing rules (TBD) (llvm rules + noalias on &mut and & w/o UnsafeCell) -* Invoking Undefined Behaviour (in e.g. compiler intrinsics) +* Dereferencing null or dangling pointers +* Reading [uninitialized memory][] +* Breaking the [pointer aliasing rules][] * Producing invalid primitive values: * dangling/null references * a `bool` that isn't 0 or 1 * an undefined `enum` discriminant - * a `char` larger than char::MAX + * a `char` larger than char::MAX (TODO: check if stronger restrictions apply) * A non-utf8 `str` -* Unwinding into an FFI function -* Causing a data race +* Unwinding into another language +* Causing a [data race][] +* Invoking Misc. Undefined Behaviour (in e.g. compiler intrinsics) That's it. That's all the Undefined Behaviour in Rust. Libraries are free to declare arbitrary requirements if they could transitively cause memory safety @@ -95,15 +129,17 @@ quite permisive with respect to other dubious operations. Rust considers it "safe" to: * Deadlock +* Have a Race Condition * Leak memory * Fail to call destructors * Overflow integers * Delete the production database -However any program that does such a thing is *probably* incorrect. Rust just isn't -interested in modeling these problems, as they are much harder to prevent in general, -and it's literally impossible to prevent incorrect programs from getting written. +However any program that does such a thing is *probably* incorrect. Rust +provides lots of tools to make doing these things rare, but these problems are +considered impractical to categorically prevent. +Rust models the seperation between Safe and Unsafe with the `unsafe` keyword. There are several places `unsafe` can appear in Rust today, which can largely be grouped into two categories: @@ -112,7 +148,7 @@ you to write `unsafe` elsewhere: * On functions, `unsafe` is declaring the function to be unsafe to call. Users of the function must check the documentation to determine what this means, and then have to write `unsafe` somewhere to identify that they're aware of - the danger. + the danger. * On trait declarations, `unsafe` is declaring that *implementing* the trait is an unsafe operation, as it has contracts that other unsafe code is free to trust blindly. @@ -126,19 +162,19 @@ unchecked contracts: There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for historical reasons and is in the process of being phased out. See the section on -destructors for details. +[destructors][] for details. Some examples of unsafe functions: * `slice::get_unchecked` will perform unchecked indexing, allowing memory safety to be freely violated. -* `ptr::offset` in an intrinsic that invokes Undefined Behaviour if it is +* `ptr::offset` is an intrinsic that invokes Undefined Behaviour if it is not "in bounds" as defined by LLVM (see the lifetimes section for details). * `mem::transmute` reinterprets some value as having the given type, - bypassing type safety in arbitrary ways. (see the conversions section for details) + bypassing type safety in arbitrary ways. (see [conversions][] for details) * All FFI functions are `unsafe` because they can do arbitrary things. C being an obvious culprit, but generally any language can do something - that Rust isn't happy about. (see the FFI section for details) + that Rust isn't happy about. As of Rust 1.0 there are exactly two unsafe traits: @@ -147,25 +183,60 @@ As of Rust 1.0 there are exactly two unsafe traits: * `Sync` is a marker trait that promises that threads can safely share implementors through a shared reference. -All other traits that declare any kind of contract *really* can't be trusted -to adhere to their contract when memory-safety is at stake. For instance Rust has -`PartialOrd` and `Ord` to differentiate between types which can "just" be -compared and those that implement a total ordering. However you can't actually -trust an implementor of `Ord` to actually provide a total ordering if failing to -do so causes you to e.g. index out of bounds. But if it just makes your program -do a stupid thing, then it's "fine" to rely on `Ord`. - -The reason this is the case is that `Ord` is safe to implement, and it should be -impossible for bad *safe* code to violate memory safety. Rust has traditionally -avoided making traits unsafe because it makes `unsafe` pervasive in the language, -which is not desirable. The only reason `Send` and `Sync` are unsafe is because -thread safety is a sort of fundamental thing that a program can't really guard -against locally (even by-value message passing still requires a notion Send). - - - - -# Working with unsafe +The need for unsafe traits boils down to the fundamental lack of trust that Unsafe +has for Safe. All safe traits are free to declare arbitrary contracts, but because +implementing them is a job for Safe, Unsafe can't trust those contracts to actually +be upheld. + +For instance Rust has `PartialOrd` and `Ord` traits to try to differentiate +between types which can "just" be compared, and those that actually implement a +*total* ordering. Pretty much every API that wants to work with data that can be +compared *really* wants Ord data. For instance, a sorted map like BTreeMap +*doesn't even make sense* for partially ordered types. If you claim to implement +Ord for a type, but don't actually provide a proper total ordering, BTreeMap will +get *really confused* and start making a total mess of itself. Data that is +inserted may be impossible to find! + +But that's ok. BTreeMap is safe, so it guarantees that even if you give it a +*completely* garbage Ord implementation, it will still do something *safe*. You +won't start reading uninitialized memory or unallocated memory. In fact, BTreeMap +manages to not actually lose any of your data. When the map is dropped, all the +destructors will be successfully called! Hooray! + +However BTreeMap is implemented using a modest spoonful of Unsafe (most collections +are). That means that it is not necessarily *trivially true* that a bad Ord +implementation will make BTreeMap behave safely. Unsafe most be sure not to rely +on Ord *where safety is at stake*, because Ord is provided by Safe, and memory +safety is not Safe's responsibility to uphold. *It must be impossible for Safe +code to violate memory safety*. + +But wouldn't it be grand if there was some way for Unsafe to trust *some* trait +contracts *somewhere*? This is the problem that unsafe traits tackle: by marking +*the trait itself* as unsafe *to implement*, Unsafe can trust the implementation +to be correct (because Unsafe can trust themself). + +Rust has traditionally avoided making traits unsafe because it makes Unsafe +pervasive, which is not desirable. Send and Sync are unsafe is because +thread safety is a *fundamental property* that Unsafe cannot possibly hope to +defend against in the same way it would defend against a bad Ord implementation. +The only way to possibly defend against thread-unsafety would be to *not use +threading at all*. Making every operation atomic isn't even sufficient, because +it's possible for complex invariants between disjoint locations in memory. + +Even concurrent paradigms that are traditionally regarded as Totally Safe like +message passing implicitly rely on some notion of thread safety -- are you +really message-passing if you send a *pointer*? Send and Sync therefore require +some *fundamental* level of trust that Safe code can't provide, so they must be +unsafe to implement. To help obviate the pervasive unsafety that this would +introduce, Send (resp. Sync) is *automatically* derived for all types composed only +of Send (resp. Sync) values. 99% of types are Send and Sync, and 99% of those +never actually say it (the remaining 1% is overwhelmingly synchronization +primitives). + + + + +# Working with Unsafe Rust generally only gives us the tools to talk about safety in a scoped and binary manner. Unfortunately reality is significantly more complicated than that. @@ -254,5 +325,11 @@ trust the capacity field because there's no way to verify it. Generally, the only bullet-proof way to limit the scope of unsafe code is at the module boundary with privacy. -[trpl]: https://doc.rust-lang.org/book/ + +[trpl]: https://doc.rust-lang.org/book/ +[pointer aliasing rules]: lifetimes.html#references +[uninitialized memory]: uninitialized.html +[data race]: concurrency.html +[destructors]: raii.html +[conversions]: conversions.html From 31adad6aad5b0fbff85a6effcfc5e11ba611493d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 6 Jul 2015 18:36:16 -0700 Subject: [PATCH 045/104] SHARD ALL THE CHAPTERS --- README.md | 319 +--------- SUMMARY.md | 40 +- casts.md | 55 ++ checked-uninit.md | 109 ++++ coercions.md | 72 +++ constructors.md | 26 + conversions.md | 185 ------ data.md | 292 --------- destructors.md | 140 +++++ dot-operator.md | 6 + exotic-sizes.md | 69 ++ hrtb.md | 72 +++ leaking.md | 229 +++++++ lifetime-elision.md | 64 ++ lifetime-misc.md | 229 +++++++ lifetime-mismatch.md | 81 +++ lifetimes.md | 1017 ++++-------------------------- meet-safe-and-unsafe.md | 82 +++ other-reprs.md | 61 ++ ownership.md | 66 ++ raii.md | 410 ------------ references.md | 139 +++++ repr-rust.md | 124 ++++ safe-unsafe-meaning.md | 135 ++++ subtyping.md | 177 ++++++ transmutes.md | 29 + unbounded-lifetimes.md | 37 ++ unchecked-uninit.md | 86 +++ uninitialized.md | 194 +----- vec-alloc.md | 117 ++++ vec-dealloc.md | 29 + vec-deref.md | 40 ++ vec-drain.md | 318 ++++++++++ vec-final.md | 309 +++++++++ vec-insert-remove.md | 50 ++ vec-into-iter.md | 293 +++++++++ vec-layout.md | 61 ++ vec-push-pop.md | 55 ++ vec.md | 1317 --------------------------------------- working-with-unsafe.md | 88 +++ 40 files changed, 3612 insertions(+), 3610 deletions(-) create mode 100644 casts.md create mode 100644 checked-uninit.md create mode 100644 coercions.md create mode 100644 constructors.md create mode 100644 destructors.md create mode 100644 dot-operator.md create mode 100644 exotic-sizes.md create mode 100644 hrtb.md create mode 100644 leaking.md create mode 100644 lifetime-elision.md create mode 100644 lifetime-misc.md create mode 100644 lifetime-mismatch.md create mode 100644 meet-safe-and-unsafe.md create mode 100644 other-reprs.md create mode 100644 ownership.md create mode 100644 references.md create mode 100644 repr-rust.md create mode 100644 safe-unsafe-meaning.md create mode 100644 subtyping.md create mode 100644 transmutes.md create mode 100644 unbounded-lifetimes.md create mode 100644 unchecked-uninit.md create mode 100644 vec-alloc.md create mode 100644 vec-dealloc.md create mode 100644 vec-deref.md create mode 100644 vec-drain.md create mode 100644 vec-final.md create mode 100644 vec-insert-remove.md create mode 100644 vec-into-iter.md create mode 100644 vec-layout.md create mode 100644 vec-push-pop.md create mode 100644 working-with-unsafe.md diff --git a/README.md b/README.md index 55e4bc5c87271..a801a21db3d53 100644 --- a/README.md +++ b/README.md @@ -13,323 +13,8 @@ Where TRPL introduces the language and teaches the basics, TURPL dives deep into the specification of the language, and all the nasty bits necessary to write Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know the basics of the language and systems programming. We will not explain the -stack or heap, we will not explain the basic syntax. +stack or heap. We will not explain the basic syntax. - - -# Meet Safe and Unsafe - -Safe and Unsafe are Rust's chief engineers. - -TODO: ADORABLE PICTURES OMG - -Unsafe handles all the dangerous internal stuff. They build the foundations -and handle all the dangerous materials. By all accounts, Unsafe is really a bit -unproductive, because the nature of their work means that they have to spend a -lot of time checking and double-checking everything. What if there's an earthquake -on a leap year? Are we ready for that? Unsafe better be, because if they get -*anything* wrong, everything will blow up! What Unsafe brings to the table is -*quality*, not quantity. Still, nothing would ever get done if everything was -built to Unsafe's standards! - -That's where Safe comes in. Safe has to handle *everything else*. Since Safe needs -to *get work done*, they've grown to be fairly carless and clumsy! Safe doesn't worry -about all the crazy eventualities that Unsafe does, because life is too short to deal -with leap-year-earthquakes. Of course, this means there's some jobs that Safe just -can't handle. Safe is all about quantity over quality. - -Unsafe loves Safe to bits, but knows that tey *can never trust them to do the -right thing*. Still, Unsafe acknowledges that not every problem needs quite the -attention to detail that they apply. Indeed, Unsafe would *love* if Safe could do -*everything* for them. To accomplish this, Unsafe spends most of their time -building *safe abstractions*. These abstractions handle all the nitty-gritty -details for Safe, and choose good defaults so that the simplest solution (which -Safe will inevitably use) is usually the *right* one. Once a safe abstraction is -built, Unsafe ideally needs to never work on it again, and Safe can blindly use -it in all their work. - -Unsafe's attention to detail means that all the things that they mark as ok for -Safe to use can be combined in arbitrarily ridiculous ways, and all the rules -that Unsafe is forced to uphold will never be violated. If they *can* be violated -by Safe, that means *Unsafe*'s the one in the wrong. Safe can work carelessly, -knowing that if anything blows up, it's not *their* fault. Safe can also call in -Unsafe at any time if there's a hard problem they can't quite work out, or if they -can't meet the client's quality demands. Of course, Unsafe will beg and plead Safe -to try their latest safe abstraction first! - -In addition to being adorable, Safe and Unsafe are what makes Rust possible. -Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. -Any time someone opines the guarantees of Rust, they are almost surely talking about -Safe. However Safe is not sufficient to write every program. For that, -we need the Unsafe superset. - -Most fundamentally, writing bindings to other languages -(such as the C exposed by your operating system) is never going to be safe. Rust -can't control what other languages do to program execution! However Unsafe is -also necessary to construct fundamental abstractions where the type system is not -sufficient to automatically prove what you're doing is sound. - -Indeed, the Rust standard library is implemented in Rust, and it makes substantial -use of Unsafe for implementing IO, memory allocation, collections, -synchronization, and other low-level computational primitives. - -Upon hearing this, many wonder why they would not simply just use C or C++ in place of -Rust (or just use a "real" safe language). If we're going to do unsafe things, why not -lean on these much more established languages? - -The most important difference between C++ and Rust is a matter of defaults: -Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular -action. In deciding to work with unchecked uninitialized memory, this does not -suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, -one does not have to suddenly worry about indexing out of bounds on `y`. -C and C++, by contrast, have pervasive unsafety baked into the language. Even the -modern best practices like `unique_ptr` have various safety pitfalls. - -It cannot be emphasized enough that Unsafe should be regarded as an exceptional -thing, not a normal one. Unsafe is often the domain of *fundamental libraries*: anything that needs -to make FFI bindings or define core abstractions. These fundamental libraries then expose -a safe interface for intermediate libraries and applications to build upon. And these -safe interfaces make an important promise: if your application segfaults, it's not your -fault. *They* have a bug. - -And really, how is that different from *any* safe language? Python, Ruby, and Java libraries -can internally do all sorts of nasty things. The languages themselves are no -different. Safe languages *regularly* have bugs that cause critical vulnerabilities. -The fact that Rust is written with a healthy spoonful of Unsafe is no different. -However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of -C to do the nasty things that need to get done. - - - - - -# What do Safe and Unsafe really mean? - -Rust cares about preventing the following things: - -* Dereferencing null or dangling pointers -* Reading [uninitialized memory][] -* Breaking the [pointer aliasing rules][] -* Producing invalid primitive values: - * dangling/null references - * a `bool` that isn't 0 or 1 - * an undefined `enum` discriminant - * a `char` larger than char::MAX (TODO: check if stronger restrictions apply) - * A non-utf8 `str` -* Unwinding into another language -* Causing a [data race][] -* Invoking Misc. Undefined Behaviour (in e.g. compiler intrinsics) - -That's it. That's all the Undefined Behaviour in Rust. Libraries are free to -declare arbitrary requirements if they could transitively cause memory safety -issues, but it all boils down to the above actions. Rust is otherwise -quite permisive with respect to other dubious operations. Rust considers it -"safe" to: - -* Deadlock -* Have a Race Condition -* Leak memory -* Fail to call destructors -* Overflow integers -* Delete the production database - -However any program that does such a thing is *probably* incorrect. Rust -provides lots of tools to make doing these things rare, but these problems are -considered impractical to categorically prevent. - -Rust models the seperation between Safe and Unsafe with the `unsafe` keyword. -There are several places `unsafe` can appear in Rust today, which can largely be -grouped into two categories: - -* There are unchecked contracts here. To declare you understand this, I require -you to write `unsafe` elsewhere: - * On functions, `unsafe` is declaring the function to be unsafe to call. Users - of the function must check the documentation to determine what this means, - and then have to write `unsafe` somewhere to identify that they're aware of - the danger. - * On trait declarations, `unsafe` is declaring that *implementing* the trait - is an unsafe operation, as it has contracts that other unsafe code is free to - trust blindly. - -* I am declaring that I have, to the best of my knowledge, adhered to the -unchecked contracts: - * On trait implementations, `unsafe` is declaring that the contract of the - `unsafe` trait has been upheld. - * On blocks, `unsafe` is declaring any unsafety from an unsafe - operation within to be handled, and therefore the parent function is safe. - -There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for -historical reasons and is in the process of being phased out. See the section on -[destructors][] for details. - -Some examples of unsafe functions: - -* `slice::get_unchecked` will perform unchecked indexing, allowing memory - safety to be freely violated. -* `ptr::offset` is an intrinsic that invokes Undefined Behaviour if it is - not "in bounds" as defined by LLVM (see the lifetimes section for details). -* `mem::transmute` reinterprets some value as having the given type, - bypassing type safety in arbitrary ways. (see [conversions][] for details) -* All FFI functions are `unsafe` because they can do arbitrary things. - C being an obvious culprit, but generally any language can do something - that Rust isn't happy about. - -As of Rust 1.0 there are exactly two unsafe traits: - -* `Send` is a marker trait (it has no actual API) that promises implementors - are safe to send to another thread. -* `Sync` is a marker trait that promises that threads can safely share - implementors through a shared reference. - -The need for unsafe traits boils down to the fundamental lack of trust that Unsafe -has for Safe. All safe traits are free to declare arbitrary contracts, but because -implementing them is a job for Safe, Unsafe can't trust those contracts to actually -be upheld. - -For instance Rust has `PartialOrd` and `Ord` traits to try to differentiate -between types which can "just" be compared, and those that actually implement a -*total* ordering. Pretty much every API that wants to work with data that can be -compared *really* wants Ord data. For instance, a sorted map like BTreeMap -*doesn't even make sense* for partially ordered types. If you claim to implement -Ord for a type, but don't actually provide a proper total ordering, BTreeMap will -get *really confused* and start making a total mess of itself. Data that is -inserted may be impossible to find! - -But that's ok. BTreeMap is safe, so it guarantees that even if you give it a -*completely* garbage Ord implementation, it will still do something *safe*. You -won't start reading uninitialized memory or unallocated memory. In fact, BTreeMap -manages to not actually lose any of your data. When the map is dropped, all the -destructors will be successfully called! Hooray! - -However BTreeMap is implemented using a modest spoonful of Unsafe (most collections -are). That means that it is not necessarily *trivially true* that a bad Ord -implementation will make BTreeMap behave safely. Unsafe most be sure not to rely -on Ord *where safety is at stake*, because Ord is provided by Safe, and memory -safety is not Safe's responsibility to uphold. *It must be impossible for Safe -code to violate memory safety*. - -But wouldn't it be grand if there was some way for Unsafe to trust *some* trait -contracts *somewhere*? This is the problem that unsafe traits tackle: by marking -*the trait itself* as unsafe *to implement*, Unsafe can trust the implementation -to be correct (because Unsafe can trust themself). - -Rust has traditionally avoided making traits unsafe because it makes Unsafe -pervasive, which is not desirable. Send and Sync are unsafe is because -thread safety is a *fundamental property* that Unsafe cannot possibly hope to -defend against in the same way it would defend against a bad Ord implementation. -The only way to possibly defend against thread-unsafety would be to *not use -threading at all*. Making every operation atomic isn't even sufficient, because -it's possible for complex invariants between disjoint locations in memory. - -Even concurrent paradigms that are traditionally regarded as Totally Safe like -message passing implicitly rely on some notion of thread safety -- are you -really message-passing if you send a *pointer*? Send and Sync therefore require -some *fundamental* level of trust that Safe code can't provide, so they must be -unsafe to implement. To help obviate the pervasive unsafety that this would -introduce, Send (resp. Sync) is *automatically* derived for all types composed only -of Send (resp. Sync) values. 99% of types are Send and Sync, and 99% of those -never actually say it (the remaining 1% is overwhelmingly synchronization -primitives). - - - - -# Working with Unsafe - -Rust generally only gives us the tools to talk about safety in a scoped and -binary manner. Unfortunately reality is significantly more complicated than that. -For instance, consider the following toy function: - -```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { - if idx < arr.len() { - unsafe { - Some(*arr.get_unchecked(idx)) - } - } else { - None - } -} -``` - -Clearly, this function is safe. We check that the index is in bounds, and if it -is, index into the array in an unchecked manner. But even in such a trivial -function, the scope of the unsafe block is questionable. Consider changing the -`<` to a `<=`: - -```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { - if idx <= arr.len() { - unsafe { - Some(*arr.get_unchecked(idx)) - } - } else { - None - } -} -``` - -This program is now unsound, an yet *we only modified safe code*. This is the -fundamental problem of safety: it's non-local. The soundness of our unsafe -operations necessarily depends on the state established by "safe" operations. -Although safety *is* modular (we *still* don't need to worry about about -unrelated safety issues like uninitialized memory), it quickly contaminates the -surrounding code. - -Trickier than that is when we get into actual statefulness. Consider a simple -implementation of `Vec`: - -```rust -// Note this defintion is insufficient. See the section on lifetimes. -struct Vec { - ptr: *mut T, - len: usize, - cap: usize, -} - -// Note this implementation does not correctly handle zero-sized types. -// We currently live in a nice imaginary world of only positive fixed-size -// types. -impl Vec { - fn push(&mut self, elem: T) { - if self.len == self.cap { - // not important for this example - self.reallocate(); - } - unsafe { - ptr::write(self.ptr.offset(len as isize), elem); - self.len += 1; - } - } -} -``` - -This code is simple enough to reasonably audit and verify. Now consider -adding the following method: - -```rust - fn make_room(&mut self) { - // grow the capacity - self.cap += 1; - } -``` - -This code is safe, but it is also completely unsound. Changing the capacity -violates the invariants of Vec (that `cap` reflects the allocated space in the -Vec). This is not something the rest of `Vec` can guard against. It *has* to -trust the capacity field because there's no way to verify it. - -`unsafe` does more than pollute a whole function: it pollutes a whole *module*. -Generally, the only bullet-proof way to limit the scope of unsafe code is at the -module boundary with privacy. - - - -[trpl]: https://doc.rust-lang.org/book/ -[pointer aliasing rules]: lifetimes.html#references -[uninitialized memory]: uninitialized.html -[data race]: concurrency.html -[destructors]: raii.html -[conversions]: conversions.html +[trpl]: https://doc.rust-lang.org/book/ \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md index 91a07b79e389a..225708e21869f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,10 +1,42 @@ # Summary +* [Meet Safe and Unsafe](meet-safe-and-unsafe.md) + * [What Do Safe and Unsafe Mean](safe-unsafe-meaning.md) + * [Working with Unsafe](working-with-unsafe.md) * [Data Layout](data.md) -* [Ownership and Lifetimes](lifetimes.md) -* [Conversions](conversions.md) + * [repr(Rust)](repr-rust.md) + * [Exotically Sized Types](exotic-sizes.md) + * [Other reprs](other-reprs.md) +* [Ownership](ownership.md) + * [References](references.md) + * [Lifetimes](lifetimes.md) + * [Limits of lifetimes](lifetime-mismatch.md) + * [Lifetime Elision](lifetime-elision.md) + * [Unbounded Lifetimes](unbounded-lifetimes.md) + * [Higher-Rank Trait Bounds](hrtb.md) + * [Subtyping and Variance](subtyping.md) + * [Misc](lifetime-misc.md) +* [Type Conversions](conversions.md) + * [Coercions](coercions.md) + * [The Dot Operator](dot-operator.md) + * [Casts](casts.md) + * [Transmutes](transmutes.md) * [Uninitialized Memory](uninitialized.md) -* [Ownership-oriented resource management (RAII)](raii.md) + * [Checked](checked-uninit.md) + * [Unchecked](unchecked-uninit.md) +* [Ownership-Oriented Resource Management](raii.md) + * [Constructors](constructors.md) + * [Destructors](destructors.md) + * [Leaking](leaking.md) * [Unwinding](unwinding.md) * [Concurrency](concurrency.md) -* [Example: Implementing Vec](vec.md) \ No newline at end of file +* [Example: Implementing Vec](vec.md) + * [Layout](vec-layout.md) + * [Allocating](vec-alloc.md) + * [Push and Pop](vec-push-pop.md) + * [Deallocating](vec-dealloc.md) + * [Deref](vec-deref.md) + * [Insert and Remove](vec-insert-remove.md) + * [IntoIter](vec-into-iter.md) + * [Drain](vec-drain.md) + * [Final Code](vec-final.md) \ No newline at end of file diff --git a/casts.md b/casts.md new file mode 100644 index 0000000000000..730d8499acfea --- /dev/null +++ b/casts.md @@ -0,0 +1,55 @@ +% Casts + +Casts are a superset of coercions: every coercion can be explicitly invoked via a +cast, but some conversions *require* a cast. These "true casts" are generally regarded +as dangerous or problematic actions. True casts revolve around raw pointers and +the primitive numeric types. True casts aren't checked. + +Here's an exhaustive list of all the true casts. For brevity, we will use `*` +to denote either a `*const` or `*mut`, and `integer` to denote any integral primitive: + + * `*T as *U` where `T, U: Sized` + * `*T as *U` TODO: explain unsized situation + * `*T as integer` + * `integer as *T` + * `number as number` + * `C-like-enum as integer` + * `bool as integer` + * `char as integer` + * `u8 as char` + * `&[T; n] as *const T` + * `fn as *T` where `T: Sized` + * `fn as integer` + +where `&.T` and `*T` are references of either mutability, +and where unsize_kind(`T`) is the kind of the unsize info +in `T` - the vtable for a trait definition (e.g. `fmt::Display` or +`Iterator`, not `Iterator`) or a length (or `()` if `T: Sized`). + +Note that lengths are not adjusted when casting raw slices - +`T: *const [u16] as *const [u8]` creates a slice that only includes +half of the original memory. + +Casting is not transitive, that is, even if `e as U1 as U2` is a valid +expression, `e as U2` is not necessarily so (in fact it will only be valid if +`U1` coerces to `U2`). + +For numeric casts, there are quite a few cases to consider: + +* casting between two integers of the same size (e.g. i32 -> u32) is a no-op +* casting from a larger integer to a smaller integer (e.g. u32 -> u8) will truncate +* casting from a smaller integer to a larger integer (e.g. u8 -> u32) will + * zero-extend if the source is unsigned + * sign-extend if the source is signed +* casting from a float to an integer will round the float towards zero + * **NOTE: currently this will cause Undefined Behaviour if the rounded + value cannot be represented by the target integer type**. This is a bug + and will be fixed. (TODO: figure out what Inf and NaN do) +* casting from an integer to float will produce the floating point representation + of the integer, rounded if necessary (rounding strategy unspecified). +* casting from an f32 to an f64 is perfect and lossless. +* casting from an f64 to an f32 will produce the closest possible value + (rounding strategy unspecified). + * **NOTE: currently this will cause Undefined Behaviour if the value + is finite but larger or smaller than the largest or smallest finite + value representable by f32**. This is a bug and will be fixed. diff --git a/checked-uninit.md b/checked-uninit.md new file mode 100644 index 0000000000000..e39a329bfd29b --- /dev/null +++ b/checked-uninit.md @@ -0,0 +1,109 @@ +% Checked Uninitialized Memory + +Like C, all stack variables in Rust are 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; + + if true { + x = 1; + } else { + x = 2; + } + + println!("{}", x); +} +``` + +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 is now logically uninitialized because Box isn't 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 +a value, 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 hidden +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 danger. diff --git a/coercions.md b/coercions.md new file mode 100644 index 0000000000000..fad9b09c3c38d --- /dev/null +++ b/coercions.md @@ -0,0 +1,72 @@ +% Coercions + +Types can implicitly be coerced to change in certain contexts. These changes are +generally just *weakening* of types, largely focused around pointers and lifetimes. +They mostly exist to make Rust "just work" in more cases, and are largely harmless. + +Here's all the kinds of coercion: + + +Coercion is allowed between the following types: + +* Subtyping: `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) + of `U` +* Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` +* Pointer Weakening: + * `&mut T` to `&T` + * `*mut T` to `*const T` + * `&T` to `*const T` + * `&mut T` to `*mut T` +* Unsizing: `T` to `U` if `T` implements `CoerceUnsized` + +`CoerceUnsized> for Pointer where T: Unsize` is implemented +for all pointer types (including smart pointers like Box and Rc). Unsize is +only implemented automatically, and enables the following transformations: + +* `[T, ..n]` => `[T]` +* `T` => `Trait` where `T: Trait` +* `SubTrait` => `Trait` where `SubTrait: Trait` (TODO: is this now implied by the previous?) +* `Foo<..., T, ...>` => `Foo<..., U, ...>` where: + * `T: Unsize` + * `Foo` is a struct + * Only the last field has type `T` + * `T` is not part of the type of any other fields + +Coercions occur at a *coercion site*. Any location that is explicitly typed +will cause a coercion to its type. If inference is necessary, the coercion will +not be performed. Exhaustively, the coercion sites for an expression `e` to +type `U` are: + +* let statements, statics, and consts: `let x: U = e` +* Arguments to functions: `takes_a_U(e)` +* Any expression that will be returned: `fn foo() -> U { e }` +* Struct literals: `Foo { some_u: e }` +* Array literals: `let x: [U; 10] = [e, ..]` +* Tuple literals: `let x: (U, ..) = (e, ..)` +* The last expression in a block: `let x: U = { ..; e }` + +Note that we do not perform coercions when matching traits (except for +receivers, see below). If there is an impl for some type `U` and `T` coerces to +`U`, that does not constitute an implementation for `T`. For example, the +following will not type check, even though it is OK to coerce `t` to `&T` and +there is an impl for `&T`: + +```rust +trait Trait {} + +fn foo(t: X) {} + +impl<'a> Trait for &'a i32 {} + + +fn main() { + let t: &mut i32 = &mut 0; + foo(t); +} +``` + +```text +:10:5: 10:8 error: the trait `Trait` is not implemented for the type `&mut i32` [E0277] +:10 foo(t); + ^~~ +``` diff --git a/constructors.md b/constructors.md new file mode 100644 index 0000000000000..8069776c0aafc --- /dev/null +++ b/constructors.md @@ -0,0 +1,26 @@ +% Constructors + +Unlike C++, Rust does not come with a slew of 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 a 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 "copy the bits". Copy types *are* implicitly +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 implicitly initialized][uninit]. Default is basically only useful for generic +programming. In concrete contexts, 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. \ No newline at end of file diff --git a/conversions.md b/conversions.md index 25d849dfbc189..388516fc7e9e2 100644 --- a/conversions.md +++ b/conversions.md @@ -29,188 +29,3 @@ fn reinterpret(foo: Foo) -> Bar { But this is, at best, annoying to do. For common conversions, rust provides more ergonomic alternatives. - - - -# Coercions - -Types can implicitly be coerced to change in certain contexts. These changes are -generally just *weakening* of types, largely focused around pointers and lifetimes. -They mostly exist to make Rust "just work" in more cases, and are largely harmless. - -Here's all the kinds of coercion: - - -Coercion is allowed between the following types: - -* Subtyping: `T` to `U` if `T` is a [subtype](lifetimes.html#subtyping-and-variance) - of `U` -* Transitivity: `T_1` to `T_3` where `T_1` coerces to `T_2` and `T_2` coerces to `T_3` -* Pointer Weakening: - * `&mut T` to `&T` - * `*mut T` to `*const T` - * `&T` to `*const T` - * `&mut T` to `*mut T` -* Unsizing: `T` to `U` if `T` implements `CoerceUnsized` - -`CoerceUnsized> for Pointer where T: Unsize` is implemented -for all pointer types (including smart pointers like Box and Rc). Unsize is -only implemented automatically, and enables the following transformations: - -* `[T, ..n]` => `[T]` -* `T` => `Trait` where `T: Trait` -* `SubTrait` => `Trait` where `SubTrait: Trait` (TODO: is this now implied by the previous?) -* `Foo<..., T, ...>` => `Foo<..., U, ...>` where: - * `T: Unsize` - * `Foo` is a struct - * Only the last field has type `T` - * `T` is not part of the type of any other fields - -Coercions occur at a *coercion site*. Any location that is explicitly typed -will cause a coercion to its type. If inference is necessary, the coercion will -not be performed. Exhaustively, the coercion sites for an expression `e` to -type `U` are: - -* let statements, statics, and consts: `let x: U = e` -* Arguments to functions: `takes_a_U(e)` -* Any expression that will be returned: `fn foo() -> U { e }` -* Struct literals: `Foo { some_u: e }` -* Array literals: `let x: [U; 10] = [e, ..]` -* Tuple literals: `let x: (U, ..) = (e, ..)` -* The last expression in a block: `let x: U = { ..; e }` - -Note that we do not perform coercions when matching traits (except for -receivers, see below). If there is an impl for some type `U` and `T` coerces to -`U`, that does not constitute an implementation for `T`. For example, the -following will not type check, even though it is OK to coerce `t` to `&T` and -there is an impl for `&T`: - -```rust -trait Trait {} - -fn foo(t: X) {} - -impl<'a> Trait for &'a i32 {} - - -fn main() { - let t: &mut i32 = &mut 0; - foo(t); -} -``` - -```text -:10:5: 10:8 error: the trait `Trait` is not implemented for the type `&mut i32` [E0277] -:10 foo(t); - ^~~ -``` - - - - -# The Dot Operator - -The dot operator will perform a lot of magic to convert types. It will perform -auto-referencing, auto-dereferencing, and coercion until types match. - -TODO: steal information from http://stackoverflow.com/questions/28519997/what-are-rusts-exact-auto-dereferencing-rules/28552082#28552082 - - - - -# Casts - -Casts are a superset of coercions: every coercion can be explicitly invoked via a -cast, but some conversions *require* a cast. These "true casts" are generally regarded -as dangerous or problematic actions. True casts revolve around raw pointers and -the primitive numeric types. True casts aren't checked. - -Here's an exhaustive list of all the true casts. For brevity, we will use `*` -to denote either a `*const` or `*mut`, and `integer` to denote any integral primitive: - - * `*T as *U` where `T, U: Sized` - * `*T as *U` TODO: explain unsized situation - * `*T as integer` - * `integer as *T` - * `number as number` - * `C-like-enum as integer` - * `bool as integer` - * `char as integer` - * `u8 as char` - * `&[T; n] as *const T` - * `fn as *T` where `T: Sized` - * `fn as integer` - -where `&.T` and `*T` are references of either mutability, -and where unsize_kind(`T`) is the kind of the unsize info -in `T` - the vtable for a trait definition (e.g. `fmt::Display` or -`Iterator`, not `Iterator`) or a length (or `()` if `T: Sized`). - -Note that lengths are not adjusted when casting raw slices - -`T: *const [u16] as *const [u8]` creates a slice that only includes -half of the original memory. - -Casting is not transitive, that is, even if `e as U1 as U2` is a valid -expression, `e as U2` is not necessarily so (in fact it will only be valid if -`U1` coerces to `U2`). - -For numeric casts, there are quite a few cases to consider: - -* casting between two integers of the same size (e.g. i32 -> u32) is a no-op -* casting from a larger integer to a smaller integer (e.g. u32 -> u8) will truncate -* casting from a smaller integer to a larger integer (e.g. u8 -> u32) will - * zero-extend if the source is unsigned - * sign-extend if the source is signed -* casting from a float to an integer will round the float towards zero - * **NOTE: currently this will cause Undefined Behaviour if the rounded - value cannot be represented by the target integer type**. This is a bug - and will be fixed. (TODO: figure out what Inf and NaN do) -* casting from an integer to float will produce the floating point representation - of the integer, rounded if necessary (rounding strategy unspecified). -* casting from an f32 to an f64 is perfect and lossless. -* casting from an f64 to an f32 will produce the closest possible value - (rounding strategy unspecified). - * **NOTE: currently this will cause Undefined Behaviour if the value - is finite but larger or smaller than the largest or smallest finite - value representable by f32**. This is a bug and will be fixed. - - - - - -# Conversion Traits - -TODO? - - - - -# Transmuting Types - -Get out of our way type system! We're going to reinterpret these bits or die -trying! Even though this book is all about doing things that are unsafe, I really -can't emphasize that you should deeply think about finding Another Way than the -operations covered in this section. This is really, truly, the most horribly -unsafe thing you can do in Rust. The railguards here are dental floss. - -`mem::transmute` takes a value of type `T` and reinterprets it to have -type `U`. The only restriction is that the `T` and `U` are verified to have the -same size. The ways to cause Undefined Behaviour with this are mind boggling. - -* First and foremost, creating an instance of *any* type with an invalid state - is going to cause arbitrary chaos that can't really be predicted. -* Transmute has an overloaded return type. If you do not specify the return type - it may produce a surprising type to satisfy inference. -* Making a primitive with an invalid value is UB -* Transmuting between non-repr(C) types is UB -* Transmuting an & to &mut is UB -* Transmuting to a reference without an explicitly provided lifetime - produces an [unbound lifetime](lifetimes.html#unbounded-lifetimes) - -`mem::transmute_copy` somehow manages to be *even more* wildly unsafe than -this. It copies `size_of` bytes out of an `&T` and interprets them as a `U`. -The size check that `mem::transmute` has is gone (as it may be valid to copy -out a prefix), though it is Undefined Behaviour for `U` to be larger than `T`. - -Also of course you can get most of the functionality of these functions using -pointer casts. diff --git a/data.md b/data.md index 599415bfe4b95..88d169c3709aa 100644 --- a/data.md +++ b/data.md @@ -3,295 +3,3 @@ Low-level programming cares a lot about data layout. It's a big deal. It also pervasively influences the rest of the language, so we're going to start by digging into how data is represented in Rust. - - - - -# The Rust repr - -Rust gives you the following ways to lay out composite data: - -* structs (named product types) -* tuples (anonymous product types) -* arrays (homogeneous product types) -* enums (named sum types -- tagged unions) - -An enum is said to be *C-like* if none of its variants have associated data. - -For all these, individual fields are aligned to their preferred alignment. For -primitives this is usually equal to their size. For instance, a u32 will be -aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 -bits. Composite structures will have a preferred alignment equal to the maximum -of their fields' preferred alignment, and a size equal to a multiple of their -preferred alignment. This ensures that arrays of T can be correctly iterated -by offsetting by their size. So for instance, - -```rust -struct A { - a: u8, - c: u32, - b: u16, -} -``` - -will have a size that is a multiple of 32-bits, and 32-bit alignment. - -There is *no indirection* for these types; all data is stored contiguously as you would -expect in C. However with the exception of arrays (which are densely packed and -in-order), the layout of data is not by default specified in Rust. Given the two -following struct definitions: - -```rust -struct A { - a: i32, - b: u64, -} - -struct B { - x: i32, - b: u64, -} -``` - -Rust *does* guarantee that two instances of A have their data laid out in exactly -the same way. However Rust *does not* guarantee that an instance of A has the same -field ordering or padding as an instance of B (in practice there's no *particular* -reason why they wouldn't, other than that its not currently guaranteed). - -With A and B as written, this is basically nonsensical, but several other features -of Rust make it desirable for the language to play with data layout in complex ways. - -For instance, consider this struct: - -```rust -struct Foo { - count: u16, - data1: T, - data2: U, -} -``` - -Now consider the monomorphizations of `Foo` and `Foo`. If Rust lays out the -fields in the order specified, we expect it to *pad* the values in the struct to satisfy -their *alignment* requirements. So if Rust didn't reorder fields, we would expect Rust to -produce the following: - -```rust -struct Foo { - count: u16, - data1: u16, - data2: u32, -} - -struct Foo { - count: u16, - _pad1: u16, - data1: u32, - data2: u16, - _pad2: u16, -} -``` - -The latter case quite simply wastes space. An optimal use of space therefore requires -different monomorphizations to have *different field orderings*. - -**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0** - -Enums make this consideration even more complicated. Naively, an enum such as: - -```rust -enum Foo { - A(u32), - B(u64), - C(u8), -} -``` - -would be laid out as: - -```rust -struct FooRepr { - data: u64, // this is *really* either a u64, u32, or u8 based on `tag` - tag: u8, // 0 = A, 1 = B, 2 = C -} -``` - -And indeed this is approximately how it would be laid out in general -(modulo the size and position of `tag`). However there are several cases where -such a representation is ineffiecient. The classic case of this is Rust's -"null pointer optimization". Given a pointer that is known to not be null -(e.g. `&u32`), an enum can *store* a discriminant bit *inside* the pointer -by using null as a special value. The net result is that -`size_of::>() == size_of::<&T>()` - -There are many types in Rust that are, or contain, "not null" pointers such as -`Box`, `Vec`, `String`, `&T`, and `&mut T`. Similarly, one can imagine -nested enums pooling their tags into a single descriminant, as they are by -definition known to have a limited range of valid values. In principle enums can -use fairly elaborate algorithms to cache bits throughout nested types with -special constrained representations. As such it is *especially* desirable that -we leave enum layout unspecified today. - - - - -# Dynamically Sized Types (DSTs) - -Rust also supports types without a statically known size. On the surface, -this is a bit nonsensical: Rust *must* know the size of something in order to -work with it! DSTs are generally produced as views, or through type-erasure -of types that *do* have a known size. Due to their lack of a statically known -size, these types can only exist *behind* some kind of pointer. They consequently -produce a *fat* pointer consisting of the pointer and the information that -*completes* them. - -For instance, the slice type, `[T]`, is some statically unknown number of elements -stored contiguously. `&[T]` consequently consists of a `(&T, usize)` pair that specifies -where the slice starts, and how many elements it contains. Similarly, Trait Objects -support interface-oriented type erasure through a `(data_ptr, vtable_ptr)` pair. - -Structs can actually store a single DST directly as their last field, but this -makes them a DST as well: - -```rust -// Can't be stored on the stack directly -struct Foo { - info: u32, - data: [u8], -} -``` - -**NOTE: As of Rust 1.0 struct DSTs are broken if the last field has -a variable position based on its alignment.** - - - -# Zero Sized Types (ZSTs) - -Rust actually allows types to be specified that occupy *no* space: - -```rust -struct Foo; // No fields = no size -enum Bar; // No variants = no size - -// All fields have no size = no size -struct Baz { - foo: Foo, - bar: Bar, - qux: (), // empty tuple has no size -} -``` - -On their own, ZSTs are, for obvious reasons, pretty useless. However -as with many curious layout choices in Rust, their potential is realized in a generic -context. - -Rust largely understands that any operation that produces or stores a ZST -can be reduced to a no-op. For instance, a `HashSet` can be effeciently implemented -as a thin wrapper around `HashMap` because all the operations `HashMap` normally -does to store and retrieve keys will be completely stripped in monomorphization. - -Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. - -Safe code need not worry about ZSTs, but *unsafe* code must be careful about the -consequence of types with no size. In particular, pointer offsets are no-ops, and -standard allocators (including jemalloc, the one used by Rust) generally consider -passing in `0` as Undefined Behaviour. - - - - -# Drop Flags - -For unfortunate legacy implementation reasons, Rust as of 1.0.0 will do a nasty trick to -any type that implements the `Drop` trait (has a destructor): it will insert a secret field -in the type. That is, - -```rust -struct Foo { - a: u32, - b: u32, -} - -impl Drop for Foo { - fn drop(&mut self) { } -} -``` - -will cause Foo to secretly become: - -```rust -struct Foo { - a: u32, - b: u32, - _drop_flag: u8, -} -``` - -For details as to *why* this is done, and how to make it not happen, check out -[TODO: SOME OTHER SECTION]. - - - - -# Alternative representations - -Rust allows you to specify alternative data layout strategies from the default. - - - - -## repr(C) - -This is the most important `repr`. It has fairly simple intent: do what C does. -The order, size, and alignment of fields is exactly what you would expect from -C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, -as C is the lingua-franca of the programming world. This is also necessary -to soundly do more elaborate tricks with data layout such as reintepretting values -as a different type. - -However, the interaction with Rust's more exotic data layout features must be kept -in mind. Due to its dual purpose as "for FFI" and "for layout control", `repr(C)` -can be applied to types that will be nonsensical or problematic if passed through -the FFI boundary. - -* ZSTs are still zero-sized, even though this is not a standard behaviour - in C, and is explicitly contrary to the behaviour of an empty type in C++, which - still consumes a byte of space. - -* DSTs, tuples, and tagged unions are not a concept in C and as such are never - FFI safe. - -* **The drop flag will still be added** - -* This is equivalent to `repr(u32)` for enums (see below) - - - - -## repr(packed) - -`repr(packed)` forces rust to strip any padding, and only align the type to a -byte. This may improve the memory footprint, but will likely have other -negative side-effects. - -In particular, most architectures *strongly* prefer values to be aligned. This -may mean the unaligned loads are penalized (x86), or even fault (ARM). In -particular, the compiler may have trouble with references to unaligned fields. - -`repr(packed)` is not to be used lightly. Unless you have extreme requirements, -this should not be used. - -This repr is a modifier on `repr(C)` and `repr(rust)`. - - - - -## repr(u8), repr(u16), repr(u32), repr(u64) - -These specify the size to make a C-like enum. If the discriminant overflows the -integer it has to fit in, it will be an error. You can manually ask Rust to -allow this by setting the overflowing element to explicitly be 0. However Rust -will not allow you to create an enum where two variants. - -These reprs have no affect on a struct or non-C-like enum. diff --git a/destructors.md b/destructors.md new file mode 100644 index 0000000000000..3bc75c132bf69 --- /dev/null +++ b/destructors.md @@ -0,0 +1,140 @@ +% Destructors + +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 `self`**. This is a +convenience feature so that you don't have to write "destructor boilerplate" to drop +children. If a struct has no special logic for being dropped other than dropping its +children, then it means `Drop` doesn't need to be implemented at all! + +**There is no stable way to prevent this behaviour in Rust 1.0**. + +Note that taking `&mut self` means that even if you *could* suppress recursive Drop, +Rust will prevent you from e.g. moving fields out of self. For most types, this +is totally fine. + +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 immediately marked as uninitialized. + +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); + } + } +} +``` + +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* an instance stores the Next variant. + +In general this works really nice because you don't need to worry about adding/removing +drops 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 overriding recursive drop and allowing moving out +of Self during `drop` 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` + // field 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 destructor. 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 what you should reach for by default. +However, in the future we expect there to be a first-class way to announce that +a field shouldn't be automatically dropped. \ No newline at end of file diff --git a/dot-operator.md b/dot-operator.md new file mode 100644 index 0000000000000..5d2010d15a803 --- /dev/null +++ b/dot-operator.md @@ -0,0 +1,6 @@ +% The Dot Operator + +The dot operator will perform a lot of magic to convert types. It will perform +auto-referencing, auto-dereferencing, and coercion until types match. + +TODO: steal information from http://stackoverflow.com/questions/28519997/what-are-rusts-exact-auto-dereferencing-rules/28552082#28552082 diff --git a/exotic-sizes.md b/exotic-sizes.md new file mode 100644 index 0000000000000..8e05485055f77 --- /dev/null +++ b/exotic-sizes.md @@ -0,0 +1,69 @@ +% Exotically Sized Types + +Most of the time, we think in terms of types with a fixed, positive size. This +is not always the case, however. + +# Dynamically Sized Types (DSTs) + +Rust also supports types without a statically known size. On the surface, +this is a bit nonsensical: Rust *must* know the size of something in order to +work with it! DSTs are generally produced as views, or through type-erasure +of types that *do* have a known size. Due to their lack of a statically known +size, these types can only exist *behind* some kind of pointer. They consequently +produce a *fat* pointer consisting of the pointer and the information that +*completes* them. + +For instance, the slice type, `[T]`, is some statically unknown number of elements +stored contiguously. `&[T]` consequently consists of a `(&T, usize)` pair that specifies +where the slice starts, and how many elements it contains. Similarly, Trait Objects +support interface-oriented type erasure through a `(data_ptr, vtable_ptr)` pair. + +Structs can actually store a single DST directly as their last field, but this +makes them a DST as well: + +```rust +// Can't be stored on the stack directly +struct Foo { + info: u32, + data: [u8], +} +``` + +**NOTE: As of Rust 1.0 struct DSTs are broken if the last field has +a variable position based on its alignment.** + + + +# Zero Sized Types (ZSTs) + +Rust actually allows types to be specified that occupy *no* space: + +```rust +struct Foo; // No fields = no size +enum Bar; // No variants = no size + +// All fields have no size = no size +struct Baz { + foo: Foo, + bar: Bar, + qux: (), // empty tuple has no size +} +``` + +On their own, ZSTs are, for obvious reasons, pretty useless. However +as with many curious layout choices in Rust, their potential is realized in a generic +context. + +Rust largely understands that any operation that produces or stores a ZST +can be reduced to a no-op. For instance, a `HashSet` can be effeciently implemented +as a thin wrapper around `HashMap` because all the operations `HashMap` normally +does to store and retrieve keys will be completely stripped in monomorphization. + +Similarly `Result<(), ()>` and `Option<()>` are effectively just fancy `bool`s. + +Safe code need not worry about ZSTs, but *unsafe* code must be careful about the +consequence of types with no size. In particular, pointer offsets are no-ops, and +standard allocators (including jemalloc, the one used by Rust) generally consider +passing in `0` as Undefined Behaviour. + + diff --git a/hrtb.md b/hrtb.md new file mode 100644 index 0000000000000..c3f25026ef48c --- /dev/null +++ b/hrtb.md @@ -0,0 +1,72 @@ +% Higher-Rank Trait Bounds (HRTBs) + +Rust's Fn traits are a little bit magic. For instance, we can write the +following code: + +```rust +struct Closure { + data: (u8, u16), + func: F, +} + +impl Closure + where F: Fn(&(u8, u16)) -> &u8, +{ + fn call(&self) -> &u8 { + (self.func)(&self.data) + } +} + +fn do_it(data: &(u8, u16)) -> &u8 { &data.0 } + +fn main() { + let clo = Closure { data: (0, 1), func: do_it }; + println!("{}", clo.call()); +} +``` + +If we try to naively desugar this code in the same way that we did in the +lifetimes section, we run into some trouble: + +```rust +struct Closure { + data: (u8, u16), + func: F, +} + +impl Closure + // where F: Fn(&'??? (u8, u16)) -> &'??? u8, +{ + fn call<'a>(&'a self) -> &'a u8 { + (self.func)(&self.data) + } +} + +fn do_it<'b>(data: &'b (u8, u16)) -> &'b u8 { &'b data.0 } + +fn main() { + 'x: { + let clo = Closure { data: (0, 1), func: do_it }; + println!("{}", clo.call()); + } +} +``` + +How on earth are we supposed to express the lifetimes on F's trait bound? We need +to provide some lifetime there, but the lifetime we care about can't be named until +we enter the body of `call`! Also, that isn't some fixed lifetime; call works with +*any* lifetime `&self` happens to have at that point. + +This job requires The Magic of Higher-Rank Trait Bounds. The way we desugar +this is as follows: + +```rust +where for<'a> F: Fn(&'a (u8, u16)) -> &'a u8, +``` + +(Where `Fn(a, b, c) -> d` is itself just sugar for the unstable *real* Fn trait) + +`for<'a>` can be read as "for all choices of `'a`", and basically produces an +*inifinite list* of trait bounds that F must satisfy. Intense. There aren't many +places outside of the Fn traits where we encounter HRTBs, and even for those we +have a nice magic sugar for the common cases. \ No newline at end of file diff --git a/leaking.md b/leaking.md new file mode 100644 index 0000000000000..5d66b1a424c45 --- /dev/null +++ b/leaking.md @@ -0,0 +1,229 @@ +% Leaking + +Ownership based resource management is intended to simplify composition. You +acquire resources when you create the object, and you release the resources +when it gets destroyed. Since destruction is handled for you, it means you +can't forget to release the resources, and it happens as soon as possible! +Surely this is perfect and all of our problems are solved. + +Everything is terrible and we have new and exotic problems to try to solve. + +Many people like to believe that Rust eliminates resource leaks, but this +is absolutely not the case, no matter how you look at it. In the strictest +sense, "leaking" is so abstract as to be unpreventable. It's quite trivial +to initialize a collection at the start of a program, fill it with tons of +objects with destructors, and then enter an infinite event loop that never +refers to it. The collection will sit around uselessly, holding on to its +precious resources until the program terminates (at which point all those +resources would have been reclaimed by the OS anyway). + +We may consider a more restricted form of leak: failing to drop a value that +is unreachable. Rust also doesn't prevent this. In fact Rust has a *function +for doing this*: `mem::forget`. This function consumes the value it is passed +*and then doesn't run its destructor*. + +In the past `mem::forget` was marked as unsafe as a sort of lint against using +it, since failing to call a destructor is generally not a well-behaved thing to +do (though useful for some special unsafe code). However this was generally +determined to be an untenable stance to take: there are *many* ways to fail to +call a destructor in safe code. The most famous example is creating a cycle +of reference counted pointers using interior mutability. + +It is reasonable for safe code to assume that destructor leaks do not happen, +as any program that leaks destructors is probably wrong. However *unsafe* code +cannot rely on destructors to be run to be *safe*. For most types this doesn't +matter: if you leak the destructor then the type is *by definition* inaccessible, +so it doesn't matter, right? For instance, if you leak a `Box` then you +waste some memory but that's hardly going to violate memory-safety. + +However where we must be careful with destructor leaks are *proxy* types. +These are types which manage access to a distinct object, but don't actually +own it. Proxy objects are quite rare. Proxy objects you'll need to care about +are even rarer. However we'll focus on three interesting examples in the +standard library: + +* `vec::Drain` +* `Rc` +* `thread::scoped::JoinGuard` + + + +## Drain + +`drain` is a collections API that moves data out of the container without +consuming the container. This enables us to reuse the allocation of a `Vec` +after claiming ownership over all of its contents. It produces an iterator +(Drain) that returns the contents of the Vec by-value. + +Now, consider Drain in the middle of iteration: some values have been moved out, +and others haven't. This means that part of the Vec is now full of logically +uninitialized data! We could backshift all the elements in the Vec every time we +remove a value, but this would have pretty catastrophic performance consequences. + +Instead, we would like Drain to *fix* the Vec's backing storage when it is +dropped. It should run itself to completion, backshift any elements that weren't +removed (drain supports subranges), and then fix Vec's `len`. It's even +unwinding-safe! Easy! + +Now consider the following: + +``` +let mut vec = vec![Box::new(0); 4]; + +{ + // start draining, vec can no longer be accessed + let mut drainer = vec.drain(..); + + // pull out two elements and immediately drop them + drainer.next(); + drainer.next(); + + // get rid of drainer, but don't call its destructor + mem::forget(drainer); +} + +// Oops, vec[0] was dropped, we're reading a pointer into free'd memory! +println!("{}", vec[0]); +``` + +This is pretty clearly Not Good. Unfortunately, we're kind've stuck between +a rock and a hard place: maintaining consistent state at every step has +an enormous cost (and would negate any benefits of the API). Failing to maintain +consistent state gives us Undefined Behaviour in safe code (making the API +unsound). + +So what can we do? Well, we can pick a trivially consistent state: set the Vec's +len to be 0 when we *start* the iteration, and fix it up if necessary in the +destructor. That way, if everything executes like normal we get the desired +behaviour with minimal overhead. But if someone has the *audacity* to mem::forget +us in the middle of the iteration, all that does is *leak even more* (and possibly +leave the Vec in an *unexpected* but consistent state). Since we've +accepted that mem::forget is safe, this is definitely safe. We call leaks causing +more leaks a *leak amplification*. + + + + +## Rc + +Rc is an interesting case because at first glance it doesn't appear to be a +proxy value at all. After all, it manages the data it points to, and dropping +all the Rcs for a value will drop that value. leaking an Rc doesn't seem like +it would be particularly dangerous. It will leave the refcount permanently +incremented and prevent the data from being freed or dropped, but that seems +just like Box, right? + +Nope. + +Let's consider a simplified implementation of Rc: + +```rust +struct Rc { + ptr: *mut RcBox, +} + +struct RcBox { + data: T, + ref_count: usize, +} + +impl Rc { + fn new(data: T) -> Self { + unsafe { + // Wouldn't it be nice if heap::allocate worked like this? + let ptr = heap::allocate>(); + ptr::write(ptr, RcBox { + data: data, + ref_count: 1, + }); + Rc { ptr: ptr } + } + } + + fn clone(&self) -> Self { + unsafe { + (*self.ptr).ref_count += 1; + } + Rc { ptr: self.ptr } + } +} + +impl Drop for Rc { + fn drop(&mut self) { + unsafe { + let inner = &mut ; + (*self.ptr).ref_count -= 1; + if (*self.ptr).ref_count == 0 { + // drop the data and then free it + ptr::read(self.ptr); + heap::deallocate(self.ptr); + } + } + } +} +``` + +This code contains an implicit and subtle assumption: ref_count can fit in a +`usize`, because there can't be more than `usize::MAX` Rcs in memory. However +this itself assumes that the ref_count accurately reflects the number of Rcs +in memory, which we know is false with mem::forget. Using mem::forget we can +overflow the ref_count, and then get it down to 0 with outstanding Rcs. Then we +can happily use-after-free the inner data. Bad Bad Not Good. + +This can be solved by *saturating* the ref_count, which is sound because +decreasing the refcount by `n` still requires `n` Rcs simultaneously living +in memory. + + + + +## thread::scoped::JoinGuard + +The thread::scoped API intends to allow threads to be spawned that reference +data on the stack without any synchronization over that data. Usage looked like: + +```rust +let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; +{ + let guards = vec![]; + for x in &mut data { + // Move the mutable reference into the closure, and execute + // it on a different thread. The closure has a lifetime bound + // by the lifetime of the mutable reference `x` we store in it. + // The guard that is returned is in turn assigned the lifetime + // of the closure, so it also mutably borrows `data` as `x` did. + // This means we cannot access `data` until the guard goes away. + let guard = thread::scoped(move || { + *x *= 2; + }); + // store the thread's guard for later + guards.push(guard); + } + // All guards are dropped here, forcing the threads to join + // (this thread blocks here until the others terminate). + // Once the threads join, the borrow expires and the data becomes + // accessible again in this thread. +} +// data is definitely mutated here. +``` + +In principle, this totally works! Rust's ownership system perfectly ensures it! +...except it relies on a destructor being called to be safe. + +``` +let mut data = Box::new(0); +{ + let guard = thread::scoped(|| { + // This is at best a data race. At worst, it's *also* a use-after-free. + *data += 1; + }); + // Because the guard is forgotten, expiring the loan without blocking this + // thread. + mem::forget(guard); +} +// So the Box is dropped here while the scoped thread may or may not be trying +// to access it. +``` + +Dang. Here the destructor running was pretty fundamental to the API, and it had +to be scrapped in favour of a completely different design. \ No newline at end of file diff --git a/lifetime-elision.md b/lifetime-elision.md new file mode 100644 index 0000000000000..eac24330911f4 --- /dev/null +++ b/lifetime-elision.md @@ -0,0 +1,64 @@ +% Lifetime Elision + +In order to make common patterns more ergonomic, Rust allows lifetimes to be +*elided* in function signatures. + +A *lifetime position* is anywhere you can write a lifetime in a type: + +```rust +&'a T +&'a mut T +T<'a> +``` + +Lifetime positions can appear as either "input" or "output": + +* For `fn` definitions, input refers to the types of the formal arguments + in the `fn` definition, while output refers to + result types. So `fn foo(s: &str) -> (&str, &str)` has elided one lifetime in + input position and two lifetimes in output position. + Note that the input positions of a `fn` method definition do not + include the lifetimes that occur in the method's `impl` header + (nor lifetimes that occur in the trait header, for a default method). + +* In the future, it should be possible to elide `impl` headers in the same manner. + +Elision rules are as follows: + +* Each elided lifetime in input position becomes a distinct lifetime + parameter. + +* If there is exactly one input lifetime position (elided or not), that lifetime + is assigned to *all* elided output lifetimes. + +* If there are multiple input lifetime positions, but one of them is `&self` or + `&mut self`, the lifetime of `self` is assigned to *all* elided output lifetimes. + +* Otherwise, it is an error to elide an output lifetime. + +Examples: + +```rust +fn print(s: &str); // elided +fn print<'a>(s: &'a str); // expanded + +fn debug(lvl: uint, s: &str); // elided +fn debug<'a>(lvl: uint, s: &'a str); // expanded + +fn substr(s: &str, until: uint) -> &str; // elided +fn substr<'a>(s: &'a str, until: uint) -> &'a str; // expanded + +fn get_str() -> &str; // ILLEGAL + +fn frob(s: &str, t: &str) -> &str; // ILLEGAL + +fn get_mut(&mut self) -> &mut T; // elided +fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded + +fn args(&mut self, args: &[T]) -> &mut Command // elided +fn args<'a, 'b, T:ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command // expanded + +fn new(buf: &mut [u8]) -> BufWriter; // elided +fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded + +``` \ No newline at end of file diff --git a/lifetime-misc.md b/lifetime-misc.md new file mode 100644 index 0000000000000..faf7f9a1f60b0 --- /dev/null +++ b/lifetime-misc.md @@ -0,0 +1,229 @@ +% misc + +This is just a dumping ground while I work out what to do with this stuff + + +# PhantomData + +When working with unsafe code, we can often end up in a situation where +types or lifetimes are logically associated with a struct, but not actually +part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` +for `&'a [T]` is (approximately) defined as follows: + +```rust +pub struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, +} +``` + +However because `'a` is unused within the struct's body, it's *unbound*. +Because of the troubles this has historically caused, unbound lifetimes and +types are *illegal* in struct definitions. Therefore we must somehow refer +to these types in the body. Correctly doing this is necessary to have +correct variance and drop checking. + +We do this using *PhantomData*, which is a special marker type. PhantomData +consumes no space, but simulates a field of the given type for the purpose of +static analysis. This was deemed to be less error-prone than explicitly telling +the type-system the kind of variance that you want, while also providing other +useful information. + +Iter logically contains `&'a T`, so this is exactly what we tell +the PhantomData to simulate: + +``` +pub struct Iter<'a, T: 'a> { + ptr: *const T, + end: *const T, + _marker: marker::PhantomData<&'a T>, +} +``` + + + + +# Dropck + +When a type is going out of scope, Rust will try to Drop it. Drop executes +arbitrary code, and in fact allows us to "smuggle" arbitrary code execution +into many places. As such additional soundness checks (dropck) are necessary to +ensure that a type T can be safely instantiated and dropped. It turns out that we +*really* don't need to care about dropck in practice, as it often "just works". + +However the one exception is with PhantomData. Given a struct like Vec: + +``` +struct Vec { + data: *const T, // *const for variance! + len: usize, + cap: usize, +} +``` + +dropck will generously determine that Vec does not own any values of +type T. This will unfortunately allow people to construct unsound Drop +implementations that access data that has already been dropped. In order to +tell dropck that we *do* own values of type T, and may call destructors of that +type, we must add extra PhantomData: + +``` +struct Vec { + data: *const T, // *const for covariance! + len: usize, + cap: usize, + _marker: marker::PhantomData, +} +``` + +Raw pointers that own an allocation is such a pervasive pattern that the +standard library made a utility for itself called `Unique` which: + +* wraps a `*const T`, +* includes a `PhantomData`, +* auto-derives Send/Sync as if T was contained +* marks the pointer as NonZero for the null-pointer optimization + + + + +# Splitting Lifetimes + +The mutual exclusion property of mutable references can be very limiting when +working with a composite structure. The borrow checker understands some basic stuff, but +will fall over pretty easily. It *does* understand structs sufficiently to +know that it's possible to borrow disjoint fields of a struct simultaneously. +So this works today: + +```rust +struct Foo { + a: i32, + b: i32, + c: i32, +} + +let mut x = Foo {a: 0, b: 0, c: 0}; +let a = &mut x.a; +let b = &mut x.b; +let c = &x.c; +*b += 1; +let c2 = &x.c; +*a += 10; +println!("{} {} {} {}", a, b, c, c2); +``` + +However borrowck doesn't understand arrays or slices in any way, so this doesn't +work: + +```rust +let x = [1, 2, 3]; +let a = &mut x[0]; +let b = &mut x[1]; +println!("{} {}", a, b); +``` + +```text +:3:18: 3:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:3 let a = &mut x[0]; + ^~~~ +:4:18: 4:22 error: cannot borrow immutable indexed content `x[..]` as mutable +:4 let b = &mut x[1]; + ^~~~ +error: aborting due to 2 previous errors +``` + +While it was plausible that borrowck could understand this simple case, it's +pretty clearly hopeless for borrowck to understand disjointness in general +container types like a tree, especially if distinct keys actually *do* map +to the same value. + +In order to "teach" borrowck that what we're doing is ok, we need to drop down +to unsafe code. For instance, mutable slices expose a `split_at_mut` function that +consumes the slice and returns *two* mutable slices. One for everything to the +left of the index, and one for everything to the right. Intuitively we know this +is safe because the slices don't alias. However the implementation requires some +unsafety: + +```rust +fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { + unsafe { + let self2: &mut [T] = mem::transmute_copy(&self); + + (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), + ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) + } +} +``` + +This is pretty plainly dangerous. We use transmute to duplicate the slice with an +*unbounded* lifetime, so that it can be treated as disjoint from the other until +we unify them when we return. + +However more subtle is how iterators that yield mutable references work. +The iterator trait is defined as follows: + +```rust +trait Iterator { + type Item; + + fn next(&mut self) -> Option; +} +``` + +Given this definition, Self::Item has *no* connection to `self`. This means +that we can call `next` several times in a row, and hold onto all the results +*concurrently*. This is perfectly fine for by-value iterators, which have exactly +these semantics. It's also actually fine for shared references, as they admit +arbitrarily many references to the same thing (although the +iterator needs to be a separate object from the thing being shared). But mutable +references make this a mess. At first glance, they might seem completely +incompatible with this API, as it would produce multiple mutable references to +the same object! + +However it actually *does* work, exactly because iterators are one-shot objects. +Everything an IterMut yields will be yielded *at most* once, so we don't *actually* +ever yield multiple mutable references to the same piece of data. + +In general all mutable iterators require *some* unsafe code *somewhere*, though. +Whether it's raw pointers, or safely composing on top of *another* IterMut. + +For instance, VecDeque's IterMut: + +```rust +pub struct IterMut<'a, T:'a> { + // The whole backing array. Some of these indices are initialized! + ring: &'a mut [T], + tail: usize, + head: usize, +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option<&'a mut T> { + if self.tail == self.head { + return None; + } + let tail = self.tail; + self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); + + unsafe { + // might as well do unchecked indexing since wrap_index has us + // in-bounds, and many of the "middle" indices are uninitialized + // anyway. + let elem = self.ring.get_unchecked_mut(tail); + + // round-trip through a raw pointer to unbound the lifetime from + // ourselves + Some(&mut *(elem as *mut _)) + } + } +} +``` + +A very subtle but interesting detail in this design is that it *relies on +privacy to be sound*. Borrowck works on some very simple rules. One of those rules +is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut +Bar is *also* live. Since IterMut is always live when `next` can be called, if +`ring` were public then we could mutate `ring` while outstanding mutable borrows +to it exist! diff --git a/lifetime-mismatch.md b/lifetime-mismatch.md new file mode 100644 index 0000000000000..93ecb51c010db --- /dev/null +++ b/lifetime-mismatch.md @@ -0,0 +1,81 @@ +% Limits of Lifetimes + +Given the following code: + +```rust,ignore +struct Foo; + +impl Foo { + fn mutate_and_share(&mut self) -> &Self { &*self } + fn share(&self) {} +} + +fn main() { + let mut foo = Foo; + let loan = foo.mutate_and_share(); + foo.share(); +} +``` + +One might expect it to compile. We call `mutate_and_share`, which mutably borrows +`foo` *temporarily*, but then returns *only* a shared reference. Therefore we +would expect `foo.share()` to succeed as `foo` shouldn't be mutably borrowed. + +However when we try to compile it: + +```text +:11:5: 11:8 error: cannot borrow `foo` as immutable because it is also borrowed as mutable +:11 foo.share(); + ^~~ +:10:16: 10:19 note: previous borrow of `foo` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `foo` until the borrow ends +:10 let loan = foo.mutate_and_share(); + ^~~ +:12:2: 12:2 note: previous borrow ends here +:8 fn main() { +:9 let mut foo = Foo; +:10 let loan = foo.mutate_and_share(); +:11 foo.share(); +:12 } + ^ +``` + +What happened? Well, we got the exact same reasoning as we did for +[Example 2 in the previous section][ex2]. We desugar the program and we get +the following: + +```rust,ignore +struct Foo; + +impl Foo { + fn mutate_and_share<'a>(&'a mut self) -> &'a Self { &'a *self } + fn share<'a>(&'a self) {} +} + +fn main() { + 'b: { + let mut foo: Foo = Foo; + 'c: { + let loan: &'c Foo = Foo::mutate_and_share::<'c>(&'c mut foo); + 'd: { + Foo::share::<'d>(&'d foo); + } + } + } +} +``` + +The lifetime system is forced to extend the `&mut foo` to have lifetime `'c`, +due to the lifetime of `loan` and mutate_and_share's signature. Then when we +try to call `share`, and it sees we're trying to alias that `&'c mut foo` and +blows up in our face! + +This program is clearly correct according to the reference semantics we *actually* +care about, but the lifetime system is too coarse-grained to handle that. + + +TODO: other common problems? SEME regions stuff, mostly? + + + + +[ex2]: lifetimes.html#example-2:-aliasing-a-mutable-reference \ No newline at end of file diff --git a/lifetimes.md b/lifetimes.md index 976b4d53e2c91..a06363a92d739 100644 --- a/lifetimes.md +++ b/lifetimes.md @@ -1,230 +1,17 @@ -% Ownership and Lifetimes - -Ownership is the breakout feature of Rust. It allows Rust to be completely -memory-safe and efficient, while avoiding garbage collection. Before getting -into the ownership system in detail, we will consider the motivation of this -design. - -TODO: Interior Mutability section - - - - -# Living Without Garbage Collection - -We will assume that you accept that garbage collection is not always an optimal -solution, and that it is desirable to manually manage memory to some extent. -If you do not accept this, might I interest you in a different language? - -Regardless of your feelings on GC, it is pretty clearly a *massive* boon to -making code safe. You never have to worry about things going away *too soon* -(although whether you still *wanted* to be pointing at that thing is a different -issue...). This is a pervasive problem that C and C++ need to deal with. -Consider this simple mistake that all of us who have used a non-GC'd language -have made at one point: - -```rust,ignore -fn as_str(data: &u32) -> &str { - // compute the string - let s = format!("{}", data); - - // OH NO! We returned a reference to something that - // exists only in this function! - // Dangling pointer! Use after free! Alas! - // (this does not compile in Rust) - &s -} -``` - -This is exactly what Rust's ownership system was built to solve. -Rust knows the scope in which the `&s` lives, and as such can prevent it from -escaping. However this is a simple case that even a C compiler could plausibly -catch. Things get more complicated as code gets bigger and pointers get fed through -various functions. Eventually, a C compiler will fall down and won't be able to -perform sufficient escape analysis to prove your code unsound. It will consequently -be forced to accept your program on the assumption that it is correct. - -This will never happen to Rust. It's up to the programmer to prove to the -compiler that everything is sound. - -Of course, rust's story around ownership is much more complicated than just -verifying that references don't escape the scope of their referrent. That's -because ensuring pointers are always valid is much more complicated than this. -For instance in this code, - -```rust,ignore -let mut data = vec![1, 2, 3]; -// get an internal reference -let x = &data[0]; - -// OH NO! `push` causes the backing storage of `data` to be reallocated. -// Dangling pointer! User after free! Alas! -// (this does not compile in Rust) -data.push(4); - -println!("{}", x); -``` - -naive scope analysis would be insufficient to prevent this bug, because `data` -does in fact live as long as we needed. However it was *changed* while we had -a reference into it. This is why Rust requires any references to freeze the -referrent and its owners. - - - -# References - -There are two kinds of reference: - -* Shared reference: `&` -* Mutable reference: `&mut` - -Which obey the following rules: - -* A reference cannot outlive its referrent -* A mutable reference cannot be aliased - -To define aliasing, we must define the notion of *paths* and *liveness*. - - - - -## Paths - -If all Rust had were values, then every value would be uniquely owned -by a variable or composite structure. From this we naturally derive a *tree* -of ownership. The stack itself is the root of the tree, with every variable -as its direct children. Each variable's direct children would be their fields -(if any), and so on. - -From this view, every value in Rust has a unique *path* in the tree of ownership. -References to a value can subsequently be interpretted as a path in this tree. -Of particular interest are *prefixes*: `x` is a prefix of `y` if `x` owns `y` - -However much data doesn't reside on the stack, and we must also accomodate this. -Globals and thread-locals are simple enough to model as residing at the bottom -of the stack. However data on the heap poses a different problem. - -If all Rust had on the heap was data uniquely by a pointer on the stack, -then we can just treat that pointer as a struct that owns the value on -the heap. Box, Vec, String, and HashMap, are examples of types which uniquely -own data on the heap. - -Unfortunately, data on the heap is not *always* uniquely owned. Rc for instance -introduces a notion of *shared* ownership. Shared ownership means there is no -unique path. A value with no unique path limits what we can do with it. In general, only -shared references can be created to these values. However mechanisms which ensure -mutual exclusion may establish One True Owner temporarily, establishing a unique path -to that value (and therefore all its children). - -The most common way to establish such a path is through *interior mutability*, -in contrast to the *inherited mutability* that everything in Rust normally uses. -Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. These -types provide exclusive access through runtime restrictions. However it is also -possible to establish unique ownership without interior mutability. For instance, -if an Rc has refcount 1, then it is safe to mutate or move its internals. - - - - -## Liveness - -Roughly, a reference is *live* at some point in a program if it can be -dereferenced. Shared references are always live unless they are literally unreachable -(for instance, they reside in freed or leaked memory). Mutable references can be -reachable but *not* live through the process of *reborrowing*. - -A mutable reference can be reborrowed to either a shared or mutable reference. -Further, the reborrow can produce exactly the same reference, or point to a -path it is a prefix of. For instance, a mutable reference can be reborrowed -to point to a field of its referrent: - -```rust -let x = &mut (1, 2); -{ - // reborrow x to a subfield - let y = &mut x.0; - // y is now live, but x isn't - *y = 3; -} -// y goes out of scope, so x is live again -*x = (5, 7); -``` - -It is also possible to reborrow into *multiple* mutable references, as long as -they are to *disjoint*: no reference is a prefix of another. Rust -explicitly enables this to be done with disjoint struct fields, because -disjointness can be statically proven: - -``` -let x = &mut (1, 2); -{ - // reborrow x to two disjoint subfields - let y = &mut x.0; - let z = &mut x.1; - // y and z are now live, but x isn't - *y = 3; - *z = 4; -} -// y and z go out of scope, so x is live again -*x = (5, 7); -``` - -However it's often the case that Rust isn't sufficiently smart to prove that -multiple borrows are disjoint. *This does not mean it is fundamentally illegal -to make such a borrow*, just that Rust isn't as smart as you want. - -To simplify things, we can model variables as a fake type of reference: *owned* -references. Owned references have much the same semantics as mutable references: -they can be re-borrowed in a mutable or shared manner, which makes them no longer -live. Live owned references have the unique property that they can be moved -out of (though mutable references *can* be swapped out of). This is -only given to *live* owned references because moving its referrent would of -course invalidate all outstanding references prematurely. - -As a local lint against inappropriate mutation, only variables that are marked -as `mut` can be borrowed mutably. - -It is also interesting to note that Box behaves exactly like an owned -reference. It can be moved out of, and Rust understands it sufficiently to -reason about its paths like a normal variable. - - - - -## Aliasing - -With liveness and paths defined, we can now properly define *aliasing*: - -**A mutable reference is aliased if there exists another live reference to it or -one of its prefixes.** - -That's it. Super simple right? Except for the fact that it took us two pages -to define all of the terms in that defintion. You know: Super. Simple. - -Actually it's a bit more complicated than that. In addition to references, -Rust has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent -ownership or aliasing semantics. As a result, Rust makes absolutely no effort -to track that they are used correctly, and they are wildly unsafe. - -**It is an open question to what degree raw pointers have alias semantics. -However it is important for these definitions to be sound that the existence -of a raw pointer does not imply some kind of live path.** - - - - -# Lifetimes +% Lifetimes Rust enforces these rules through *lifetimes*. Lifetimes are effectively -just names for scopes on the stack, somewhere in the program. Each reference, +just names for scopes somewhere in the program. Each reference, and anything that contains a reference, is tagged with a lifetime specifying the scope it's valid for. Within a function body, Rust generally doesn't let you explicitly name the lifetimes involved. This is because it's generally not really *necessary* to talk about lifetimes in a local context; rust has all the information and -can work out everything. +can work out everything. It's also a good thing because the scope of a borrow +is often significantly smaller than the scope its referent is *actually* valid +for. Rust will introduce *many* anonymous scopes and temporaries to make your +code *just work*. However once you cross the function boundary, you need to start talking about lifetimes. Lifetimes are denoted with an apostrophe: `'a`, `'static`. To dip @@ -232,9 +19,10 @@ our toes with lifetimes, we're going to pretend that we're actually allowed to label scopes with lifetimes, and desugar the examples from the start of this chapter. -Our examples made use of *aggressive* sugar around scopes and lifetimes, -because writing everything out explicitly is *extremely noisy*. All rust code -relies on aggressive inference and elision of "obvious" things. +Our examples made use of *aggressive* sugar -- high fructose corn syrup even -- +around scopes and lifetimes, because writing everything out explicitly is +*extremely noisy*. All Rust code relies on aggressive inference and elision of +"obvious" things. One particularly interesting piece of sugar is that each `let` statement implicitly introduces a scope. For the most part, this doesn't really matter. However it @@ -247,25 +35,61 @@ let y = &x; let z = &y; ``` -becomes: +The borrow checker always tries to minimize the extent of a lifetime, so it will +likely desugar to the following: -```rust,ignore -// NOTE: `'a:` and `&'a x` is not valid syntax! +```rust +// NOTE: `'a: {` and `&'b x` is not valid syntax! 'a: { let x: i32 = 0; 'b: { - let y: &'a i32 = &'a x; + // lifetime used is 'b because that's *good enough*. + let y: &'b i32 = &'b x; 'c: { - let z: &'b &'a i32 = &'b y; + // ditto on 'c + let z: &'c &'b i32 = &'c y; } } } ``` -Wow. That's... awful. Let's all take a moment to thank Rust for being a huge -pile of sugar with sugar on top. +Wow. That's... awful. Let's all take a moment to thank Rust for being a +diabetes-inducing torrent of syrupy-goodness. -Anyway, let's look at some of those examples from before: +Actually passing references to outer scopes will cause Rust to infer +a larger lifetime: + +```rust +let x = 0; +let z; +let y = &x; +z = y; +``` + +The borrow checker always tries to minimize the extent of a lifetime, so it will +likely desugar to something like the following: + +```rust +// NOTE: `'a: {` and `&'b x` is not valid syntax! +'a: { + let x: i32 = 0; + 'b: { + let z: &'b i32; + 'c: { + // Must use 'b here because this reference is + // being passed to that scope. + let y: &'b i32 = &'b x; + z = y; + } + } +} +``` + + + +# Example: references that outlive referents + +Alright, let's look at some of those examples from before: ```rust,ignore fn as_str(data: &u32) -> &str { @@ -280,7 +104,7 @@ desugars to: fn as_str<'a>(data: &'a u32) -> &'a str { 'b: { let s = format!("{}", data); - return &'b s + return &'a s; } } ``` @@ -288,704 +112,111 @@ fn as_str<'a>(data: &'a u32) -> &'a str { This signature of `as_str` takes a reference to a u32 with *some* lifetime, and promises that it can produce a reference to a str that can live *just as long*. Already we can see why this signature might be trouble. That basically implies -that we're going to *find* a str somewhere in the scope that u32 originated in, -or somewhere *even* earlier. That's uh... a big ask. +that we're going to *find* a str somewhere in the scope the scope the reference +to the u32 originated in, or somewhere *even* earlier. That's a *bit* of a big ask. -We then proceed to compute the string `s`, and return a reference to it. -Unfortunately, since `s` was defined in the scope `'b`, the reference we're -returning can only live for that long. From the perspective of the compiler, -we've failed *twice* here. We've failed to fulfill the contract we were asked -to fulfill (`'b` is unrelated to `'a`); and we've also tried to make a reference -outlive its referrent by returning an `&'b`, where `'b` is in our function. +We then proceed to compute the string `s`, and return a reference to it. Since +the contract of our function says the reference must outlive `'a`, that's the +lifetime we infer for the reference. Unfortunately, `s` was defined in the +scope `'b`, so the only way this is sound is if `'b` contains `'a` -- which is +clearly false since `'a` must contain the function call itself. We have therefore +created a reference whose lifetime outlives its referent, which is *literally* +the first thing we said that references can't do. The compiler rightfully blows +up in our face. -Shoot! - -Of course, the right way to right this function is as follows: - -```rust -fn to_string(data: &u32) -> String { - format!("{}", data) -} -``` - -We must produce an owned value inside the function to return it! The only way -we could have returned an `&'a str` would have been if it was in a field of the -`&'a u32`, which is obviously not the case. - -(Actually we could have also just returned a string literal, though this limits -the behaviour of our function *just a bit*.) - -How about the other example: +To make this more clear, we can expand the example: ```rust,ignore -let mut data = vec![1, 2, 3]; -let x = &data[0]; -data.push(4); -println!("{}", x); -``` - -```rust,ignore -'a: { - let mut data: Vec = vec![1, 2, 3]; +fn as_str<'a>(data: &'a u32) -> &'a str { 'b: { - let x: &'a i32 = Index::index(&'a data, 0); - 'c: { - // Exactly what the desugar for Vec::push is is up to Rust. - // This particular desugar is a decent approximation for our - // purpose. In particular methods oft invoke a temporary borrow. - let temp: &'c mut Vec = &'c mut data; - // NOTE: Vec::push is not valid syntax - Vec::push(temp, 4); - } - println!("{}", x); + let s = format!("{}", data); + return &'a s } } -``` - -Here the problem is that we're trying to mutably borrow the `data` path, while -we have a reference into something it's a prefix of. Rust subsequently throws -up its hands in disgust and rejects our program. The correct way to write this -is to just re-order the code so that we make `x` *after* we push: - -TODO: convince myself of this. - -```rust -let mut data = vec![1, 2, 3]; -data.push(4); - -let x = &data[0]; -println!("{}", x); -``` - - - -# Lifetime Elision - -In order to make common patterns more ergonomic, Rust allows lifetimes to be -*elided* in function signatures. - -A *lifetime position* is anywhere you can write a lifetime in a type: - -```rust -&'a T -&'a mut T -T<'a> -``` - -Lifetime positions can appear as either "input" or "output": - -* For `fn` definitions, input refers to the types of the formal arguments - in the `fn` definition, while output refers to - result types. So `fn foo(s: &str) -> (&str, &str)` has elided one lifetime in - input position and two lifetimes in output position. - Note that the input positions of a `fn` method definition do not - include the lifetimes that occur in the method's `impl` header - (nor lifetimes that occur in the trait header, for a default method). - -* In the future, it should be possible to elide `impl` headers in the same manner. - -Elision rules are as follows: - -* Each elided lifetime in input position becomes a distinct lifetime - parameter. - -* If there is exactly one input lifetime position (elided or not), that lifetime - is assigned to *all* elided output lifetimes. - -* If there are multiple input lifetime positions, but one of them is `&self` or - `&mut self`, the lifetime of `self` is assigned to *all* elided output lifetimes. - -* Otherwise, it is an error to elide an output lifetime. - -Examples: - -```rust -fn print(s: &str); // elided -fn print<'a>(s: &'a str); // expanded - -fn debug(lvl: uint, s: &str); // elided -fn debug<'a>(lvl: uint, s: &'a str); // expanded - -fn substr(s: &str, until: uint) -> &str; // elided -fn substr<'a>(s: &'a str, until: uint) -> &'a str; // expanded - -fn get_str() -> &str; // ILLEGAL - -fn frob(s: &str, t: &str) -> &str; // ILLEGAL - -fn get_mut(&mut self) -> &mut T; // elided -fn get_mut<'a>(&'a mut self) -> &'a mut T; // expanded - -fn args(&mut self, args: &[T]) -> &mut Command // elided -fn args<'a, 'b, T:ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command // expanded - -fn new(buf: &mut [u8]) -> BufWriter; // elided -fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> // expanded - -``` - - - -# Unbounded Lifetimes - -Unsafe code can often end up producing references or lifetimes out of thin air. -Such lifetimes come into the world as *unbounded*. The most common source of this -is derefencing a raw pointer, which produces a reference with an unbounded lifetime. -Such a lifetime becomes as big as context demands. This is in fact more powerful -than simply becoming `'static`, because for instance `&'static &'a T` -will fail to typecheck, but the unbound lifetime will perfectly mold into -`&'a &'a T` as needed. However for most intents and purposes, such an unbounded -lifetime can be regarded as `'static`. - -Almost no reference is `'static`, so this is probably wrong. `transmute` and -`transmute_copy` are the two other primary offenders. One should endeavour to -bound an unbounded lifetime as quick as possible, especially across function -boundaries. - -Given a function, any output lifetimes that don't derive from inputs are -unbounded. For instance: - -``` -fn get_str<'a>() -> &'a str; -``` - -will produce an `&str` with an unbounded lifetime. The easiest way to avoid -unbounded lifetimes is to use lifetime elision at the function boundary. -If an output lifetime is elided, then it *must* be bounded by an input lifetime. -Of course, it might be bounded by the *wrong* lifetime, but this will usually -just cause a compiler error, rather than allow memory safety to be trivially -violated. - -Within a function, bounding lifetimes is more error-prone. The safest and easiest -way to bound a lifetime is to return it from a function with a bound lifetime. -However if this is unacceptable, the reference can be placed in a location with -a specific lifetime. Unfortunately it's impossible to name all lifetimes involved -in a function. To get around this, you can in principle use `copy_lifetime`, though -these are unstable due to their awkward nature and questionable utility. - - - - - -# Higher-Rank Trait Bounds - -// TODO: make aturon less mad - -Generics in Rust generally allow types to be instantiated with arbitrary -associated lifetimes, but this fixes the lifetimes they work with once -instantiated. For almost all types, this is exactly the desired behaviour. -For example slice::Iter can work with arbitrary lifetimes, determined by the -slice that instantiates it. However *once* Iter is instantiated the lifetimes -it works with cannot be changed. It returns references that live for some -particular `'a`. - -However some types are more flexible than this. In particular, a single -instantiation of a function can process arbitrary lifetimes: - -```rust -fn identity(input: &u8) -> &u8 { input } -``` - -What is *the* lifetime that identity works with? There is none. If you think -this is "cheating" because functions are statically instantiated, then you need -only consider the equivalent closure: - -```rust -let identity = |input: &u8| input; -``` - -These functions are *higher ranked* over the lifetimes they work with. This means -that they're generic over what they handle *after instantiation*. For most things -this would pose a massive problem, but because lifetimes don't *exist* at runtime, -this is really just a compile-time mechanism. The Fn traits contain sugar that -allows higher-rank lifetimes to simply be expressed by simply omitting lifetimes: - - -```rust -fn main() { - foo(|input| input); -} - -fn foo(f: F) - // F is higher-ranked over the lifetime these references have - where F: Fn(&u8) -> &u8 -{ - f(&0); - f(&1); -} -``` - -The desugaring of this is actually unstable: - -``` -#![feature(unboxed_closures)] - -fn main() { - foo(|input| input); -} - -fn foo(f: F) - where F: for<'a> Fn<(&'a u8,), Output=&'a u8> -{ - f(&0); - f(&1); -} -``` - -`for<'a>` is how we declare a higher-ranked lifetime. Unfortunately higher-ranked -lifetimes are still fairly new, and are missing a few features to make them -maximally useful outside of the Fn traits. - - - - -# Subtyping and Variance - -Although Rust doesn't have any notion of inheritance, it *does* include subtyping. -In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are derived -from scopes, we can partially order them based on an *outlives* relationship. We -can even express this as a generic bound: `T: 'a` specifies that `T` *outlives* `'a`. - -We can then define subtyping on lifetimes in terms of lifetimes: if `'a : 'b` -("a outlives b"), then `'a` is a subtype of `b`. This is a -large source of confusion, because a bigger scope is a *sub type* of a smaller scope. -This does in fact make sense. The intuitive reason for this is that if you expect an -`&'a u8`, then it's totally fine for me to hand you an `&'static u8` in the same way -that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. - -(Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary -construct that some disagree with. I just find that it simplifies this analysis.) - -TODO: higher rank lifetime subtyping - -Variance is where things get really harsh. -Variance is a property that *type constructors* have. A type constructor in Rust -is a generic type with unbound arguments. For instance `Vec` is a type constructor -that takes a `T` and returns a `Vec`. `&` and `&mut` are type constructors that -take a lifetime and a type. - -A type constructor's *variance* is how the subtypes of its inputs affects the -subtypes of its outputs. There are three kinds of variance: - -* F is *variant* if `T` being a subtype of `U` implies `F` is a subtype of `F` -* F is *invariant* otherwise (no subtyping relation can be derived) - -(For those of you who are familiar with variance from other languages, what we refer -to as "just" variant is in fact *covariant*. Rust does not have contravariance. -Historically Rust did have some contravariance but it was scrapped due to poor -interactions with other features.) - -Some important variances: - -* `&` is variant (as is *const by metaphor) -* `&mut` is invariant (as is *mut by metaphor) -* `Fn(T) -> U` is invariant with respect to `T`, but variant with respect to `U` -* `Box`, `Vec`, and all other collections are variant -* `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" - types are invariant - -To understand why these variances are correct and desirable, we will consider several -examples. We have already covered why `&` should be variant when introducing subtyping: -it's desirable to be able to pass longer-lived things where shorter-lived things are -needed. - -To see why `&mut` should be invariant, consider the following code: - -```rust fn main() { - let mut forever_str: &'static str = "hello"; - { - let string = String::from("world"); - overwrite(&mut forever_str, &mut &*string); + 'c: { + let x: u32 = 0; + 'd: { + // An anonymous scope is introduced because the borrow does not + // need to last for the whole scope x is valid for. The return + // of as_str must find a str somewhere *before* this function + // call. Obviously not happening. + println!("{}", as_str::<'d>(&'d temp)); + } } - println!("{}", forever_str); -} - -fn overwrite(input: &mut T, new: &mut T) { - *input = *new; } ``` -The signature of `overwrite` is clearly valid: it takes mutable references to two values -of the same type, and replaces one with the other. We have seen already that `&` is -variant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a -subtype of `&'a str`. Therefore, if `&mut` was -*also* variant, then the lifetime of the `&'static str` would successfully be -"shrunk" down to the shorter lifetime of the string, and `replace` would be -called successfully. The string would subsequently be dropped, and `forever_str` -would point to freed memory when we print it! - -Therefore `&mut` should be invariant. This is the general theme of variance vs -invariance: if variance would allow you to *store* a short-lived value in a -longer-lived slot, then you must be invariant. - -`Box` and `Vec` are interesting cases because they're variant, but you can -definitely store values in them! This is fine because *you can only store values -in them through a mutable reference*! The mutable reference makes the whole type -invariant, and therefore prevents you from getting in trouble. - -Being variant allows them to be variant when shared immutably (so you can pass -a `&Box<&'static str>` where a `&Box<&'a str>` is expected). It also allows you to -forever weaken the type by moving it into a weaker slot. That is, you can do: - -```rust -fn get_box<'a>(&'a u8) -> Box<&'a str> { - // string literals are `&'static str`s - Box::new("hello") -} -``` - -which is fine because unlike the mutable borrow case, there's no one else who -"remembers" the old lifetime in the box. - -The variance of the cell types similarly follows. `&` is like an `&mut` for a -cell, because you can still store values in them through an `&`. Therefore cells -must be invariant to avoid lifetime smuggling. - -`Fn` is the most subtle case, because it has mixed variance. To see why -`Fn(T) -> U` should be invariant over T, consider the following function -signature: - -```rust -// 'a is derived from some parent scope -fn foo(&'a str) -> usize; -``` - -This signature claims that it can handle any &str that lives *at least* as long -as `'a`. Now if this signature was variant with respect to &str, that would mean - -```rust -fn foo(&'static str) -> usize; -``` - -could be provided in its place, as it would be a subtype. However this function -has a *stronger* requirement: it says that it can *only* handle `&'static str`s, -and nothing else. Therefore functions are not variant over their arguments. - -To see why `Fn(T) -> U` should be *variant* over U, consider the following -function signature: - -```rust -// 'a is derived from some parent scope -fn foo(usize) -> &'a str; -``` - -This signature claims that it will return something that outlives `'a`. It is -therefore completely reasonable to provide - -```rust -fn foo(usize) -> &'static str; -``` - -in its place. Therefore functions *are* variant over their return type. - -`*const` has the exact same semantics as &, so variance follows. `*mut` on the -other hand can dereference to an &mut whether shared or not, so it is marked -as invariant in analogy to cells. - -This is all well and good for the types the standard library provides, but -how is variance determined for type that *you* define? A struct, informally -speaking, inherits the variance of its fields. If a struct `Foo` -has a generic argument `A` that is used in a field `a`, then Foo's variance -over `A` is exactly `a`'s variance. However this is complicated if `A` is used -in multiple fields. - -* If all uses of A are variant, then Foo is variant over A -* Otherwise, Foo is invariant over A - -```rust -struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { - a: &'a A, // variant over 'a and A - b: &'b mut B, // invariant over 'b and B - c: *const C, // variant over C - d: *mut D, // invariant over D - e: Vec, // variant over E - f: Cell, // invariant over F - g: G // variant over G - h1: H // would also be variant over H except... - h2: Cell // invariant over H, because invariance wins -} -``` - - - -# PhantomData - -When working with unsafe code, we can often end up in a situation where -types or lifetimes are logically associated with a struct, but not actually -part of a field. This most commonly occurs with lifetimes. For instance, the `Iter` -for `&'a [T]` is (approximately) defined as follows: - -``` -pub struct Iter<'a, T: 'a> { - ptr: *const T, - end: *const T, -} -``` - -However because `'a` is unused within the struct's body, it's *unbound*. -Because of the troubles this has historically caused, unbound lifetimes and -types are *illegal* in struct definitions. Therefore we must somehow refer -to these types in the body. Correctly doing this is necessary to have -correct variance and drop checking. - -We do this using *PhantomData*, which is a special marker type. PhantomData -consumes no space, but simulates a field of the given type for the purpose of -static analysis. This was deemed to be less error-prone than explicitly telling -the type-system the kind of variance that you want, while also providing other -useful information. - -Iter logically contains `&'a T`, so this is exactly what we tell -the PhantomData to simulate: - -``` -pub struct Iter<'a, T: 'a> { - ptr: *const T, - end: *const T, - _marker: marker::PhantomData<&'a T>, -} -``` - - - - -# Dropck - -When a type is going out of scope, Rust will try to Drop it. Drop executes -arbitrary code, and in fact allows us to "smuggle" arbitrary code execution -into many places. As such additional soundness checks (dropck) are necessary to -ensure that a type T can be safely instantiated and dropped. It turns out that we -*really* don't need to care about dropck in practice, as it often "just works". - -However the one exception is with PhantomData. Given a struct like Vec: - -``` -struct Vec { - data: *const T, // *const for variance! - len: usize, - cap: usize, -} -``` - -dropck will generously determine that Vec does not own any values of -type T. This will unfortunately allow people to construct unsound Drop -implementations that access data that has already been dropped. In order to -tell dropck that we *do* own values of type T, and may call destructors of that -type, we must add extra PhantomData: - -``` -struct Vec { - data: *const T, // *const for covariance! - len: usize, - cap: usize, - _marker: marker::PhantomData, -} -``` - -Raw pointers that own an allocation is such a pervasive pattern that the -standard library made a utility for itself called `Unique` which: - -* wraps a `*const T`, -* includes a PhantomData, -* auto-derives Send/Sync as if T was contained -* marks the pointer as NonZero for the null-pointer optimization - - - - -# Splitting Lifetimes +Shoot! -The mutual exclusion property of mutable references can be very limiting when -working with a composite structure. Borrowck understands some basic stuff, but -will fall over pretty easily. Borrowck understands structs sufficiently to -understand that it's possible to borrow disjoint fields of a struct simultaneously. -So this works today: +Of course, the right way to write this function is as follows: ```rust -struct Foo { - a: i32, - b: i32, - c: i32, +fn to_string(data: &u32) -> String { + format!("{}", data) } - -let mut x = Foo {a: 0, b: 0, c: 0}; -let a = &mut x.a; -let b = &mut x.b; -let c = &x.c; -*b += 1; -let c2 = &x.c; -*a += 10; -println!("{} {} {} {}", a, b, c, c2); ``` -However borrowck doesn't understand arrays or slices in any way, so this doesn't -work: - -```rust -let x = [1, 2, 3]; -let a = &mut x[0]; -let b = &mut x[1]; -println!("{} {}", a, b); -``` +We must produce an owned value inside the function to return it! The only way +we could have returned an `&'a str` would have been if it was in a field of the +`&'a u32`, which is obviously not the case. -```text -:3:18: 3:22 error: cannot borrow immutable indexed content `x[..]` as mutable -:3 let a = &mut x[0]; - ^~~~ -:4:18: 4:22 error: cannot borrow immutable indexed content `x[..]` as mutable -:4 let b = &mut x[1]; - ^~~~ -error: aborting due to 2 previous errors -``` +(Actually we could have also just returned a string literal, which as a global +can be considered to reside at the bottom of the stack; though this limits +our implementation *just a bit*.) -While it was plausible that borrowck could understand this simple case, it's -pretty clearly hopeless for borrowck to understand disjointness in general -container types like a tree, especially if distinct keys actually *do* map -to the same value. -In order to "teach" borrowck that what we're doing is ok, we need to drop down -to unsafe code. For instance, mutable slices expose a `split_at_mut` function that -consumes the slice and returns *two* mutable slices. One for everything to the -left of the index, and one for everything to the right. Intuitively we know this -is safe because the slices don't alias. However the implementation requires some -unsafety: -```rust -fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { - unsafe { - let self2: &mut [T] = mem::transmute_copy(&self); - (ops::IndexMut::index_mut(self, ops::RangeTo { end: mid } ), - ops::IndexMut::index_mut(self2, ops::RangeFrom { start: mid } )) - } -} -``` -This is pretty plainly dangerous. We use transmute to duplicate the slice with an -*unbounded* lifetime, so that it can be treated as disjoint from the other until -we unify them when we return. +# Example 2: aliasing a mutable reference -However more subtle is how iterators that yield mutable references work. -The iterator trait is defined as follows: +How about the other example: ```rust -trait Iterator { - type Item; - - fn next(&mut self) -> Option; -} +let mut data = vec![1, 2, 3]; +let x = &data[0]; +data.push(4); +println!("{}", x); ``` -Given this definition, Self::Item has *no* connection to `self`. This means -that we can call `next` several times in a row, and hold onto all the results -*concurrently*. This is perfectly fine for by-value iterators, which have exactly -these semantics. It's also actually fine for shared references, as they admit -arbitrarily many references to the same thing (although the -iterator needs to be a separate object from the thing being shared). But mutable -references make this a mess. At first glance, they might seem completely -incompatible with this API, as it would produce multiple mutable references to -the same object! - -However it actually *does* work, exactly because iterators are one-shot objects. -Everything an IterMut yields will be yielded *at most* once, so we don't *actually* -ever yield multiple mutable references to the same piece of data. - -In general all mutable iterators require *some* unsafe code *somewhere*, though. -Whether it's raw pointers, or safely composing on top of *another* IterMut. - -For instance, VecDeque's IterMut: - ```rust -pub struct IterMut<'a, T:'a> { - // The whole backing array. Some of these indices are initialized! - ring: &'a mut [T], - tail: usize, - head: usize, -} - -impl<'a, T> Iterator for IterMut<'a, T> { - type Item = &'a mut T; +'a: { + let mut data: Vec = vec![1, 2, 3]; + 'b: { + // 'b is as big as we need this borrow to be + // (just need to get to `println!`) + let x: &'b i32 = Index::index::<'b>(&'b data, 0); + 'c: { + // Temporary scope because we don't need the + // &mut to last any longer. - fn next(&mut self) -> Option<&'a mut T> { - if self.tail == self.head { - return None; - } - let tail = self.tail; - self.tail = wrap_index(self.tail.wrapping_add(1), self.ring.len()); - - unsafe { - // might as well do unchecked indexing since wrap_index has us - // in-bounds, and many of the "middle" indices are uninitialized - // anyway. - let elem = self.ring.get_unchecked_mut(tail); - - // round-trip through a raw pointer to unbound the lifetime from - // ourselves - Some(&mut *(elem as *mut _)) + // NOTE: Vec::push is not valid syntax + Vec::push(&'c mut data, 4); } + println!("{}", x); } } ``` -A very subtle but interesting detail in this design is that it *relies on -privacy to be sound*. Borrowck works on some very simple rules. One of those rules -is that if we have a live &mut Foo and Foo contains an &mut Bar, then that &mut -Bar is *also* live. Since IterMut is always live when `next` can be called, if -`ring` were public then we could mutate `ring` while outstanding mutable borrows -to it exist! - - - - - -# Weird Lifetimes - -Given the following code: - -```rust -struct Foo; - -impl Foo { - fn mutate_and_share(&mut self) -> &Self { &*self } - fn share(&self) {} -} - -fn main() { - let mut foo = Foo; - let loan = foo.mutate_and_share(); - foo.share(); -} -``` - -One might expect it to compile. We call `mutate_and_share`, which mutably borrows -`foo` *temporarily*, but then returns *only* a shared reference. Therefore we -would expect `foo.share()` to succeed as `foo` shouldn't be mutably borrowed. - -However when we try to compile it: - -```text -:11:5: 11:8 error: cannot borrow `foo` as immutable because it is also borrowed as mutable -:11 foo.share(); - ^~~ -:10:16: 10:19 note: previous borrow of `foo` occurs here; the mutable borrow prevents subsequent moves, borrows, or modification of `foo` until the borrow ends -:10 let loan = foo.mutate_and_share(); - ^~~ -:12:2: 12:2 note: previous borrow ends here -:8 fn main() { -:9 let mut foo = Foo; -:10 let loan = foo.mutate_and_share(); -:11 foo.share(); -:12 } - ^ -``` - -What happened? Well, the lifetime of `loan` is derived from a *mutable* borrow. -This makes the type system believe that `foo` is mutably borrowed as long as -`loan` exists, even though it's a shared reference. This isn't a bug, although -one could argue it is a limitation of the design. In particular, to know if -the mutable part of the borrow is *really* expired we'd have to peek into -implementation details of the function. Currently, type-checking a function -does not need to inspect the bodies of any other functions or types. +The problem here is is bit more subtle and interesting. We want Rust to +reject this program for the following reason: We have a live shared reference `x` +to a descendent of `data` when try to take a *mutable* reference to `data` +when we call `push`. This would create an aliased mutable reference, which would +violate the *second* rule of references. +However this is *not at all* how Rust reasons that this program is bad. Rust +doesn't understand that `x` is a reference to a subpath of `data`. It doesn't +understand Vec at all. What it *does* see is that `x` has to live for `'b` to +be printed. The signature of `Index::index` subsequently demands that the +reference we take to *data* has to survive for `'b`. When we try to call `push`, +it then sees us try to make an `&'c mut data`. Rust knows that `'c` is contained +within `'b`, and rejects our program because the `&'b data` must still be live! +Here we see that the lifetime system is *much* more coarse than the reference +semantics we're actually interested in preserving. For the most part, *that's +totally ok*, because it keeps us from spending all day explaining our program +to the compiler. However it does mean that several programs that are *totally* +correct with respect to Rust's *true* semantics are rejected because lifetimes +are too dumb. \ No newline at end of file diff --git a/meet-safe-and-unsafe.md b/meet-safe-and-unsafe.md new file mode 100644 index 0000000000000..e12997f6f2461 --- /dev/null +++ b/meet-safe-and-unsafe.md @@ -0,0 +1,82 @@ +% Meet Safe and Unsafe + +Safe and Unsafe are Rust's chief engineers. + +TODO: ADORABLE PICTURES OMG + +Unsafe handles all the dangerous internal stuff. They build the foundations +and handle all the dangerous materials. By all accounts, Unsafe is really a bit +unproductive, because the nature of their work means that they have to spend a +lot of time checking and double-checking everything. What if there's an earthquake +on a leap year? Are we ready for that? Unsafe better be, because if they get +*anything* wrong, everything will blow up! What Unsafe brings to the table is +*quality*, not quantity. Still, nothing would ever get done if everything was +built to Unsafe's standards! + +That's where Safe comes in. Safe has to handle *everything else*. Since Safe needs +to *get work done*, they've grown to be fairly carless and clumsy! Safe doesn't worry +about all the crazy eventualities that Unsafe does, because life is too short to deal +with leap-year-earthquakes. Of course, this means there's some jobs that Safe just +can't handle. Safe is all about quantity over quality. + +Unsafe loves Safe to bits, but knows that tey *can never trust them to do the +right thing*. Still, Unsafe acknowledges that not every problem needs quite the +attention to detail that they apply. Indeed, Unsafe would *love* if Safe could do +*everything* for them. To accomplish this, Unsafe spends most of their time +building *safe abstractions*. These abstractions handle all the nitty-gritty +details for Safe, and choose good defaults so that the simplest solution (which +Safe will inevitably use) is usually the *right* one. Once a safe abstraction is +built, Unsafe ideally needs to never work on it again, and Safe can blindly use +it in all their work. + +Unsafe's attention to detail means that all the things that they mark as ok for +Safe to use can be combined in arbitrarily ridiculous ways, and all the rules +that Unsafe is forced to uphold will never be violated. If they *can* be violated +by Safe, that means *Unsafe*'s the one in the wrong. Safe can work carelessly, +knowing that if anything blows up, it's not *their* fault. Safe can also call in +Unsafe at any time if there's a hard problem they can't quite work out, or if they +can't meet the client's quality demands. Of course, Unsafe will beg and plead Safe +to try their latest safe abstraction first! + +In addition to being adorable, Safe and Unsafe are what makes Rust possible. +Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. +Any time someone opines the guarantees of Rust, they are almost surely talking about +Safe. However Safe is not sufficient to write every program. For that, +we need the Unsafe superset. + +Most fundamentally, writing bindings to other languages +(such as the C exposed by your operating system) is never going to be safe. Rust +can't control what other languages do to program execution! However Unsafe is +also necessary to construct fundamental abstractions where the type system is not +sufficient to automatically prove what you're doing is sound. + +Indeed, the Rust standard library is implemented in Rust, and it makes substantial +use of Unsafe for implementing IO, memory allocation, collections, +synchronization, and other low-level computational primitives. + +Upon hearing this, many wonder why they would not simply just use C or C++ in place of +Rust (or just use a "real" safe language). If we're going to do unsafe things, why not +lean on these much more established languages? + +The most important difference between C++ and Rust is a matter of defaults: +Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular +action. In deciding to work with unchecked uninitialized memory, this does not +suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, +one does not have to suddenly worry about indexing out of bounds on `y`. +C and C++, by contrast, have pervasive unsafety baked into the language. Even the +modern best practices like `unique_ptr` have various safety pitfalls. + +It cannot be emphasized enough that Unsafe should be regarded as an exceptional +thing, not a normal one. Unsafe is often the domain of *fundamental libraries*: anything that needs +to make FFI bindings or define core abstractions. These fundamental libraries then expose +a safe interface for intermediate libraries and applications to build upon. And these +safe interfaces make an important promise: if your application segfaults, it's not your +fault. *They* have a bug. + +And really, how is that different from *any* safe language? Python, Ruby, and Java libraries +can internally do all sorts of nasty things. The languages themselves are no +different. Safe languages *regularly* have bugs that cause critical vulnerabilities. +The fact that Rust is written with a healthy spoonful of Unsafe is no different. +However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of +C to do the nasty things that need to get done. + diff --git a/other-reprs.md b/other-reprs.md new file mode 100644 index 0000000000000..068d30c5e3da5 --- /dev/null +++ b/other-reprs.md @@ -0,0 +1,61 @@ +% Alternative representations + +Rust allows you to specify alternative data layout strategies from the default. + + + + +# repr(C) + +This is the most important `repr`. It has fairly simple intent: do what C does. +The order, size, and alignment of fields is exactly what you would expect from +C or C++. Any type you expect to pass through an FFI boundary should have `repr(C)`, +as C is the lingua-franca of the programming world. This is also necessary +to soundly do more elaborate tricks with data layout such as reintepretting values +as a different type. + +However, the interaction with Rust's more exotic data layout features must be kept +in mind. Due to its dual purpose as "for FFI" and "for layout control", `repr(C)` +can be applied to types that will be nonsensical or problematic if passed through +the FFI boundary. + +* ZSTs are still zero-sized, even though this is not a standard behaviour + in C, and is explicitly contrary to the behaviour of an empty type in C++, which + still consumes a byte of space. + +* DSTs, tuples, and tagged unions are not a concept in C and as such are never + FFI safe. + +* **The drop flag will still be added** + +* This is equivalent to `repr(u32)` for enums (see below) + + + + +# repr(packed) + +`repr(packed)` forces rust to strip any padding, and only align the type to a +byte. This may improve the memory footprint, but will likely have other +negative side-effects. + +In particular, most architectures *strongly* prefer values to be aligned. This +may mean the unaligned loads are penalized (x86), or even fault (ARM). In +particular, the compiler may have trouble with references to unaligned fields. + +`repr(packed)` is not to be used lightly. Unless you have extreme requirements, +this should not be used. + +This repr is a modifier on `repr(C)` and `repr(rust)`. + + + + +# repr(u8), repr(u16), repr(u32), repr(u64) + +These specify the size to make a C-like enum. If the discriminant overflows the +integer it has to fit in, it will be an error. You can manually ask Rust to +allow this by setting the overflowing element to explicitly be 0. However Rust +will not allow you to create an enum where two variants. + +These reprs have no affect on a struct or non-C-like enum. \ No newline at end of file diff --git a/ownership.md b/ownership.md new file mode 100644 index 0000000000000..9c4f92a4394ee --- /dev/null +++ b/ownership.md @@ -0,0 +1,66 @@ +% Ownership and Lifetimes + +Ownership is the breakout feature of Rust. It allows Rust to be completely +memory-safe and efficient, while avoiding garbage collection. Before getting +into the ownership system in detail, we will consider the motivation of this +design. + +We will assume that you accept that garbage collection is not always an optimal +solution, and that it is desirable to manually manage memory to some extent. +If you do not accept this, might I interest you in a different language? + +Regardless of your feelings on GC, it is pretty clearly a *massive* boon to +making code safe. You never have to worry about things going away *too soon* +(although whether you still *wanted* to be pointing at that thing is a different +issue...). This is a pervasive problem that C and C++ need to deal with. +Consider this simple mistake that all of us who have used a non-GC'd language +have made at one point: + +```rust +fn as_str(data: &u32) -> &str { + // compute the string + let s = format!("{}", data); + + // OH NO! We returned a reference to something that + // exists only in this function! + // Dangling pointer! Use after free! Alas! + // (this does not compile in Rust) + &s +} +``` + +This is exactly what Rust's ownership system was built to solve. +Rust knows the scope in which the `&s` lives, and as such can prevent it from +escaping. However this is a simple case that even a C compiler could plausibly +catch. Things get more complicated as code gets bigger and pointers get fed through +various functions. Eventually, a C compiler will fall down and won't be able to +perform sufficient escape analysis to prove your code unsound. It will consequently +be forced to accept your program on the assumption that it is correct. + +This will never happen to Rust. It's up to the programmer to prove to the +compiler that everything is sound. + +Of course, rust's story around ownership is much more complicated than just +verifying that references don't escape the scope of their referent. That's +because ensuring pointers are always valid is much more complicated than this. +For instance in this code, + +```rust +let mut data = vec![1, 2, 3]; +// get an internal reference +let x = &data[0]; + +// OH NO! `push` causes the backing storage of `data` to be reallocated. +// Dangling pointer! User after free! Alas! +// (this does not compile in Rust) +data.push(4); + +println!("{}", x); +``` + +naive scope analysis would be insufficient to prevent this bug, because `data` +does in fact live as long as we needed. However it was *changed* while we had +a reference into it. This is why Rust requires any references to freeze the +referent and its owners. + + diff --git a/raii.md b/raii.md index f85562bd809bb..e9b92c69ccd2d 100644 --- a/raii.md +++ b/raii.md @@ -12,413 +12,3 @@ important in Rust because we have no pervasive GC to rely on for memory manageme 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. - - - - -# Constructors - -Unlike C++, Rust does not come with a slew of 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 a 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 "copy the bits". Copy types *are* implicitly -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 implicitly initialized][uninit]. Default is basically only useful for generic -programming. In concrete contexts, 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. - - - - - -# Destructors - -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 `self`**. This is a -convenience feature so that you don't have to write "destructor boilerplate" to drop -children. If a struct has no special logic for being dropped other than dropping its -children, then it means `Drop` doesn't need to be implemented at all! - -**There is no stable way to prevent this behaviour in Rust 1.0**. - -Note that taking `&mut self` means that even if you *could* suppress recursive Drop, -Rust will prevent you from e.g. moving fields out of self. For most types, this -is totally fine. - -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 immediately marked as uninitialized. - -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); - } - } -} -``` - -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* an instance stores the Next variant. - -In general this works really nice because you don't need to worry about adding/removing -drops 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 overriding recursive drop and allowing moving out -of Self during `drop` 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` - // field 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 destructor. 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 what you should reach for by default. -However, in the future we expect there to be a first-class way to announce that -a field shouldn't be automatically dropped. - - - - -# Leaking - -Ownership based resource management is intended to simplify composition. You -acquire resources when you create the object, and you release the resources -when it gets destroyed. Since destruction is handled for you, it means you -can't forget to release the resources, and it happens as soon as possible! -Surely this is perfect and all of our problems are solved. - -Everything is terrible and we have new and exotic problems to try to solve. - -Many people like to believe that Rust eliminates resource leaks, but this -is absolutely not the case, no matter how you look at it. In the strictest -sense, "leaking" is so abstract as to be unpreventable. It's quite trivial -to initialize a collection at the start of a program, fill it with tons of -objects with destructors, and then enter an infinite event loop that never -refers to it. The collection will sit around uselessly, holding on to its -precious resources until the program terminates (at which point all those -resources would have been reclaimed by the OS anyway). - -We may consider a more restricted form of leak: failing to drop a value that -is unreachable. Rust also doesn't prevent this. In fact Rust has a *function -for doing this*: `mem::forget`. This function consumes the value it is passed -*and then doesn't run its destructor*. - -In the past `mem::forget` was marked as unsafe as a sort of lint against using -it, since failing to call a destructor is generally not a well-behaved thing to -do (though useful for some special unsafe code). However this was generally -determined to be an untenable stance to take: there are *many* ways to fail to -call a destructor in safe code. The most famous example is creating a cycle -of reference counted pointers using interior mutability. - -It is reasonable for safe code to assume that destructor leaks do not happen, -as any program that leaks destructors is probably wrong. However *unsafe* code -cannot rely on destructors to be run to be *safe*. For most types this doesn't -matter: if you leak the destructor then the type is *by definition* inaccessible, -so it doesn't matter, right? For instance, if you leak a `Box` then you -waste some memory but that's hardly going to violate memory-safety. - -However where we must be careful with destructor leaks are *proxy* types. -These are types which manage access to a distinct object, but don't actually -own it. Proxy objects are quite rare. Proxy objects you'll need to care about -are even rarer. However we'll focus on three interesting examples in the -standard library: - -* `vec::Drain` -* `Rc` -* `thread::scoped::JoinGuard` - - - -## Drain - -`drain` is a collections API that moves data out of the container without -consuming the container. This enables us to reuse the allocation of a `Vec` -after claiming ownership over all of its contents. It produces an iterator -(Drain) that returns the contents of the Vec by-value. - -Now, consider Drain in the middle of iteration: some values have been moved out, -and others haven't. This means that part of the Vec is now full of logically -uninitialized data! We could backshift all the elements in the Vec every time we -remove a value, but this would have pretty catastrophic performance consequences. - -Instead, we would like Drain to *fix* the Vec's backing storage when it is -dropped. It should run itself to completion, backshift any elements that weren't -removed (drain supports subranges), and then fix Vec's `len`. It's even -unwinding-safe! Easy! - -Now consider the following: - -``` -let mut vec = vec![Box::new(0); 4]; - -{ - // start draining, vec can no longer be accessed - let mut drainer = vec.drain(..); - - // pull out two elements and immediately drop them - drainer.next(); - drainer.next(); - - // get rid of drainer, but don't call its destructor - mem::forget(drainer); -} - -// Oops, vec[0] was dropped, we're reading a pointer into free'd memory! -println!("{}", vec[0]); -``` - -This is pretty clearly Not Good. Unfortunately, we're kind've stuck between -a rock and a hard place: maintaining consistent state at every step has -an enormous cost (and would negate any benefits of the API). Failing to maintain -consistent state gives us Undefined Behaviour in safe code (making the API -unsound). - -So what can we do? Well, we can pick a trivially consistent state: set the Vec's -len to be 0 when we *start* the iteration, and fix it up if necessary in the -destructor. That way, if everything executes like normal we get the desired -behaviour with minimal overhead. But if someone has the *audacity* to mem::forget -us in the middle of the iteration, all that does is *leak even more* (and possibly -leave the Vec in an *unexpected* but consistent state). Since we've -accepted that mem::forget is safe, this is definitely safe. We call leaks causing -more leaks a *leak amplification*. - - - - -## Rc - -Rc is an interesting case because at first glance it doesn't appear to be a -proxy value at all. After all, it manages the data it points to, and dropping -all the Rcs for a value will drop that value. leaking an Rc doesn't seem like -it would be particularly dangerous. It will leave the refcount permanently -incremented and prevent the data from being freed or dropped, but that seems -just like Box, right? - -Nope. - -Let's consider a simplified implementation of Rc: - -```rust -struct Rc { - ptr: *mut RcBox, -} - -struct RcBox { - data: T, - ref_count: usize, -} - -impl Rc { - fn new(data: T) -> Self { - unsafe { - // Wouldn't it be nice if heap::allocate worked like this? - let ptr = heap::allocate>(); - ptr::write(ptr, RcBox { - data: data, - ref_count: 1, - }); - Rc { ptr: ptr } - } - } - - fn clone(&self) -> Self { - unsafe { - (*self.ptr).ref_count += 1; - } - Rc { ptr: self.ptr } - } -} - -impl Drop for Rc { - fn drop(&mut self) { - unsafe { - let inner = &mut ; - (*self.ptr).ref_count -= 1; - if (*self.ptr).ref_count == 0 { - // drop the data and then free it - ptr::read(self.ptr); - heap::deallocate(self.ptr); - } - } - } -} -``` - -This code contains an implicit and subtle assumption: ref_count can fit in a -`usize`, because there can't be more than `usize::MAX` Rcs in memory. However -this itself assumes that the ref_count accurately reflects the number of Rcs -in memory, which we know is false with mem::forget. Using mem::forget we can -overflow the ref_count, and then get it down to 0 with outstanding Rcs. Then we -can happily use-after-free the inner data. Bad Bad Not Good. - -This can be solved by *saturating* the ref_count, which is sound because -decreasing the refcount by `n` still requires `n` Rcs simultaneously living -in memory. - - - - -## thread::scoped::JoinGuard - -The thread::scoped API intends to allow threads to be spawned that reference -data on the stack without any synchronization over that data. Usage looked like: - -```rust -let mut data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; -{ - let guards = vec![]; - for x in &mut data { - // Move the mutable reference into the closure, and execute - // it on a different thread. The closure has a lifetime bound - // by the lifetime of the mutable reference `x` we store in it. - // The guard that is returned is in turn assigned the lifetime - // of the closure, so it also mutably borrows `data` as `x` did. - // This means we cannot access `data` until the guard goes away. - let guard = thread::scoped(move || { - *x *= 2; - }); - // store the thread's guard for later - guards.push(guard); - } - // All guards are dropped here, forcing the threads to join - // (this thread blocks here until the others terminate). - // Once the threads join, the borrow expires and the data becomes - // accessible again in this thread. -} -// data is definitely mutated here. -``` - -In principle, this totally works! Rust's ownership system perfectly ensures it! -...except it relies on a destructor being called to be safe. - -``` -let mut data = Box::new(0); -{ - let guard = thread::scoped(|| { - // This is at best a data race. At worst, it's *also* a use-after-free. - *data += 1; - }); - // Because the guard is forgotten, expiring the loan without blocking this - // thread. - mem::forget(guard); -} -// So the Box is dropped here while the scoped thread may or may not be trying -// to access it. -``` - -Dang. Here the destructor running was pretty fundamental to the API, and it had -to be scrapped in favour of a completely different design. - -[uninit]: uninitialized.html \ No newline at end of file diff --git a/references.md b/references.md new file mode 100644 index 0000000000000..fa47a69a7eaae --- /dev/null +++ b/references.md @@ -0,0 +1,139 @@ +% References + +There are two kinds of reference: + +* Shared reference: `&` +* Mutable reference: `&mut` + +Which obey the following rules: + +* A reference cannot outlive its referent +* A mutable reference cannot be aliased + +To define aliasing, we must define the notion of *paths* and *liveness*. + + + + +# Paths + +If all Rust had were values, then every value would be uniquely owned +by a variable or composite structure. From this we naturally derive a *tree* +of ownership. The stack itself is the root of the tree, with every variable +as its direct children. Each variable's direct children would be their fields +(if any), and so on. + +From this view, every value in Rust has a unique *path* in the tree of ownership. +References to a value can subsequently be interpreted as a path in this tree. +Of particular interest are *prefixes*: `x` is a prefix of `y` if `x` owns `y` + +However much data doesn't reside on the stack, and we must also accommodate this. +Globals and thread-locals are simple enough to model as residing at the bottom +of the stack (though we must be careful with mutable globals). Data on +the heap poses a different problem. + +If all Rust had on the heap was data uniquely by a pointer on the stack, +then we can just treat that pointer as a struct that owns the value on +the heap. Box, Vec, String, and HashMap, are examples of types which uniquely +own data on the heap. + +Unfortunately, data on the heap is not *always* uniquely owned. Rc for instance +introduces a notion of *shared* ownership. Shared ownership means there is no +unique path. A value with no unique path limits what we can do with it. In general, only +shared references can be created to these values. However mechanisms which ensure +mutual exclusion may establish One True Owner temporarily, establishing a unique path +to that value (and therefore all its children). + +The most common way to establish such a path is through *interior mutability*, +in contrast to the *inherited mutability* that everything in Rust normally uses. +Cell, RefCell, Mutex, and RWLock are all examples of interior mutability types. These +types provide exclusive access through runtime restrictions. However it is also +possible to establish unique ownership without interior mutability. For instance, +if an Rc has refcount 1, then it is safe to mutate or move its internals. + + + + +# Liveness + +Roughly, a reference is *live* at some point in a program if it can be +dereferenced. Shared references are always live unless they are literally unreachable +(for instance, they reside in freed or leaked memory). Mutable references can be +reachable but *not* live through the process of *reborrowing*. + +A mutable reference can be reborrowed to either a shared or mutable reference. +Further, the reborrow can produce exactly the same reference, or point to a +path it is a prefix of. For instance, a mutable reference can be reborrowed +to point to a field of its referent: + +```rust +let x = &mut (1, 2); +{ + // reborrow x to a subfield + let y = &mut x.0; + // y is now live, but x isn't + *y = 3; +} +// y goes out of scope, so x is live again +*x = (5, 7); +``` + +It is also possible to reborrow into *multiple* mutable references, as long as +they are *disjoint*: no reference is a prefix of another. Rust +explicitly enables this to be done with disjoint struct fields, because +disjointness can be statically proven: + +```rust +let x = &mut (1, 2); +{ + // reborrow x to two disjoint subfields + let y = &mut x.0; + let z = &mut x.1; + // y and z are now live, but x isn't + *y = 3; + *z = 4; +} +// y and z go out of scope, so x is live again +*x = (5, 7); +``` + +However it's often the case that Rust isn't sufficiently smart to prove that +multiple borrows are disjoint. *This does not mean it is fundamentally illegal +to make such a borrow*, just that Rust isn't as smart as you want. + +To simplify things, we can model variables as a fake type of reference: *owned* +references. Owned references have much the same semantics as mutable references: +they can be re-borrowed in a mutable or shared manner, which makes them no longer +live. Live owned references have the unique property that they can be moved +out of (though mutable references *can* be swapped out of). This is +only given to *live* owned references because moving its referent would of +course invalidate all outstanding references prematurely. + +As a local lint against inappropriate mutation, only variables that are marked +as `mut` can be borrowed mutably. + +It is also interesting to note that Box behaves exactly like an owned +reference. It can be moved out of, and Rust understands it sufficiently to +reason about its paths like a normal variable. + + + + +# Aliasing + +With liveness and paths defined, we can now properly define *aliasing*: + +**A mutable reference is aliased if there exists another live reference to it or +one of its prefixes.** + +That's it. Super simple right? Except for the fact that it took us two pages +to define all of the terms in that defintion. You know: Super. Simple. + +Actually it's a bit more complicated than that. In addition to references, +Rust has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent +ownership or aliasing semantics. As a result, Rust makes absolutely no effort +to track that they are used correctly, and they are wildly unsafe. + +**It is an open question to what degree raw pointers have alias semantics. +However it is important for these definitions to be sound that the existence +of a raw pointer does not imply some kind of live path.** diff --git a/repr-rust.md b/repr-rust.md new file mode 100644 index 0000000000000..caf60bed8c53b --- /dev/null +++ b/repr-rust.md @@ -0,0 +1,124 @@ +% repr(Rust) + +Rust gives you the following ways to lay out composite data: + +* structs (named product types) +* tuples (anonymous product types) +* arrays (homogeneous product types) +* enums (named sum types -- tagged unions) + +An enum is said to be *C-like* if none of its variants have associated data. + +For all these, individual fields are aligned to their preferred alignment. For +primitives this is usually equal to their size. For instance, a u32 will be +aligned to a multiple of 32 bits, and a u16 will be aligned to a multiple of 16 +bits. Composite structures will have a preferred alignment equal to the maximum +of their fields' preferred alignment, and a size equal to a multiple of their +preferred alignment. This ensures that arrays of T can be correctly iterated +by offsetting by their size. So for instance, + +```rust +struct A { + a: u8, + c: u32, + b: u16, +} +``` + +will have a size that is a multiple of 32-bits, and 32-bit alignment. + +There is *no indirection* for these types; all data is stored contiguously as you would +expect in C. However with the exception of arrays (which are densely packed and +in-order), the layout of data is not by default specified in Rust. Given the two +following struct definitions: + +```rust +struct A { + a: i32, + b: u64, +} + +struct B { + x: i32, + b: u64, +} +``` + +Rust *does* guarantee that two instances of A have their data laid out in exactly +the same way. However Rust *does not* guarantee that an instance of A has the same +field ordering or padding as an instance of B (in practice there's no *particular* +reason why they wouldn't, other than that its not currently guaranteed). + +With A and B as written, this is basically nonsensical, but several other features +of Rust make it desirable for the language to play with data layout in complex ways. + +For instance, consider this struct: + +```rust +struct Foo { + count: u16, + data1: T, + data2: U, +} +``` + +Now consider the monomorphizations of `Foo` and `Foo`. If Rust lays out the +fields in the order specified, we expect it to *pad* the values in the struct to satisfy +their *alignment* requirements. So if Rust didn't reorder fields, we would expect Rust to +produce the following: + +```rust +struct Foo { + count: u16, + data1: u16, + data2: u32, +} + +struct Foo { + count: u16, + _pad1: u16, + data1: u32, + data2: u16, + _pad2: u16, +} +``` + +The latter case quite simply wastes space. An optimal use of space therefore requires +different monomorphizations to have *different field orderings*. + +**Note: this is a hypothetical optimization that is not yet implemented in Rust 1.0** + +Enums make this consideration even more complicated. Naively, an enum such as: + +```rust +enum Foo { + A(u32), + B(u64), + C(u8), +} +``` + +would be laid out as: + +```rust +struct FooRepr { + data: u64, // this is *really* either a u64, u32, or u8 based on `tag` + tag: u8, // 0 = A, 1 = B, 2 = C +} +``` + +And indeed this is approximately how it would be laid out in general +(modulo the size and position of `tag`). However there are several cases where +such a representation is ineffiecient. The classic case of this is Rust's +"null pointer optimization". Given a pointer that is known to not be null +(e.g. `&u32`), an enum can *store* a discriminant bit *inside* the pointer +by using null as a special value. The net result is that +`size_of::>() == size_of::<&T>()` + +There are many types in Rust that are, or contain, "not null" pointers such as +`Box`, `Vec`, `String`, `&T`, and `&mut T`. Similarly, one can imagine +nested enums pooling their tags into a single descriminant, as they are by +definition known to have a limited range of valid values. In principle enums can +use fairly elaborate algorithms to cache bits throughout nested types with +special constrained representations. As such it is *especially* desirable that +we leave enum layout unspecified today. \ No newline at end of file diff --git a/safe-unsafe-meaning.md b/safe-unsafe-meaning.md new file mode 100644 index 0000000000000..8a6300a061d24 --- /dev/null +++ b/safe-unsafe-meaning.md @@ -0,0 +1,135 @@ +% What do Safe and Unsafe really mean? + +Rust cares about preventing the following things: + +* Dereferencing null or dangling pointers +* Reading [uninitialized memory][] +* Breaking the [pointer aliasing rules][] +* Producing invalid primitive values: + * dangling/null references + * a `bool` that isn't 0 or 1 + * an undefined `enum` discriminant + * a `char` larger than char::MAX (TODO: check if stronger restrictions apply) + * A non-utf8 `str` +* Unwinding into another language +* Causing a [data race][] +* Invoking Misc. Undefined Behaviour (in e.g. compiler intrinsics) + +That's it. That's all the Undefined Behaviour in Rust. Libraries are free to +declare arbitrary requirements if they could transitively cause memory safety +issues, but it all boils down to the above actions. Rust is otherwise +quite permisive with respect to other dubious operations. Rust considers it +"safe" to: + +* Deadlock +* Have a Race Condition +* Leak memory +* Fail to call destructors +* Overflow integers +* Delete the production database + +However any program that does such a thing is *probably* incorrect. Rust +provides lots of tools to make doing these things rare, but these problems are +considered impractical to categorically prevent. + +Rust models the seperation between Safe and Unsafe with the `unsafe` keyword. +There are several places `unsafe` can appear in Rust today, which can largely be +grouped into two categories: + +* There are unchecked contracts here. To declare you understand this, I require +you to write `unsafe` elsewhere: + * On functions, `unsafe` is declaring the function to be unsafe to call. Users + of the function must check the documentation to determine what this means, + and then have to write `unsafe` somewhere to identify that they're aware of + the danger. + * On trait declarations, `unsafe` is declaring that *implementing* the trait + is an unsafe operation, as it has contracts that other unsafe code is free to + trust blindly. + +* I am declaring that I have, to the best of my knowledge, adhered to the +unchecked contracts: + * On trait implementations, `unsafe` is declaring that the contract of the + `unsafe` trait has been upheld. + * On blocks, `unsafe` is declaring any unsafety from an unsafe + operation within to be handled, and therefore the parent function is safe. + +There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for +historical reasons and is in the process of being phased out. See the section on +[destructors][] for details. + +Some examples of unsafe functions: + +* `slice::get_unchecked` will perform unchecked indexing, allowing memory + safety to be freely violated. +* `ptr::offset` is an intrinsic that invokes Undefined Behaviour if it is + not "in bounds" as defined by LLVM (see the lifetimes section for details). +* `mem::transmute` reinterprets some value as having the given type, + bypassing type safety in arbitrary ways. (see [conversions][] for details) +* All FFI functions are `unsafe` because they can do arbitrary things. + C being an obvious culprit, but generally any language can do something + that Rust isn't happy about. + +As of Rust 1.0 there are exactly two unsafe traits: + +* `Send` is a marker trait (it has no actual API) that promises implementors + are safe to send to another thread. +* `Sync` is a marker trait that promises that threads can safely share + implementors through a shared reference. + +The need for unsafe traits boils down to the fundamental lack of trust that Unsafe +has for Safe. All safe traits are free to declare arbitrary contracts, but because +implementing them is a job for Safe, Unsafe can't trust those contracts to actually +be upheld. + +For instance Rust has `PartialOrd` and `Ord` traits to try to differentiate +between types which can "just" be compared, and those that actually implement a +*total* ordering. Pretty much every API that wants to work with data that can be +compared *really* wants Ord data. For instance, a sorted map like BTreeMap +*doesn't even make sense* for partially ordered types. If you claim to implement +Ord for a type, but don't actually provide a proper total ordering, BTreeMap will +get *really confused* and start making a total mess of itself. Data that is +inserted may be impossible to find! + +But that's ok. BTreeMap is safe, so it guarantees that even if you give it a +*completely* garbage Ord implementation, it will still do something *safe*. You +won't start reading uninitialized memory or unallocated memory. In fact, BTreeMap +manages to not actually lose any of your data. When the map is dropped, all the +destructors will be successfully called! Hooray! + +However BTreeMap is implemented using a modest spoonful of Unsafe (most collections +are). That means that it is not necessarily *trivially true* that a bad Ord +implementation will make BTreeMap behave safely. Unsafe most be sure not to rely +on Ord *where safety is at stake*, because Ord is provided by Safe, and memory +safety is not Safe's responsibility to uphold. *It must be impossible for Safe +code to violate memory safety*. + +But wouldn't it be grand if there was some way for Unsafe to trust *some* trait +contracts *somewhere*? This is the problem that unsafe traits tackle: by marking +*the trait itself* as unsafe *to implement*, Unsafe can trust the implementation +to be correct (because Unsafe can trust themself). + +Rust has traditionally avoided making traits unsafe because it makes Unsafe +pervasive, which is not desirable. Send and Sync are unsafe is because +thread safety is a *fundamental property* that Unsafe cannot possibly hope to +defend against in the same way it would defend against a bad Ord implementation. +The only way to possibly defend against thread-unsafety would be to *not use +threading at all*. Making every operation atomic isn't even sufficient, because +it's possible for complex invariants between disjoint locations in memory. + +Even concurrent paradigms that are traditionally regarded as Totally Safe like +message passing implicitly rely on some notion of thread safety -- are you +really message-passing if you send a *pointer*? Send and Sync therefore require +some *fundamental* level of trust that Safe code can't provide, so they must be +unsafe to implement. To help obviate the pervasive unsafety that this would +introduce, Send (resp. Sync) is *automatically* derived for all types composed only +of Send (resp. Sync) values. 99% of types are Send and Sync, and 99% of those +never actually say it (the remaining 1% is overwhelmingly synchronization +primitives). + + + +[pointer aliasing rules]: lifetimes.html#references +[uninitialized memory]: uninitialized.html +[data race]: concurrency.html +[destructors]: raii.html +[conversions]: conversions.html \ No newline at end of file diff --git a/subtyping.md b/subtyping.md new file mode 100644 index 0000000000000..733e015dbd7d0 --- /dev/null +++ b/subtyping.md @@ -0,0 +1,177 @@ +% Subtyping and Variance + +Although Rust doesn't have any notion of inheritance, it *does* include subtyping. +In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are scopes, +we can partially order them based on a *contains* (outlives) relationship. We +can even express this as a generic bound: `T: 'a` specifies that whatever scope `T` +is valid for must contain the scope `'a` ("T outlives `'a`"). + +We can then define subtyping on lifetimes in terms of that relationship: if `'a: 'b` +("a contains b" or "a outlives b"), then `'a` is a subtype of `'b`. This is a +large source of confusion, because it seems intuitively backwards to many: +the bigger scope is a *sub type* of the smaller scope. + +This does in fact make sense. The intuitive reason for this is that if you expect an +`&'a u8`, then it's totally fine for me to hand you an `&'static u8`, in the same way +that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. +Cats are just Animals *and more*, just as `'static` is just `'a` *and more*. + +(Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary +construct that some disagree with. I just find that it simplifies this analysis.) + +Higher-ranked lifetimes are also subtypes of every concrete lifetime. This is because +taking an arbitrary lifetime is strictly more general than taking a specific one. + + + +# Variance + +Variance is where things get really harsh. + +Variance is a property that *type constructors* have. A type constructor in Rust +is a generic type with unbound arguments. For instance `Vec` is a type constructor +that takes a `T` and returns a `Vec`. `&` and `&mut` are type constructors that +take a lifetime and a type. + +A type constructor's *variance* is how the subtypes of its inputs affects the +subtypes of its outputs. There are three kinds of variance: + +* F is *variant* if `T` being a subtype of `U` implies `F` is a subtype of `F` +* F is *invariant* otherwise (no subtyping relation can be derived) + +(For those of you who are familiar with variance from other languages, what we refer +to as "just" variance is in fact *covariance*. Rust does not have contravariance. +Historically Rust did have some contravariance but it was scrapped due to poor +interactions with other features.) + +Some important variances: + +* `&` is variant (as is `*const` by metaphor) +* `&mut` is invariant (as is `*mut` by metaphor) +* `Fn(T) -> U` is invariant with respect to `T`, but variant with respect to `U` +* `Box`, `Vec`, and all other collections are variant +* `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" + types are invariant + +To understand why these variances are correct and desirable, we will consider several +examples. We have already covered why `&` should be variant when introducing subtyping: +it's desirable to be able to pass longer-lived things where shorter-lived things are +needed. + +To see why `&mut` should be invariant, consider the following code: + +```rust +fn main() { + let mut forever_str: &'static str = "hello"; + { + let string = String::from("world"); + overwrite(&mut forever_str, &mut &*string); + } + println!("{}", forever_str); +} + +fn overwrite(input: &mut T, new: &mut T) { + *input = *new; +} +``` + +The signature of `overwrite` is clearly valid: it takes mutable references to two values +of the same type, and overwrites one with the other. We have seen already that `&` is +variant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a +subtype of `&'a str`. Therefore, if `&mut` was +*also* variant, then the lifetime of the `&'static str` would successfully be +"shrunk" down to the shorter lifetime of the string, and `overwrite` would be +called successfully. The string would subsequently be dropped, and `forever_str` +would point to freed memory when we print it! + +Therefore `&mut` should be invariant. This is the general theme of variance vs +invariance: if variance would allow you to *store* a short-lived value in a +longer-lived slot, then you must be invariant. + +`Box` and `Vec` are interesting cases because they're variant, but you can +definitely store values in them! This is fine because *you can only store values +in them through a mutable reference*! The mutable reference makes the whole type +invariant, and therefore prevents you from getting in trouble. + +Being variant allows them to be variant when shared immutably (so you can pass +a `&Box<&'static str>` where a `&Box<&'a str>` is expected). It also allows you to +forever weaken the type by moving it into a weaker slot. That is, you can do: + +```rust +fn get_box<'a>(&'a u8) -> Box<&'a str> { + // string literals are `&'static str`s + Box::new("hello") +} +``` + +which is fine because unlike the mutable borrow case, there's no one else who +"remembers" the old lifetime in the box. + +The variance of the cell types similarly follows. `&` is like an `&mut` for a +cell, because you can still store values in them through an `&`. Therefore cells +must be invariant to avoid lifetime smuggling. + +`Fn` is the most subtle case, because it has mixed variance. To see why +`Fn(T) -> U` should be invariant over T, consider the following function +signature: + +```rust +// 'a is derived from some parent scope +fn foo(&'a str) -> usize; +``` + +This signature claims that it can handle any &str that lives *at least* as long +as `'a`. Now if this signature was variant with respect to `&str`, that would mean + +```rust +fn foo(&'static str) -> usize; +``` + +could be provided in its place, as it would be a subtype. However this function +has a *stronger* requirement: it says that it can *only* handle `&'static str`s, +and nothing else. Therefore functions are not variant over their arguments. + +To see why `Fn(T) -> U` should be *variant* over U, consider the following +function signature: + +```rust +// 'a is derived from some parent scope +fn foo(usize) -> &'a str; +``` + +This signature claims that it will return something that outlives `'a`. It is +therefore completely reasonable to provide + +```rust +fn foo(usize) -> &'static str; +``` + +in its place. Therefore functions *are* variant over their return type. + +`*const` has the exact same semantics as `&`, so variance follows. `*mut` on the +other hand can dereference to an &mut whether shared or not, so it is marked +as invariant in analogy to cells. + +This is all well and good for the types the standard library provides, but +how is variance determined for type that *you* define? A struct, informally +speaking, inherits the variance of its fields. If a struct `Foo` +has a generic argument `A` that is used in a field `a`, then Foo's variance +over `A` is exactly `a`'s variance. However this is complicated if `A` is used +in multiple fields. + +* If all uses of A are variant, then Foo is variant over A +* Otherwise, Foo is invariant over A + +```rust +struct Foo<'a, 'b, A, B, C, D, E, F, G, H> { + a: &'a A, // variant over 'a and A + b: &'b mut B, // invariant over 'b and B + c: *const C, // variant over C + d: *mut D, // invariant over D + e: Vec, // variant over E + f: Cell, // invariant over F + g: G // variant over G + h1: H // would also be variant over H except... + h2: Cell // invariant over H, because invariance wins +} +``` \ No newline at end of file diff --git a/transmutes.md b/transmutes.md new file mode 100644 index 0000000000000..577d35ddb56dc --- /dev/null +++ b/transmutes.md @@ -0,0 +1,29 @@ +% Transmutes + +Get out of our way type system! We're going to reinterpret these bits or die +trying! Even though this book is all about doing things that are unsafe, I really +can't emphasize that you should deeply think about finding Another Way than the +operations covered in this section. This is really, truly, the most horribly +unsafe thing you can do in Rust. The railguards here are dental floss. + +`mem::transmute` takes a value of type `T` and reinterprets it to have +type `U`. The only restriction is that the `T` and `U` are verified to have the +same size. The ways to cause Undefined Behaviour with this are mind boggling. + +* First and foremost, creating an instance of *any* type with an invalid state + is going to cause arbitrary chaos that can't really be predicted. +* Transmute has an overloaded return type. If you do not specify the return type + it may produce a surprising type to satisfy inference. +* Making a primitive with an invalid value is UB +* Transmuting between non-repr(C) types is UB +* Transmuting an & to &mut is UB +* Transmuting to a reference without an explicitly provided lifetime + produces an [unbound lifetime](lifetimes.html#unbounded-lifetimes) + +`mem::transmute_copy` somehow manages to be *even more* wildly unsafe than +this. It copies `size_of` bytes out of an `&T` and interprets them as a `U`. +The size check that `mem::transmute` has is gone (as it may be valid to copy +out a prefix), though it is Undefined Behaviour for `U` to be larger than `T`. + +Also of course you can get most of the functionality of these functions using +pointer casts. \ No newline at end of file diff --git a/unbounded-lifetimes.md b/unbounded-lifetimes.md new file mode 100644 index 0000000000000..24caeeb36aaab --- /dev/null +++ b/unbounded-lifetimes.md @@ -0,0 +1,37 @@ +% Unbounded Lifetimes + +Unsafe code can often end up producing references or lifetimes out of thin air. +Such lifetimes come into the world as *unbounded*. The most common source of this +is derefencing a raw pointer, which produces a reference with an unbounded lifetime. +Such a lifetime becomes as big as context demands. This is in fact more powerful +than simply becoming `'static`, because for instance `&'static &'a T` +will fail to typecheck, but the unbound lifetime will perfectly mold into +`&'a &'a T` as needed. However for most intents and purposes, such an unbounded +lifetime can be regarded as `'static`. + +Almost no reference is `'static`, so this is probably wrong. `transmute` and +`transmute_copy` are the two other primary offenders. One should endeavour to +bound an unbounded lifetime as quick as possible, especially across function +boundaries. + +Given a function, any output lifetimes that don't derive from inputs are +unbounded. For instance: + +```rust +fn get_str<'a>() -> &'a str; +``` + +will produce an `&str` with an unbounded lifetime. The easiest way to avoid +unbounded lifetimes is to use lifetime elision at the function boundary. +If an output lifetime is elided, then it *must* be bounded by an input lifetime. +Of course it might be bounded by the *wrong* lifetime, but this will usually +just cause a compiler error, rather than allow memory safety to be trivially +violated. + +Within a function, bounding lifetimes is more error-prone. The safest and easiest +way to bound a lifetime is to return it from a function with a bound lifetime. +However if this is unacceptable, the reference can be placed in a location with +a specific lifetime. Unfortunately it's impossible to name all lifetimes involved +in a function. To get around this, you can in principle use `copy_lifetime`, though +these are unstable due to their awkward nature and questionable utility. + diff --git a/unchecked-uninit.md b/unchecked-uninit.md new file mode 100644 index 0000000000000..f5c0fb4059935 --- /dev/null +++ b/unchecked-uninit.md @@ -0,0 +1,86 @@ +% Unchecked Uninitialized Memory + +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: +`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 opens us up to all kinds of problems. 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 uninitialized 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 +returns a pointer to uninitialized memory. + +To handle this, we must use the `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 bits 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 + // NOTE: exception safety is not a concern; Box can't panic + 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 types which don't implement Drop or +contain Drop types, because Rust knows not to try to Drop them. Similarly you +should be able to assign to fields of partially initialized structs +directly if those fields don't contain any Drop types. + +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. +Every control path through that variable's scope must initialize the value +before it ends, if has a destructor. +*[This includes code panicking](unwinding.html)*. + +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. \ No newline at end of file diff --git a/uninitialized.md b/uninitialized.md index 983c320c7382c..915ea8602918e 100644 --- a/uninitialized.md +++ b/uninitialized.md @@ -6,195 +6,5 @@ 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 are 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; - - if true { - x = 1; - } else { - x = 2; - } - - println!("{}", x); -} -``` - -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 is now logically uninitialized because Box isn't 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 -a value, 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 hidden -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 danger. - -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: -`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 opens us up to all kinds of problems. 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 uninitialized 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 -returns a pointer to uninitialized memory. - -To handle this, we must use the `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 bits 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 - // NOTE: exception safety is not a concern; Box can't panic - 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 types which don't implement Drop or -contain Drop types, because Rust knows not to try to Drop them. Similarly you -should be able to assign to fields of partially initialized structs -directly if those fields don't contain any Drop types. - -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. -Every control path through that variable's scope must initialize the value -before it ends, if has a destructor. -*[This includes code panicking](unwinding.html)*. - -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. +Rust provides mechanisms to work with uninitialized memory in checked (safe) and +unchecked (unsafe) ways. \ No newline at end of file diff --git a/vec-alloc.md b/vec-alloc.md new file mode 100644 index 0000000000000..a51f23ca4b8b1 --- /dev/null +++ b/vec-alloc.md @@ -0,0 +1,117 @@ +% Allocating Memory + +So: + +```rust +#![feature(heap_api)] + +use std::rt::heap::EMPTY; +use std::mem; + +impl Vec { + fn new() -> Self { + assert!(mem::size_of::() != 0, "We're not ready to handle ZSTs"); + unsafe { + // need to cast EMPTY to the actual ptr type we want, let + // inference handle it. + Vec { ptr: Unique::new(heap::EMPTY as *mut _), len: 0, cap: 0 } + } + } +} +``` + +I slipped in that assert there because zero-sized types will require some +special handling throughout our code, and I want to defer the issue for now. +Without this assert, some of our early drafts will do some Very Bad Things. + +Next we need to figure out what to actually do when we *do* want space. For that, +we'll need to use the rest of the heap APIs. These basically allow us to +talk directly to Rust's instance of jemalloc. + +We'll also need a way to handle out-of-memory conditions. The standard library +calls the `abort` intrinsic, but calling intrinsics from normal Rust code is a +pretty bad idea. Unfortunately, the `abort` exposed by the standard library +allocates. Not something we want to do during `oom`! Instead, we'll call +`std::process::exit`. + +```rust +fn oom() { + ::std::process::exit(-9999); +} +``` + +Okay, now we can write growing. Roughly, we want to have this logic: + +```text +if cap == 0: + allocate() + cap = 1 +else + reallocate + cap *= 2 +``` + +But Rust's only supported allocator API is so low level that we'll need to +do a fair bit of extra work, though. We also need to guard against some special +conditions that can occur with really large allocations. In particular, we index +into arrays using unsigned integers, but `ptr::offset` takes signed integers. This +means Bad Things will happen if we ever manage to grow to contain more than +`isize::MAX` elements. Thankfully, this isn't something we need to worry about +in most cases. + +On 64-bit targets we're artifically limited to only 48-bits, so we'll run out +of memory far before we reach that point. However on 32-bit targets, particularly +those with extensions to use more of the address space, it's theoretically possible +to successfully allocate more than `isize::MAX` bytes of memory. Still, we only +really need to worry about that if we're allocating elements that are a byte large. +Anything else will use up too much space. + +However since this is a tutorial, we're not going to be particularly optimal here, +and just unconditionally check, rather than use clever platform-specific `cfg`s. + +```rust +fn grow(&mut self) { + // this is all pretty delicate, so let's say it's all unsafe + unsafe { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + // as an invariant, we can assume that `self.cap < isize::MAX`, + // so this doesn't need to be checked. + let new_cap = self.cap * 2; + // Similarly this can't overflow due to previously allocating this + let old_num_bytes = self.cap * elem_size; + + // check that the new allocation doesn't exceed `isize::MAX` at all + // regardless of the actual size of the capacity. This combines the + // `new_cap <= isize::MAX` and `new_num_bytes <= usize::MAX` checks + // we need to make. We lose the ability to allocate e.g. 2/3rds of + // the address space with a single Vec of i16's on 32-bit though. + // Alas, poor Yorick -- I knew him, Horatio. + assert!(old_num_bytes <= (::std::isize::MAX as usize) / 2, + "capacity overflow"); + + let new_num_bytes = old_num_bytes * 2; + let ptr = heap::reallocate(*self.ptr as *mut _, + old_num_bytes, + new_num_bytes, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom(); } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } +} +``` + +Nothing particularly tricky here. Just computing sizes and alignments and doing +some careful multiplication checks. + diff --git a/vec-dealloc.md b/vec-dealloc.md new file mode 100644 index 0000000000000..a83d24d7b49c9 --- /dev/null +++ b/vec-dealloc.md @@ -0,0 +1,29 @@ +% Deallocating + +Next we should implement Drop so that we don't massively leak tons of resources. +The easiest way is to just call `pop` until it yields None, and then deallocate +our buffer. Note that calling `pop` is uneeded if `T: !Drop`. In theory we can +ask Rust if T needs_drop and omit the calls to `pop`. However in practice LLVM +is *really* good at removing simple side-effect free code like this, so I wouldn't +bother unless you notice it's not being stripped (in this case it is). + +We must not call `heap::deallocate` when `self.cap == 0`, as in this case we haven't +actually allocated any memory. + + +```rust +impl Drop for Vec { + fn drop(&mut self) { + if self.cap != 0 { + while let Some(_) = self.pop() { } + + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr, num_bytes, align); + } + } + } +} +``` diff --git a/vec-deref.md b/vec-deref.md new file mode 100644 index 0000000000000..b07d784939ae6 --- /dev/null +++ b/vec-deref.md @@ -0,0 +1,40 @@ +% Deref + +Alright! We've got a decent minimal ArrayStack implemented. We can push, we can +pop, and we can clean up after ourselves. However there's a whole mess of functionality +we'd reasonably want. In particular, we have a proper array, but none of the slice +functionality. That's actually pretty easy to solve: we can implement `Deref`. +This will magically make our Vec coerce to and behave like a slice in all sorts of +conditions. + +All we need is `slice::from_raw_parts`. + +```rust +use std::ops::Deref; + +impl Deref for Vec { + type Target = [T]; + fn deref(&self) -> &[T] { + unsafe { + ::std::slice::from_raw_parts(*self.ptr, self.len) + } + } +} +``` + +And let's do DerefMut too: + +```rust +use std::ops::DerefMut; + +impl DerefMut for Vec { + fn deref_mut(&mut self) -> &mut [T] { + unsafe { + ::std::slice::from_raw_parts_mut(*self.ptr, self.len) + } + } +} +``` + +Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, `iter_mut`, +and all other sorts of bells and whistles provided by slice. Sweet! diff --git a/vec-drain.md b/vec-drain.md new file mode 100644 index 0000000000000..0a53e8bdfad9c --- /dev/null +++ b/vec-drain.md @@ -0,0 +1,318 @@ +% Drain + +Let's move on to Drain. Drain is largely the same as IntoIter, except that +instead of consuming the Vec, it borrows the Vec and leaves its allocation +free. For now we'll only implement the "basic" full-range version. + +```rust,ignore +use std::marker::PhantomData; + +struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec> + start: *const T, + end: *const T, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None +``` + +-- wait, this is seeming familiar. Let's do some more compression. Both +IntoIter and Drain have the exact same structure, let's just factor it out. + +```rust +struct RawValIter { + start: *const T, + end: *const T, +} + +impl RawValIter { + // unsafe to construct because it has no associated lifetimes. + // This is necessary to store a RawValIter in the same struct as + // its actual allocation. OK since it's a private implementation + // detail. + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} + +// Iterator and DoubleEndedIterator impls identical to IntoIter. +``` + +And IntoIter becomes the following: + +``` +pub struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + iter: RawValIter, +} + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { self.iter.next() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl Drop for IntoIter { + fn drop(&mut self) { + for _ in &mut self.iter {} + } +} + +impl Vec { + pub fn into_iter(self) -> IntoIter { + unsafe { + let iter = RawValIter::new(&self); + let buf = ptr::read(&self.buf); + mem::forget(self); + + IntoIter { + iter: iter, + _buf: buf, + } + } + } +} +``` + +Note that I've left a few quirks in this design to make upgrading Drain to work +with arbitrary subranges a bit easier. In particular we *could* have RawValIter +drain itself on drop, but that won't work right for a more complex Drain. +We also take a slice to simplify Drain initialization. + +Alright, now Drain is really easy: + +```rust +use std::marker::PhantomData; + +pub struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec>, + iter: RawValIter, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { self.iter.next_back() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl<'a, T> DoubleEndedIterator for Drain<'a, T> { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl<'a, T> Drop for Drain<'a, T> { + fn drop(&mut self) { + for _ in &mut self.iter {} + } +} + +impl Vec { + pub fn drain(&mut self) -> Drain { + // this is a mem::forget safety thing. If Drain is forgotten, we just + // leak the whole Vec's contents. Also we need to do this *eventually* + // anyway, so why not do it now? + self.len = 0; + + unsafe { + Drain { + iter: RawValIter::new(&self), + vec: PhantomData, + } + } + } +} +``` + + + + +# Handling Zero-Sized Types + +It's time. We're going to fight the spectre that is zero-sized types. Safe Rust +*never* needs to care about this, but Vec is very intensive on raw pointers and +raw allocations, which are exactly the *only* two things that care about +zero-sized types. We need to be careful of two things: + +* The raw allocator API has undefined behaviour if you pass in 0 for an + allocation size. +* raw pointer offsets are no-ops for zero-sized types, which will break our + C-style pointer iterator. + +Thankfully we abstracted out pointer-iterators and allocating handling into +RawValIter and RawVec respectively. How mysteriously convenient. + + + + +## Allocating Zero-Sized Types + +So if the allocator API doesn't support zero-sized allocations, what on earth +do we store as our allocation? Why, `heap::EMPTY` of course! Almost every operation +with a ZST is a no-op since ZSTs have exactly one value, and therefore no state needs +to be considered to store or load them. This actually extends to `ptr::read` and +`ptr::write`: they won't actually look at the pointer at all. As such we *never* need +to change the pointer. + +Note however that our previous reliance on running out of memory before overflow is +no longer valid with zero-sized types. We must explicitly guard against capacity +overflow for zero-sized types. + +Due to our current architecture, all this means is writing 3 guards, one in each +method of RawVec. + +```rust +impl RawVec { + fn new() -> Self { + unsafe { + // !0 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { !0 } else { 0 }; + + // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } + } + } + + fn grow(&mut self) { + unsafe { + let elem_size = mem::size_of::(); + + // since we set the capacity to usize::MAX when elem_size is + // 0, getting to here necessarily means the Vec is overfull. + assert!(elem_size != 0, "capacity overflow"); + + let align = mem::min_align_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + +impl Drop for RawVec { + fn drop(&mut self) { + let elem_size = mem::size_of::(); + + // don't free zero-sized allocations, as they were never allocated. + if self.cap != 0 && elem_size != 0 { + let align = mem::min_align_of::(); + + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +That's it. We support pushing and popping zero-sized types now. Our iterators +(that aren't provided by slice Deref) are still busted, though. + + + + +## Iterating Zero-Sized Types + +Zero-sized offsets are no-ops. This means that our current design will always +initialize `start` and `end` as the same value, and our iterators will yield +nothing. The current solution to this is to cast the pointers to integers, +increment, and then cast them back: + +``` +impl RawValIter { + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if mem::size_of::() == 0 { + ((slice.as_ptr() as usize) + slice.len()) as *const _ + } else if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} +``` + +Now we have a different bug. Instead of our iterators not running at all, our +iterators now run *forever*. We need to do the same trick in our iterator impls. +Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll +basically be treating the two pointers as if they point to bytes, we'll just +map size 0 to divide by 1. + +``` +impl Iterator for RawValIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = if mem::size_of::() == 0 { + (self.start as usize + 1) as *const _ + } else { + self.start.offset(1); + } + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let elem_size = mem::size_of::(); + let len = (self.end as usize - self.start as usize) + / if elem_size == 0 { 1 } else { elem_size }; + (len, Some(len)) + } +} + +impl DoubleEndedIterator for RawValIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = if mem::size_of::() == 0 { + (self.end as usize - 1) as *const _ + } else { + self.end.offset(-1); + } + Some(ptr::read(self.end)) + } + } + } +} +``` + +And that's it. Iteration works! \ No newline at end of file diff --git a/vec-final.md b/vec-final.md new file mode 100644 index 0000000000000..96fcf6d471030 --- /dev/null +++ b/vec-final.md @@ -0,0 +1,309 @@ +% The Final Code + +```rust +#![feature(unique)] +#![feature(heap_api)] + +use std::ptr::{Unique, self}; +use std::rt::heap; +use std::mem; +use std::ops::{Deref, DerefMut}; +use std::marker::PhantomData; + + + + + +struct RawVec { + ptr: Unique, + cap: usize, +} + +impl RawVec { + fn new() -> Self { + unsafe { + // !0 is usize::MAX. This branch should be stripped at compile time. + let cap = if mem::size_of::() == 0 { !0 } else { 0 }; + + // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } + } + } + + fn grow(&mut self) { + unsafe { + let elem_size = mem::size_of::(); + + // since we set the capacity to usize::MAX when elem_size is + // 0, getting to here necessarily means the Vec is overfull. + assert!(elem_size != 0, "capacity overflow"); + + let align = mem::min_align_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + +impl Drop for RawVec { + fn drop(&mut self) { + let elem_size = mem::size_of::(); + if self.cap != 0 && elem_size != 0 { + let align = mem::min_align_of::(); + + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} + + + + + +pub struct Vec { + buf: RawVec, + len: usize, +} + +impl Vec { + fn ptr(&self) -> *mut T { *self.buf.ptr } + + fn cap(&self) -> usize { self.buf.cap } + + pub fn new() -> Self { + Vec { buf: RawVec::new(), len: 0 } + } + pub fn push(&mut self, elem: T) { + if self.len == self.cap() { self.buf.grow(); } + + unsafe { + ptr::write(self.ptr().offset(self.len as isize), elem); + } + + // Can't fail, we'll OOM first. + self.len += 1; + } + + pub fn pop(&mut self) -> Option { + if self.len == 0 { + None + } else { + self.len -= 1; + unsafe { + Some(ptr::read(self.ptr().offset(self.len as isize))) + } + } + } + + pub fn insert(&mut self, index: usize, elem: T) { + assert!(index <= self.len, "index out of bounds"); + if self.cap() == self.len { self.buf.grow(); } + + unsafe { + if index < self.len { + ptr::copy(self.ptr().offset(index as isize), + self.ptr().offset(index as isize + 1), + self.len - index); + } + ptr::write(self.ptr().offset(index as isize), elem); + self.len += 1; + } + } + + pub fn remove(&mut self, index: usize) -> T { + assert!(index < self.len, "index out of bounds"); + unsafe { + self.len -= 1; + let result = ptr::read(self.ptr().offset(index as isize)); + ptr::copy(self.ptr().offset(index as isize + 1), + self.ptr().offset(index as isize), + self.len - index); + result + } + } + + pub fn into_iter(self) -> IntoIter { + unsafe { + let iter = RawValIter::new(&self); + let buf = ptr::read(&self.buf); + mem::forget(self); + + IntoIter { + iter: iter, + _buf: buf, + } + } + } + + pub fn drain(&mut self) -> Drain { + // this is a mem::forget safety thing. If this is forgotten, we just + // leak the whole Vec's contents. Also we need to do this *eventually* + // anyway, so why not do it now? + self.len = 0; + unsafe { + Drain { + iter: RawValIter::new(&self), + vec: PhantomData, + } + } + } +} + +impl Drop for Vec { + fn drop(&mut self) { + while let Some(_) = self.pop() {} + // allocation is handled by RawVec + } +} + +impl Deref for Vec { + type Target = [T]; + fn deref(&self) -> &[T] { + unsafe { + ::std::slice::from_raw_parts(self.ptr(), self.len) + } + } +} + +impl DerefMut for Vec { + fn deref_mut(&mut self) -> &mut [T] { + unsafe { + ::std::slice::from_raw_parts_mut(self.ptr(), self.len) + } + } +} + + + + + +struct RawValIter { + start: *const T, + end: *const T, +} + +impl RawValIter { + unsafe fn new(slice: &[T]) -> Self { + RawValIter { + start: slice.as_ptr(), + end: if mem::size_of::() == 0 { + ((slice.as_ptr() as usize) + slice.len()) as *const _ + } else if slice.len() == 0 { + slice.as_ptr() + } else { + slice.as_ptr().offset(slice.len() as isize) + } + } + } +} + +impl Iterator for RawValIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = self.start.offset(1); + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let elem_size = mem::size_of::(); + let len = (self.end as usize - self.start as usize) + / if elem_size == 0 { 1 } else { elem_size }; + (len, Some(len)) + } +} + +impl DoubleEndedIterator for RawValIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = self.end.offset(-1); + Some(ptr::read(self.end)) + } + } + } +} + + + + +pub struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + iter: RawValIter, +} + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { self.iter.next() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl Drop for IntoIter { + fn drop(&mut self) { + for _ in &mut *self {} + } +} + + + + +pub struct Drain<'a, T: 'a> { + vec: PhantomData<&'a mut Vec>, + iter: RawValIter, +} + +impl<'a, T> Iterator for Drain<'a, T> { + type Item = T; + fn next(&mut self) -> Option { self.iter.next_back() } + fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } +} + +impl<'a, T> DoubleEndedIterator for Drain<'a, T> { + fn next_back(&mut self) -> Option { self.iter.next_back() } +} + +impl<'a, T> Drop for Drain<'a, T> { + fn drop(&mut self) { + // pre-drain the iter + for _ in &mut self.iter {} + } +} + +/// Abort the process, we're out of memory! +/// +/// In practice this is probably dead code on most OSes +fn oom() { + ::std::process::exit(-9999); +} +``` \ No newline at end of file diff --git a/vec-insert-remove.md b/vec-insert-remove.md new file mode 100644 index 0000000000000..42d114c4a4495 --- /dev/null +++ b/vec-insert-remove.md @@ -0,0 +1,50 @@ +% Insert and Remove + +Something *not* provided but slice is `insert` and `remove`, so let's do those next. + +Insert needs to shift all the elements at the target index to the right by one. +To do this we need to use `ptr::copy`, which is our version of C's `memmove`. +This copies some chunk of memory from one location to another, correctly handling +the case where the source and destination overlap (which will definitely happen +here). + +If we insert at index `i`, we want to shift the `[i .. len]` to `[i+1 .. len+1]` +using the *old* len. + +```rust +pub fn insert(&mut self, index: usize, elem: T) { + // Note: `<=` because it's valid to insert after everything + // which would be equivalent to push. + assert!(index <= self.len, "index out of bounds"); + if self.cap == self.len { self.grow(); } + + unsafe { + if index < self.len { + // ptr::copy(src, dest, len): "copy from source to dest len elems" + ptr::copy(self.ptr.offset(index as isize), + self.ptr.offset(index as isize + 1), + len - index); + } + ptr::write(self.ptr.offset(index as isize), elem); + self.len += 1; + } +} +``` + +Remove behaves in the opposite manner. We need to shift all the elements from +`[i+1 .. len + 1]` to `[i .. len]` using the *new* len. + +```rust +pub fn remove(&mut self, index: usize) -> T { + // Note: `<` because it's *not* valid to remove after everything + assert!(index < self.len, "index out of bounds"); + unsafe { + self.len -= 1; + let result = ptr::read(self.ptr.offset(index as isize)); + ptr::copy(self.ptr.offset(index as isize + 1), + self.ptr.offset(index as isize), + len - index); + result + } +} +``` \ No newline at end of file diff --git a/vec-into-iter.md b/vec-into-iter.md new file mode 100644 index 0000000000000..b7e7d2bdc42df --- /dev/null +++ b/vec-into-iter.md @@ -0,0 +1,293 @@ +% IntoIter + +Let's move on to writing iterators. `iter` and `iter_mut` have already been +written for us thanks to The Magic of Deref. However there's two interesting +iterators that Vec provides that slices can't: `into_iter` and `drain`. + +IntoIter consumes the Vec by-value, and can consequently yield its elements +by-value. In order to enable this, IntoIter needs to take control of Vec's +allocation. + +IntoIter needs to be DoubleEnded as well, to enable reading from both ends. +Reading from the back could just be implemented as calling `pop`, but reading +from the front is harder. We could call `remove(0)` but that would be insanely +expensive. Instead we're going to just use ptr::read to copy values out of either +end of the Vec without mutating the buffer at all. + +To do this we're going to use a very common C idiom for array iteration. We'll +make two pointers; one that points to the start of the array, and one that points +to one-element past the end. When we want an element from one end, we'll read out +the value pointed to at that end and move the pointer over by one. When the two +pointers are equal, we know we're done. + +Note that the order of read and offset are reversed for `next` and `next_back` +For `next_back` the pointer is always *after* the element it wants to read next, +while for `next` the pointer is always *at* the element it wants to read next. +To see why this is, consider the case where every element but one has been yielded. + +The array looks like this: + +```text + S E +[X, X, X, O, X, X, X] +``` + +If E pointed directly at the element it wanted to yield next, it would be +indistinguishable from the case where there are no more elements to yield. + +So we're going to use the following struct: + +```rust +struct IntoIter { + buf: Unique, + cap: usize, + start: *const T, + end: *const T, +} +``` + +One last subtle detail: if our Vec is empty, we want to produce an empty iterator. +This will actually technically fall out doing the naive thing of: + +```text +start = ptr +end = ptr.offset(len) +``` + +However because `offset` is marked as a GEP inbounds instruction, this will tell +LLVM that ptr is allocated and won't alias other allocated memory. This is fine +for zero-sized types, as they can't alias anything. However if we're using +`heap::EMPTY` as a sentinel for a non-allocation for a *non-zero-sized* type, +this can cause undefined behaviour. Alas, we must therefore special case either +cap or len being 0 to not do the offset. + +So this is what we end up with for initialization: + +```rust +impl Vec { + fn into_iter(self) -> IntoIter { + // Can't destructure Vec since it's Drop + let ptr = self.ptr; + let cap = self.cap; + let len = self.len; + + // Make sure not to drop Vec since that will free the buffer + mem::forget(self); + + unsafe { + IntoIter { + buf: ptr, + cap: cap, + start: *ptr, + end: if cap == 0 { + // can't offset off this pointer, it's not allocated! + *ptr + } else { + ptr.offset(len as isize) + } + } + } + } +} +``` + +Here's iterating forward: + +```rust +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + let result = ptr::read(self.start); + self.start = self.start.offset(1); + Some(result) + } + } + } + + fn size_hint(&self) -> (usize, Option) { + let len = (self.end as usize - self.start as usize) + / mem::size_of::(); + (len, Some(len)) + } +} +``` + +And here's iterating backwards. + +```rust +impl DoubleEndedIterator for IntoIter { + fn next_back(&mut self) -> Option { + if self.start == self.end { + None + } else { + unsafe { + self.end = self.end.offset(-1); + Some(ptr::read(self.end)) + } + } + } +} +``` + +Because IntoIter takes ownership of its allocation, it needs to implement Drop +to free it. However it *also* wants to implement Drop to drop any elements it +contains that weren't yielded. + + +```rust +impl Drop for IntoIter { + fn drop(&mut self) { + if self.cap != 0 { + // drop any remaining elements + for _ in &mut *self {} + + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.buf as *mut _, num_bytes, align); + } + } + } +} +``` + +We've actually reached an interesting situation here: we've duplicated the logic +for specifying a buffer and freeing its memory. Now that we've implemented it and +identified *actual* logic duplication, this is a good time to perform some logic +compression. + +We're going to abstract out the `(ptr, cap)` pair and give them the logic for +allocating, growing, and freeing: + +```rust + +struct RawVec { + ptr: Unique, + cap: usize, +} + +impl RawVec { + fn new() -> Self { + assert!(mem::size_of::() != 0, "TODO: implement ZST support"); + unsafe { + RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: 0 } + } + } + + // unchanged from Vec + fn grow(&mut self) { + unsafe { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + + let (new_cap, ptr) = if self.cap == 0 { + let ptr = heap::allocate(elem_size, align); + (1, ptr) + } else { + let new_cap = 2 * self.cap; + let ptr = heap::reallocate(*self.ptr as *mut _, + self.cap * elem_size, + new_cap * elem_size, + align); + (new_cap, ptr) + }; + + // If allocate or reallocate fail, we'll get `null` back + if ptr.is_null() { oom() } + + self.ptr = Unique::new(ptr as *mut _); + self.cap = new_cap; + } + } +} + + +impl Drop for RawVec { + fn drop(&mut self) { + if self.cap != 0 { + let align = mem::min_align_of::(); + let elem_size = mem::size_of::(); + let num_bytes = elem_size * self.cap; + unsafe { + heap::deallocate(*self.ptr as *mut _, num_bytes, align); + } + } + } +} +``` + +And change vec as follows: + +```rust +pub struct Vec { + buf: RawVec, + len: usize, +} + +impl Vec { + fn ptr(&self) -> *mut T { *self.buf.ptr } + + fn cap(&self) -> usize { self.buf.cap } + + pub fn new() -> Self { + Vec { buf: RawVec::new(), len: 0 } + } + + // push/pop/insert/remove largely unchanged: + // * `self.ptr -> self.ptr()` + // * `self.cap -> self.cap()` + // * `self.grow -> self.buf.grow()` +} + +impl Drop for Vec { + fn drop(&mut self) { + while let Some(_) = self.pop() {} + // deallocation is handled by RawVec + } +} +``` + +And finally we can really simplify IntoIter: + +```rust +struct IntoIter { + _buf: RawVec, // we don't actually care about this. Just need it to live. + start: *const T, + end: *const T, +} + +// next and next_back litterally unchanged since they never referred to the buf + +impl Drop for IntoIter { + fn drop(&mut self) { + // only need to ensure all our elements are read; + // buffer will clean itself up afterwards. + for _ in &mut *self {} + } +} + +impl Vec { + pub fn into_iter(self) -> IntoIter { + unsafe { + // need to use ptr::read to unsafely move the buf out since it's + // not Copy. + let buf = ptr::read(&self.buf); + let len = self.len; + mem::forget(self); + + IntoIter { + start: *buf.ptr, + end: buf.ptr.offset(len as isize), + _buf: buf, + } + } + } +} +``` + +Much better. \ No newline at end of file diff --git a/vec-layout.md b/vec-layout.md new file mode 100644 index 0000000000000..0f85e4d27cefe --- /dev/null +++ b/vec-layout.md @@ -0,0 +1,61 @@ +% Layout + +First off, we need to come up with the struct layout. Naively we want this +design: + +```rust +struct Vec { + ptr: *mut T, + cap: usize, + len: usize, +} +``` + +And indeed this would compile. Unfortunately, it would be incorrect. The compiler +will give us too strict variance, so e.g. an `&Vec<&'static str>` couldn't be used +where an `&Vec<&'a str>` was expected. More importantly, it will give incorrect +ownership information to dropck, as it will conservatively assume we don't own +any values of type `T`. See [the chapter on ownership and lifetimes] +(lifetimes.html) for details. + +As we saw in the lifetimes chapter, we should use `Unique` in place of `*mut T` +when we have a raw pointer to an allocation we own: + + +```rust +#![feature(unique)] + +use std::ptr::{Unique, self}; + +pub struct Vec { + ptr: Unique, + cap: usize, + len: usize, +} +``` + +As a recap, Unique is a wrapper around a raw pointer that declares that: + +* We own at least one value of type `T` +* We are Send/Sync iff `T` is Send/Sync +* Our pointer is never null (and therefore `Option` is null-pointer-optimized) + +That last point is subtle. First, it makes `Unique::new` unsafe to call, because +putting `null` inside of it is Undefined Behaviour. It also throws a +wrench in an important feature of Vec (and indeed all of the std collections): +an empty Vec doesn't actually allocate at all. So if we can't allocate, +but also can't put a null pointer in `ptr`, what do we do in +`Vec::new`? Well, we just put some other garbage in there! + +This is perfectly fine because we already have `cap == 0` as our sentinel for no +allocation. We don't even need to handle it specially in almost any code because +we usually need to check if `cap > len` or `len > 0` anyway. The traditional +Rust value to put here is `0x01`. The standard library actually exposes this +as `std::rt::heap::EMPTY`. There are quite a few places where we'll want to use +`heap::EMPTY` because there's no real allocation to talk about but `null` would +make the compiler angry. + +All of the `heap` API is totally unstable under the `heap_api` feature, though. +We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of +the `heap` API anyway, so let's just get that dependency over with. + diff --git a/vec-push-pop.md b/vec-push-pop.md new file mode 100644 index 0000000000000..d1584a2342100 --- /dev/null +++ b/vec-push-pop.md @@ -0,0 +1,55 @@ +% Push and Pop + +Alright. We can initialize. We can allocate. Let's actually implement some +functionality! Let's start with `push`. All it needs to do is check if we're +full to grow, unconditionally write to the next index, and then increment our +length. + +To do the write we have to be careful not to evaluate the memory we want to write +to. At worst, it's truly uninitialized memory from the allocator. At best it's the +bits of some old value we popped off. Either way, we can't just index to the memory +and dereference it, because that will evaluate the memory as a valid instance of +T. Worse, `foo[idx] = x` will try to call `drop` on the old value of `foo[idx]`! + +The correct way to do this is with `ptr::write`, which just blindly overwrites the +target address with the bits of the value we provide. No evaluation involved. + +For `push`, if the old len (before push was called) is 0, then we want to write +to the 0th index. So we should offset by the old len. + +```rust +pub fn push(&mut self, elem: T) { + if self.len == self.cap { self.grow(); } + + unsafe { + ptr::write(self.ptr.offset(self.len as isize), elem); + } + + // Can't fail, we'll OOM first. + self.len += 1; +} +``` + +Easy! How about `pop`? Although this time the index we want to access is +initialized, Rust won't just let us dereference the location of memory to move +the value out, because that *would* leave the memory uninitialized! For this we +need `ptr::read`, which just copies out the bits from the target address and +intrprets it as a value of type T. This will leave the memory at this address +*logically* uninitialized, even though there is in fact a perfectly good instance +of T there. + +For `pop`, if the old len is 1, we want to read out of the 0th index. So we +should offset by the *new* len. + +```rust +pub fn pop(&mut self) -> Option { + if self.len == 0 { + None + } else { + self.len -= 1; + unsafe { + Some(ptr::read(self.ptr.offset(self.len as isize))) + } + } +} +``` \ No newline at end of file diff --git a/vec.md b/vec.md index 2b4e35e7653f8..a613f259b70f2 100644 --- a/vec.md +++ b/vec.md @@ -4,1320 +4,3 @@ To bring everything together, we're going to write `std::Vec` from scratch. Because all the best tools for writing unsafe code are unstable, this project will only work on nightly (as of Rust 1.2.0). - - -# Layout - -First off, we need to come up with the struct layout. Naively we want this -design: - -```rust -struct Vec { - ptr: *mut T, - cap: usize, - len: usize, -} -``` - -And indeed this would compile. Unfortunately, it would be incorrect. The compiler -will give us too strict variance, so e.g. an `&Vec<&'static str>` couldn't be used -where an `&Vec<&'a str>` was expected. More importantly, it will give incorrect -ownership information to dropck, as it will conservatively assume we don't own -any values of type `T`. See [the chapter on ownership and lifetimes] -(lifetimes.html) for details. - -As we saw in the lifetimes chapter, we should use `Unique` in place of `*mut T` -when we have a raw pointer to an allocation we own: - - -```rust -#![feature(unique)] - -use std::ptr::{Unique, self}; - -pub struct Vec { - ptr: Unique, - cap: usize, - len: usize, -} -``` - -As a recap, Unique is a wrapper around a raw pointer that declares that: - -* We own at least one value of type `T` -* We are Send/Sync iff `T` is Send/Sync -* Our pointer is never null (and therefore `Option` is null-pointer-optimized) - -That last point is subtle. First, it makes `Unique::new` unsafe to call, because -putting `null` inside of it is Undefined Behaviour. It also throws a -wrench in an important feature of Vec (and indeed all of the std collections): -an empty Vec doesn't actually allocate at all. So if we can't allocate, -but also can't put a null pointer in `ptr`, what do we do in -`Vec::new`? Well, we just put some other garbage in there! - -This is perfectly fine because we already have `cap == 0` as our sentinel for no -allocation. We don't even need to handle it specially in almost any code because -we usually need to check if `cap > len` or `len > 0` anyway. The traditional -Rust value to put here is `0x01`. The standard library actually exposes this -as `std::rt::heap::EMPTY`. There are quite a few places where we'll want to use -`heap::EMPTY` because there's no real allocation to talk about but `null` would -make the compiler angry. - -All of the `heap` API is totally unstable under the `heap_api` feature, though. -We could trivially define `heap::EMPTY` ourselves, but we'll want the rest of -the `heap` API anyway, so let's just get that dependency over with. - - - - -# Allocating Memory - -So: - -```rust -#![feature(heap_api)] - -use std::rt::heap::EMPTY; -use std::mem; - -impl Vec { - fn new() -> Self { - assert!(mem::size_of::() != 0, "We're not ready to handle ZSTs"); - unsafe { - // need to cast EMPTY to the actual ptr type we want, let - // inference handle it. - Vec { ptr: Unique::new(heap::EMPTY as *mut _), len: 0, cap: 0 } - } - } -} -``` - -I slipped in that assert there because zero-sized types will require some -special handling throughout our code, and I want to defer the issue for now. -Without this assert, some of our early drafts will do some Very Bad Things. - -Next we need to figure out what to actually do when we *do* want space. For that, -we'll need to use the rest of the heap APIs. These basically allow us to -talk directly to Rust's instance of jemalloc. - -We'll also need a way to handle out-of-memory conditions. The standard library -calls the `abort` intrinsic, but calling intrinsics from normal Rust code is a -pretty bad idea. Unfortunately, the `abort` exposed by the standard library -allocates. Not something we want to do during `oom`! Instead, we'll call -`std::process::exit`. - -```rust -fn oom() { - ::std::process::exit(-9999); -} -``` - -Okay, now we can write growing. Roughly, we want to have this logic: - -```text -if cap == 0: - allocate() - cap = 1 -else - reallocate - cap *= 2 -``` - -But Rust's only supported allocator API is so low level that we'll need to -do a fair bit of extra work, though. We also need to guard against some special -conditions that can occur with really large allocations. In particular, we index -into arrays using unsigned integers, but `ptr::offset` takes signed integers. This -means Bad Things will happen if we ever manage to grow to contain more than -`isize::MAX` elements. Thankfully, this isn't something we need to worry about -in most cases. - -On 64-bit targets we're artifically limited to only 48-bits, so we'll run out -of memory far before we reach that point. However on 32-bit targets, particularly -those with extensions to use more of the address space, it's theoretically possible -to successfully allocate more than `isize::MAX` bytes of memory. Still, we only -really need to worry about that if we're allocating elements that are a byte large. -Anything else will use up too much space. - -However since this is a tutorial, we're not going to be particularly optimal here, -and just unconditionally check, rather than use clever platform-specific `cfg`s. - -```rust -fn grow(&mut self) { - // this is all pretty delicate, so let's say it's all unsafe - unsafe { - let align = mem::min_align_of::(); - let elem_size = mem::size_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - // as an invariant, we can assume that `self.cap < isize::MAX`, - // so this doesn't need to be checked. - let new_cap = self.cap * 2; - // Similarly this can't overflow due to previously allocating this - let old_num_bytes = self.cap * elem_size; - - // check that the new allocation doesn't exceed `isize::MAX` at all - // regardless of the actual size of the capacity. This combines the - // `new_cap <= isize::MAX` and `new_num_bytes <= usize::MAX` checks - // we need to make. We lose the ability to allocate e.g. 2/3rds of - // the address space with a single Vec of i16's on 32-bit though. - // Alas, poor Yorick -- I knew him, Horatio. - assert!(old_num_bytes <= (::std::isize::MAX as usize) / 2, - "capacity overflow"); - - let new_num_bytes = old_num_bytes * 2; - let ptr = heap::reallocate(*self.ptr as *mut _, - old_num_bytes, - new_num_bytes, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom(); } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } -} -``` - -Nothing particularly tricky here. Just computing sizes and alignments and doing -some careful multiplication checks. - - - - - -# Push and Pop - -Alright. We can initialize. We can allocate. Let's actually implement some -functionality! Let's start with `push`. All it needs to do is check if we're -full to grow, unconditionally write to the next index, and then increment our -length. - -To do the write we have to be careful not to evaluate the memory we want to write -to. At worst, it's truly uninitialized memory from the allocator. At best it's the -bits of some old value we popped off. Either way, we can't just index to the memory -and dereference it, because that will evaluate the memory as a valid instance of -T. Worse, `foo[idx] = x` will try to call `drop` on the old value of `foo[idx]`! - -The correct way to do this is with `ptr::write`, which just blindly overwrites the -target address with the bits of the value we provide. No evaluation involved. - -For `push`, if the old len (before push was called) is 0, then we want to write -to the 0th index. So we should offset by the old len. - -```rust -pub fn push(&mut self, elem: T) { - if self.len == self.cap { self.grow(); } - - unsafe { - ptr::write(self.ptr.offset(self.len as isize), elem); - } - - // Can't fail, we'll OOM first. - self.len += 1; -} -``` - -Easy! How about `pop`? Although this time the index we want to access is -initialized, Rust won't just let us dereference the location of memory to move -the value out, because that *would* leave the memory uninitialized! For this we -need `ptr::read`, which just copies out the bits from the target address and -intrprets it as a value of type T. This will leave the memory at this address -*logically* uninitialized, even though there is in fact a perfectly good instance -of T there. - -For `pop`, if the old len is 1, we want to read out of the 0th index. So we -should offset by the *new* len. - -```rust -pub fn pop(&mut self) -> Option { - if self.len == 0 { - None - } else { - self.len -= 1; - unsafe { - Some(ptr::read(self.ptr.offset(self.len as isize))) - } - } -} -``` - - - - - -# Deallocating - -Next we should implement Drop so that we don't massively leak tons of resources. -The easiest way is to just call `pop` until it yields None, and then deallocate -our buffer. Note that calling `pop` is uneeded if `T: !Drop`. In theory we can -ask Rust if T needs_drop and omit the calls to `pop`. However in practice LLVM -is *really* good at removing simple side-effect free code like this, so I wouldn't -bother unless you notice it's not being stripped (in this case it is). - -We must not call `heap::deallocate` when `self.cap == 0`, as in this case we haven't -actually allocated any memory. - - -```rust -impl Drop for Vec { - fn drop(&mut self) { - if self.cap != 0 { - while let Some(_) = self.pop() { } - - let align = mem::min_align_of::(); - let elem_size = mem::size_of::(); - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr, num_bytes, align); - } - } - } -} -``` - - - - - -# Deref - -Alright! We've got a decent minimal ArrayStack implemented. We can push, we can -pop, and we can clean up after ourselves. However there's a whole mess of functionality -we'd reasonably want. In particular, we have a proper array, but none of the slice -functionality. That's actually pretty easy to solve: we can implement `Deref`. -This will magically make our Vec coerce to and behave like a slice in all sorts of -conditions. - -All we need is `slice::from_raw_parts`. - -```rust -use std::ops::Deref; - -impl Deref for Vec { - type Target = [T]; - fn deref(&self) -> &[T] { - unsafe { - ::std::slice::from_raw_parts(*self.ptr, self.len) - } - } -} -``` - -And let's do DerefMut too: - -```rust -use std::ops::DerefMut; - -impl DerefMut for Vec { - fn deref_mut(&mut self) -> &mut [T] { - unsafe { - ::std::slice::from_raw_parts_mut(*self.ptr, self.len) - } - } -} -``` - -Now we have `len`, `first`, `last`, indexing, slicing, sorting, `iter`, `iter_mut`, -and all other sorts of bells and whistles provided by slice. Sweet! - - - - - -# Insert and Remove - -Something *not* provided but slice is `insert` and `remove`, so let's do those next. - -Insert needs to shift all the elements at the target index to the right by one. -To do this we need to use `ptr::copy`, which is our version of C's `memmove`. -This copies some chunk of memory from one location to another, correctly handling -the case where the source and destination overlap (which will definitely happen -here). - -If we insert at index `i`, we want to shift the `[i .. len]` to `[i+1 .. len+1]` -using the *old* len. - -```rust -pub fn insert(&mut self, index: usize, elem: T) { - // Note: `<=` because it's valid to insert after everything - // which would be equivalent to push. - assert!(index <= self.len, "index out of bounds"); - if self.cap == self.len { self.grow(); } - - unsafe { - if index < self.len { - // ptr::copy(src, dest, len): "copy from source to dest len elems" - ptr::copy(self.ptr.offset(index as isize), - self.ptr.offset(index as isize + 1), - len - index); - } - ptr::write(self.ptr.offset(index as isize), elem); - self.len += 1; - } -} -``` - -Remove behaves in the opposite manner. We need to shift all the elements from -`[i+1 .. len + 1]` to `[i .. len]` using the *new* len. - -```rust -pub fn remove(&mut self, index: usize) -> T { - // Note: `<` because it's *not* valid to remove after everything - assert!(index < self.len, "index out of bounds"); - unsafe { - self.len -= 1; - let result = ptr::read(self.ptr.offset(index as isize)); - ptr::copy(self.ptr.offset(index as isize + 1), - self.ptr.offset(index as isize), - len - index); - result - } -} -``` - - - - - -# IntoIter - -Let's move on to writing iterators. `iter` and `iter_mut` have already been -written for us thanks to The Magic of Deref. However there's two interesting -iterators that Vec provides that slices can't: `into_iter` and `drain`. - -IntoIter consumes the Vec by-value, and can consequently yield its elements -by-value. In order to enable this, IntoIter needs to take control of Vec's -allocation. - -IntoIter needs to be DoubleEnded as well, to enable reading from both ends. -Reading from the back could just be implemented as calling `pop`, but reading -from the front is harder. We could call `remove(0)` but that would be insanely -expensive. Instead we're going to just use ptr::read to copy values out of either -end of the Vec without mutating the buffer at all. - -To do this we're going to use a very common C idiom for array iteration. We'll -make two pointers; one that points to the start of the array, and one that points -to one-element past the end. When we want an element from one end, we'll read out -the value pointed to at that end and move the pointer over by one. When the two -pointers are equal, we know we're done. - -Note that the order of read and offset are reversed for `next` and `next_back` -For `next_back` the pointer is always *after* the element it wants to read next, -while for `next` the pointer is always *at* the element it wants to read next. -To see why this is, consider the case where every element but one has been yielded. - -The array looks like this: - -```text - S E -[X, X, X, O, X, X, X] -``` - -If E pointed directly at the element it wanted to yield next, it would be -indistinguishable from the case where there are no more elements to yield. - -So we're going to use the following struct: - -```rust -struct IntoIter { - buf: Unique, - cap: usize, - start: *const T, - end: *const T, -} -``` - -One last subtle detail: if our Vec is empty, we want to produce an empty iterator. -This will actually technically fall out doing the naive thing of: - -```text -start = ptr -end = ptr.offset(len) -``` - -However because `offset` is marked as a GEP inbounds instruction, this will tell -LLVM that ptr is allocated and won't alias other allocated memory. This is fine -for zero-sized types, as they can't alias anything. However if we're using -`heap::EMPTY` as a sentinel for a non-allocation for a *non-zero-sized* type, -this can cause undefined behaviour. Alas, we must therefore special case either -cap or len being 0 to not do the offset. - -So this is what we end up with for initialization: - -```rust -impl Vec { - fn into_iter(self) -> IntoIter { - // Can't destructure Vec since it's Drop - let ptr = self.ptr; - let cap = self.cap; - let len = self.len; - - // Make sure not to drop Vec since that will free the buffer - mem::forget(self); - - unsafe { - IntoIter { - buf: ptr, - cap: cap, - start: *ptr, - end: if cap == 0 { - // can't offset off this pointer, it's not allocated! - *ptr - } else { - ptr.offset(len as isize) - } - } - } - } -} -``` - -Here's iterating forward: - -```rust -impl Iterator for IntoIter { - type Item = T; - fn next(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - let result = ptr::read(self.start); - self.start = self.start.offset(1); - Some(result) - } - } - } - - fn size_hint(&self) -> (usize, Option) { - let len = (self.end as usize - self.start as usize) - / mem::size_of::(); - (len, Some(len)) - } -} -``` - -And here's iterating backwards. - -```rust -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - self.end = self.end.offset(-1); - Some(ptr::read(self.end)) - } - } - } -} -``` - -Because IntoIter takes ownership of its allocation, it needs to implement Drop -to free it. However it *also* wants to implement Drop to drop any elements it -contains that weren't yielded. - - -```rust -impl Drop for IntoIter { - fn drop(&mut self) { - if self.cap != 0 { - // drop any remaining elements - for _ in &mut *self {} - - let align = mem::min_align_of::(); - let elem_size = mem::size_of::(); - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.buf as *mut _, num_bytes, align); - } - } - } -} -``` - -We've actually reached an interesting situation here: we've duplicated the logic -for specifying a buffer and freeing its memory. Now that we've implemented it and -identified *actual* logic duplication, this is a good time to perform some logic -compression. - -We're going to abstract out the `(ptr, cap)` pair and give them the logic for -allocating, growing, and freeing: - -```rust - -struct RawVec { - ptr: Unique, - cap: usize, -} - -impl RawVec { - fn new() -> Self { - assert!(mem::size_of::() != 0, "TODO: implement ZST support"); - unsafe { - RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: 0 } - } - } - - // unchanged from Vec - fn grow(&mut self) { - unsafe { - let align = mem::min_align_of::(); - let elem_size = mem::size_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - let new_cap = 2 * self.cap; - let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } - } -} - - -impl Drop for RawVec { - fn drop(&mut self) { - if self.cap != 0 { - let align = mem::min_align_of::(); - let elem_size = mem::size_of::(); - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr as *mut _, num_bytes, align); - } - } - } -} -``` - -And change vec as follows: - -```rust -pub struct Vec { - buf: RawVec, - len: usize, -} - -impl Vec { - fn ptr(&self) -> *mut T { *self.buf.ptr } - - fn cap(&self) -> usize { self.buf.cap } - - pub fn new() -> Self { - Vec { buf: RawVec::new(), len: 0 } - } - - // push/pop/insert/remove largely unchanged: - // * `self.ptr -> self.ptr()` - // * `self.cap -> self.cap()` - // * `self.grow -> self.buf.grow()` -} - -impl Drop for Vec { - fn drop(&mut self) { - while let Some(_) = self.pop() {} - // deallocation is handled by RawVec - } -} -``` - -And finally we can really simplify IntoIter: - -```rust -struct IntoIter { - _buf: RawVec, // we don't actually care about this. Just need it to live. - start: *const T, - end: *const T, -} - -// next and next_back litterally unchanged since they never referred to the buf - -impl Drop for IntoIter { - fn drop(&mut self) { - // only need to ensure all our elements are read; - // buffer will clean itself up afterwards. - for _ in &mut *self {} - } -} - -impl Vec { - pub fn into_iter(self) -> IntoIter { - unsafe { - // need to use ptr::read to unsafely move the buf out since it's - // not Copy. - let buf = ptr::read(&self.buf); - let len = self.len; - mem::forget(self); - - IntoIter { - start: *buf.ptr, - end: buf.ptr.offset(len as isize), - _buf: buf, - } - } - } -} -``` - -Much better. - - - - - -# Drain - -Let's move on to Drain. Drain is largely the same as IntoIter, except that -instead of consuming the Vec, it borrows the Vec and leaves its allocation -free. For now we'll only implement the "basic" full-range version. - -```rust,ignore -use std::marker::PhantomData; - -struct Drain<'a, T: 'a> { - vec: PhantomData<&'a mut Vec> - start: *const T, - end: *const T, -} - -impl<'a, T> Iterator for Drain<'a, T> { - type Item = T; - fn next(&mut self) -> Option { - if self.start == self.end { - None -``` - --- wait, this is seeming familiar. Let's do some more compression. Both -IntoIter and Drain have the exact same structure, let's just factor it out. - -```rust -struct RawValIter { - start: *const T, - end: *const T, -} - -impl RawValIter { - // unsafe to construct because it has no associated lifetimes. - // This is necessary to store a RawValIter in the same struct as - // its actual allocation. OK since it's a private implementation - // detail. - unsafe fn new(slice: &[T]) -> Self { - RawValIter { - start: slice.as_ptr(), - end: if slice.len() == 0 { - slice.as_ptr() - } else { - slice.as_ptr().offset(slice.len() as isize) - } - } - } -} - -// Iterator and DoubleEndedIterator impls identical to IntoIter. -``` - -And IntoIter becomes the following: - -``` -pub struct IntoIter { - _buf: RawVec, // we don't actually care about this. Just need it to live. - iter: RawValIter, -} - -impl Iterator for IntoIter { - type Item = T; - fn next(&mut self) -> Option { self.iter.next() } - fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } -} - -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option { self.iter.next_back() } -} - -impl Drop for IntoIter { - fn drop(&mut self) { - for _ in &mut self.iter {} - } -} - -impl Vec { - pub fn into_iter(self) -> IntoIter { - unsafe { - let iter = RawValIter::new(&self); - let buf = ptr::read(&self.buf); - mem::forget(self); - - IntoIter { - iter: iter, - _buf: buf, - } - } - } -} -``` - -Note that I've left a few quirks in this design to make upgrading Drain to work -with arbitrary subranges a bit easier. In particular we *could* have RawValIter -drain itself on drop, but that won't work right for a more complex Drain. -We also take a slice to simplify Drain initialization. - -Alright, now Drain is really easy: - -```rust -use std::marker::PhantomData; - -pub struct Drain<'a, T: 'a> { - vec: PhantomData<&'a mut Vec>, - iter: RawValIter, -} - -impl<'a, T> Iterator for Drain<'a, T> { - type Item = T; - fn next(&mut self) -> Option { self.iter.next_back() } - fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } -} - -impl<'a, T> DoubleEndedIterator for Drain<'a, T> { - fn next_back(&mut self) -> Option { self.iter.next_back() } -} - -impl<'a, T> Drop for Drain<'a, T> { - fn drop(&mut self) { - for _ in &mut self.iter {} - } -} - -impl Vec { - pub fn drain(&mut self) -> Drain { - // this is a mem::forget safety thing. If Drain is forgotten, we just - // leak the whole Vec's contents. Also we need to do this *eventually* - // anyway, so why not do it now? - self.len = 0; - - unsafe { - Drain { - iter: RawValIter::new(&self), - vec: PhantomData, - } - } - } -} -``` - - - - -# Handling Zero-Sized Types - -It's time. We're going to fight the spectre that is zero-sized types. Safe Rust -*never* needs to care about this, but Vec is very intensive on raw pointers and -raw allocations, which are exactly the *only* two things that care about -zero-sized types. We need to be careful of two things: - -* The raw allocator API has undefined behaviour if you pass in 0 for an - allocation size. -* raw pointer offsets are no-ops for zero-sized types, which will break our - C-style pointer iterator. - -Thankfully we abstracted out pointer-iterators and allocating handling into -RawValIter and RawVec respectively. How mysteriously convenient. - - - - -## Allocating Zero-Sized Types - -So if the allocator API doesn't support zero-sized allocations, what on earth -do we store as our allocation? Why, `heap::EMPTY` of course! Almost every operation -with a ZST is a no-op since ZSTs have exactly one value, and therefore no state needs -to be considered to store or load them. This actually extends to `ptr::read` and -`ptr::write`: they won't actually look at the pointer at all. As such we *never* need -to change the pointer. - -Note however that our previous reliance on running out of memory before overflow is -no longer valid with zero-sized types. We must explicitly guard against capacity -overflow for zero-sized types. - -Due to our current architecture, all this means is writing 3 guards, one in each -method of RawVec. - -```rust -impl RawVec { - fn new() -> Self { - unsafe { - // !0 is usize::MAX. This branch should be stripped at compile time. - let cap = if mem::size_of::() == 0 { !0 } else { 0 }; - - // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" - RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } - } - } - - fn grow(&mut self) { - unsafe { - let elem_size = mem::size_of::(); - - // since we set the capacity to usize::MAX when elem_size is - // 0, getting to here necessarily means the Vec is overfull. - assert!(elem_size != 0, "capacity overflow"); - - let align = mem::min_align_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - let new_cap = 2 * self.cap; - let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } - } -} - -impl Drop for RawVec { - fn drop(&mut self) { - let elem_size = mem::size_of::(); - - // don't free zero-sized allocations, as they were never allocated. - if self.cap != 0 && elem_size != 0 { - let align = mem::min_align_of::(); - - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr as *mut _, num_bytes, align); - } - } - } -} -``` - -That's it. We support pushing and popping zero-sized types now. Our iterators -(that aren't provided by slice Deref) are still busted, though. - - - - -## Iterating Zero-Sized Types - -Zero-sized offsets are no-ops. This means that our current design will always -initialize `start` and `end` as the same value, and our iterators will yield -nothing. The current solution to this is to cast the pointers to integers, -increment, and then cast them back: - -``` -impl RawValIter { - unsafe fn new(slice: &[T]) -> Self { - RawValIter { - start: slice.as_ptr(), - end: if mem::size_of::() == 0 { - ((slice.as_ptr() as usize) + slice.len()) as *const _ - } else if slice.len() == 0 { - slice.as_ptr() - } else { - slice.as_ptr().offset(slice.len() as isize) - } - } - } -} -``` - -Now we have a different bug. Instead of our iterators not running at all, our -iterators now run *forever*. We need to do the same trick in our iterator impls. -Also, our size_hint computation code will divide by 0 for ZSTs. Since we'll -basically be treating the two pointers as if they point to bytes, we'll just -map size 0 to divide by 1. - -``` -impl Iterator for RawValIter { - type Item = T; - fn next(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - let result = ptr::read(self.start); - self.start = if mem::size_of::() == 0 { - (self.start as usize + 1) as *const _ - } else { - self.start.offset(1); - } - Some(result) - } - } - } - - fn size_hint(&self) -> (usize, Option) { - let elem_size = mem::size_of::(); - let len = (self.end as usize - self.start as usize) - / if elem_size == 0 { 1 } else { elem_size }; - (len, Some(len)) - } -} - -impl DoubleEndedIterator for RawValIter { - fn next_back(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - self.end = if mem::size_of::() == 0 { - (self.end as usize - 1) as *const _ - } else { - self.end.offset(-1); - } - Some(ptr::read(self.end)) - } - } - } -} -``` - -And that's it. Iteration works! - - - -# Advanced Drain - -TODO? Not clear if informative - - - - - -# The Final Code - -```rust -#![feature(unique)] -#![feature(heap_api)] - -use std::ptr::{Unique, self}; -use std::rt::heap; -use std::mem; -use std::ops::{Deref, DerefMut}; -use std::marker::PhantomData; - - - - - -struct RawVec { - ptr: Unique, - cap: usize, -} - -impl RawVec { - fn new() -> Self { - unsafe { - // !0 is usize::MAX. This branch should be stripped at compile time. - let cap = if mem::size_of::() == 0 { !0 } else { 0 }; - - // heap::EMPTY doubles as "unallocated" and "zero-sized allocation" - RawVec { ptr: Unique::new(heap::EMPTY as *mut T), cap: cap } - } - } - - fn grow(&mut self) { - unsafe { - let elem_size = mem::size_of::(); - - // since we set the capacity to usize::MAX when elem_size is - // 0, getting to here necessarily means the Vec is overfull. - assert!(elem_size != 0, "capacity overflow"); - - let align = mem::min_align_of::(); - - let (new_cap, ptr) = if self.cap == 0 { - let ptr = heap::allocate(elem_size, align); - (1, ptr) - } else { - let new_cap = 2 * self.cap; - let ptr = heap::reallocate(*self.ptr as *mut _, - self.cap * elem_size, - new_cap * elem_size, - align); - (new_cap, ptr) - }; - - // If allocate or reallocate fail, we'll get `null` back - if ptr.is_null() { oom() } - - self.ptr = Unique::new(ptr as *mut _); - self.cap = new_cap; - } - } -} - -impl Drop for RawVec { - fn drop(&mut self) { - let elem_size = mem::size_of::(); - if self.cap != 0 && elem_size != 0 { - let align = mem::min_align_of::(); - - let num_bytes = elem_size * self.cap; - unsafe { - heap::deallocate(*self.ptr as *mut _, num_bytes, align); - } - } - } -} - - - - - -pub struct Vec { - buf: RawVec, - len: usize, -} - -impl Vec { - fn ptr(&self) -> *mut T { *self.buf.ptr } - - fn cap(&self) -> usize { self.buf.cap } - - pub fn new() -> Self { - Vec { buf: RawVec::new(), len: 0 } - } - pub fn push(&mut self, elem: T) { - if self.len == self.cap() { self.buf.grow(); } - - unsafe { - ptr::write(self.ptr().offset(self.len as isize), elem); - } - - // Can't fail, we'll OOM first. - self.len += 1; - } - - pub fn pop(&mut self) -> Option { - if self.len == 0 { - None - } else { - self.len -= 1; - unsafe { - Some(ptr::read(self.ptr().offset(self.len as isize))) - } - } - } - - pub fn insert(&mut self, index: usize, elem: T) { - assert!(index <= self.len, "index out of bounds"); - if self.cap() == self.len { self.buf.grow(); } - - unsafe { - if index < self.len { - ptr::copy(self.ptr().offset(index as isize), - self.ptr().offset(index as isize + 1), - self.len - index); - } - ptr::write(self.ptr().offset(index as isize), elem); - self.len += 1; - } - } - - pub fn remove(&mut self, index: usize) -> T { - assert!(index < self.len, "index out of bounds"); - unsafe { - self.len -= 1; - let result = ptr::read(self.ptr().offset(index as isize)); - ptr::copy(self.ptr().offset(index as isize + 1), - self.ptr().offset(index as isize), - self.len - index); - result - } - } - - pub fn into_iter(self) -> IntoIter { - unsafe { - let iter = RawValIter::new(&self); - let buf = ptr::read(&self.buf); - mem::forget(self); - - IntoIter { - iter: iter, - _buf: buf, - } - } - } - - pub fn drain(&mut self) -> Drain { - // this is a mem::forget safety thing. If this is forgotten, we just - // leak the whole Vec's contents. Also we need to do this *eventually* - // anyway, so why not do it now? - self.len = 0; - unsafe { - Drain { - iter: RawValIter::new(&self), - vec: PhantomData, - } - } - } -} - -impl Drop for Vec { - fn drop(&mut self) { - while let Some(_) = self.pop() {} - // allocation is handled by RawVec - } -} - -impl Deref for Vec { - type Target = [T]; - fn deref(&self) -> &[T] { - unsafe { - ::std::slice::from_raw_parts(self.ptr(), self.len) - } - } -} - -impl DerefMut for Vec { - fn deref_mut(&mut self) -> &mut [T] { - unsafe { - ::std::slice::from_raw_parts_mut(self.ptr(), self.len) - } - } -} - - - - - -struct RawValIter { - start: *const T, - end: *const T, -} - -impl RawValIter { - unsafe fn new(slice: &[T]) -> Self { - RawValIter { - start: slice.as_ptr(), - end: if mem::size_of::() == 0 { - ((slice.as_ptr() as usize) + slice.len()) as *const _ - } else if slice.len() == 0 { - slice.as_ptr() - } else { - slice.as_ptr().offset(slice.len() as isize) - } - } - } -} - -impl Iterator for RawValIter { - type Item = T; - fn next(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - let result = ptr::read(self.start); - self.start = self.start.offset(1); - Some(result) - } - } - } - - fn size_hint(&self) -> (usize, Option) { - let elem_size = mem::size_of::(); - let len = (self.end as usize - self.start as usize) - / if elem_size == 0 { 1 } else { elem_size }; - (len, Some(len)) - } -} - -impl DoubleEndedIterator for RawValIter { - fn next_back(&mut self) -> Option { - if self.start == self.end { - None - } else { - unsafe { - self.end = self.end.offset(-1); - Some(ptr::read(self.end)) - } - } - } -} - - - - -pub struct IntoIter { - _buf: RawVec, // we don't actually care about this. Just need it to live. - iter: RawValIter, -} - -impl Iterator for IntoIter { - type Item = T; - fn next(&mut self) -> Option { self.iter.next() } - fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } -} - -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option { self.iter.next_back() } -} - -impl Drop for IntoIter { - fn drop(&mut self) { - for _ in &mut *self {} - } -} - - - - -pub struct Drain<'a, T: 'a> { - vec: PhantomData<&'a mut Vec>, - iter: RawValIter, -} - -impl<'a, T> Iterator for Drain<'a, T> { - type Item = T; - fn next(&mut self) -> Option { self.iter.next_back() } - fn size_hint(&self) -> (usize, Option) { self.iter.size_hint() } -} - -impl<'a, T> DoubleEndedIterator for Drain<'a, T> { - fn next_back(&mut self) -> Option { self.iter.next_back() } -} - -impl<'a, T> Drop for Drain<'a, T> { - fn drop(&mut self) { - // pre-drain the iter - for _ in &mut self.iter {} - } -} - -/// Abort the process, we're out of memory! -/// -/// In practice this is probably dead code on most OSes -fn oom() { - ::std::process::exit(-1); -} -``` diff --git a/working-with-unsafe.md b/working-with-unsafe.md new file mode 100644 index 0000000000000..6725132466191 --- /dev/null +++ b/working-with-unsafe.md @@ -0,0 +1,88 @@ +% Working with Unsafe + +Rust generally only gives us the tools to talk about safety in a scoped and +binary manner. Unfortunately reality is significantly more complicated than that. +For instance, consider the following toy function: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx < arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +Clearly, this function is safe. We check that the index is in bounds, and if it +is, index into the array in an unchecked manner. But even in such a trivial +function, the scope of the unsafe block is questionable. Consider changing the +`<` to a `<=`: + +```rust +fn do_idx(idx: usize, arr: &[u8]) -> Option { + if idx <= arr.len() { + unsafe { + Some(*arr.get_unchecked(idx)) + } + } else { + None + } +} +``` + +This program is now unsound, an yet *we only modified safe code*. This is the +fundamental problem of safety: it's non-local. The soundness of our unsafe +operations necessarily depends on the state established by "safe" operations. +Although safety *is* modular (we *still* don't need to worry about about +unrelated safety issues like uninitialized memory), it quickly contaminates the +surrounding code. + +Trickier than that is when we get into actual statefulness. Consider a simple +implementation of `Vec`: + +```rust +// Note this defintion is insufficient. See the section on lifetimes. +struct Vec { + ptr: *mut T, + len: usize, + cap: usize, +} + +// Note this implementation does not correctly handle zero-sized types. +// We currently live in a nice imaginary world of only positive fixed-size +// types. +impl Vec { + fn push(&mut self, elem: T) { + if self.len == self.cap { + // not important for this example + self.reallocate(); + } + unsafe { + ptr::write(self.ptr.offset(len as isize), elem); + self.len += 1; + } + } +} +``` + +This code is simple enough to reasonably audit and verify. Now consider +adding the following method: + +```rust + fn make_room(&mut self) { + // grow the capacity + self.cap += 1; + } +``` + +This code is safe, but it is also completely unsound. Changing the capacity +violates the invariants of Vec (that `cap` reflects the allocated space in the +Vec). This is not something the rest of `Vec` can guard against. It *has* to +trust the capacity field because there's no way to verify it. + +`unsafe` does more than pollute a whole function: it pollutes a whole *module*. +Generally, the only bullet-proof way to limit the scope of unsafe code is at the +module boundary with privacy. From 59ff3a39ae866b862678a769f469f0bae55606e5 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 6 Jul 2015 20:25:14 -0700 Subject: [PATCH 046/104] expand on ctors --- constructors.md | 77 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 53 insertions(+), 24 deletions(-) diff --git a/constructors.md b/constructors.md index 8069776c0aafc..99bcf5e283ee3 100644 --- a/constructors.md +++ b/constructors.md @@ -1,26 +1,55 @@ % Constructors -Unlike C++, Rust does not come with a slew of 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 a 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 "copy the bits". Copy types *are* implicitly -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 implicitly initialized][uninit]. Default is basically only useful for generic -programming. In concrete contexts, 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. \ No newline at end of file +There is exactly one way to create an instance of a user-defined type: name it, +and initialize all its fields at once: + +```rust +struct Foo { + a: u8, + b: u32, + c: bool, +} + +enum Bar { + X(u32), + Y(bool), +} + +struct Empty; + +let foo = Foo { a: 0, b: 1, c: false }; +let bar = Bar::X(0); +let empty = Empty; +``` + +That's it. Every other way you make an instance of a type is just calling a +totally vanilla function that does some stuff and eventually bottoms out to The +One True Constructor. + +Unlike C++, Rust does not come with a slew of built in kinds of constructor. +There are no Copy, Default, Assignment, Move, or whatever constructors. The +reasons for this are varied, but it largely boils down to 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 *only* semantics in Rust. At most `x = y` just moves the bits of y into the x +variable. Rust *does* provide two facilities for providing C++'s copy-oriented +semantics: `Copy` and `Clone`. Clone is our moral equivalent of a 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 "copy the bits". Copy types *are* implicitly +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 implicitly initialized][uninit]. Default is basically +only useful for generic programming. In concrete contexts, 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. From adcd30c5a2aa732174b0c5deba3f4b9c9a9a44d0 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 6 Jul 2015 20:28:11 -0700 Subject: [PATCH 047/104] mdinger fix --- safe-unsafe-meaning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/safe-unsafe-meaning.md b/safe-unsafe-meaning.md index 8a6300a061d24..6c3d4087b8198 100644 --- a/safe-unsafe-meaning.md +++ b/safe-unsafe-meaning.md @@ -98,7 +98,7 @@ destructors will be successfully called! Hooray! However BTreeMap is implemented using a modest spoonful of Unsafe (most collections are). That means that it is not necessarily *trivially true* that a bad Ord -implementation will make BTreeMap behave safely. Unsafe most be sure not to rely +implementation will make BTreeMap behave safely. Unsafe must be sure not to rely on Ord *where safety is at stake*, because Ord is provided by Safe, and memory safety is not Safe's responsibility to uphold. *It must be impossible for Safe code to violate memory safety*. From 5ec12b154bcc839f9a903f238791b6010a61418b Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 6 Jul 2015 23:36:10 -0700 Subject: [PATCH 048/104] cleanup --- subtyping.md | 84 ++++++++++++++++++++++++++++------------------------ unwinding.md | 19 ++++++------ 2 files changed, 56 insertions(+), 47 deletions(-) diff --git a/subtyping.md b/subtyping.md index 733e015dbd7d0..31aba0adbf98c 100644 --- a/subtyping.md +++ b/subtyping.md @@ -2,22 +2,23 @@ Although Rust doesn't have any notion of inheritance, it *does* include subtyping. In Rust, subtyping derives entirely from *lifetimes*. Since lifetimes are scopes, -we can partially order them based on a *contains* (outlives) relationship. We -can even express this as a generic bound: `T: 'a` specifies that whatever scope `T` -is valid for must contain the scope `'a` ("T outlives `'a`"). +we can partially order them based on the *contains* (outlives) relationship. We +can even express this as a generic bound. -We can then define subtyping on lifetimes in terms of that relationship: if `'a: 'b` +Subtyping on lifetimes in terms of that relationship: if `'a: 'b` ("a contains b" or "a outlives b"), then `'a` is a subtype of `'b`. This is a large source of confusion, because it seems intuitively backwards to many: the bigger scope is a *sub type* of the smaller scope. -This does in fact make sense. The intuitive reason for this is that if you expect an -`&'a u8`, then it's totally fine for me to hand you an `&'static u8`, in the same way -that if you expect an Animal in Java, it's totally fine for me to hand you a Cat. -Cats are just Animals *and more*, just as `'static` is just `'a` *and more*. +This does in fact make sense, though. The intuitive reason for this is that if +you expect an `&'a u8`, then it's totally fine for me to hand you an `&'static u8`, +in the same way that if you expect an Animal in Java, it's totally fine for me to +hand you a Cat. Cats are just Animals *and more*, just as `'static` is just `'a` +*and more*. (Note, the subtyping relationship and typed-ness of lifetimes is a fairly arbitrary -construct that some disagree with. I just find that it simplifies this analysis.) +construct that some disagree with. However it simplifies our analysis to treat +lifetimes and types uniformly.) Higher-ranked lifetimes are also subtypes of every concrete lifetime. This is because taking an arbitrary lifetime is strictly more general than taking a specific one. @@ -26,15 +27,15 @@ taking an arbitrary lifetime is strictly more general than taking a specific one # Variance -Variance is where things get really harsh. +Variance is where things get a bit complicated. Variance is a property that *type constructors* have. A type constructor in Rust is a generic type with unbound arguments. For instance `Vec` is a type constructor that takes a `T` and returns a `Vec`. `&` and `&mut` are type constructors that -take a lifetime and a type. +take a two types: a lifetime, and a type to point to. -A type constructor's *variance* is how the subtypes of its inputs affects the -subtypes of its outputs. There are three kinds of variance: +A type constructor's *variance* is how the subtyping of its inputs affects the +subtyping of its outputs. There are two kinds of variance in Rust: * F is *variant* if `T` being a subtype of `U` implies `F` is a subtype of `F` * F is *invariant* otherwise (no subtyping relation can be derived) @@ -60,42 +61,47 @@ needed. To see why `&mut` should be invariant, consider the following code: -```rust +```rust,ignore +fn overwrite(input: &mut T, new: &mut T) { + *input = *new; +} + fn main() { let mut forever_str: &'static str = "hello"; { let string = String::from("world"); overwrite(&mut forever_str, &mut &*string); } + // Oops, printing free'd memory println!("{}", forever_str); } - -fn overwrite(input: &mut T, new: &mut T) { - *input = *new; -} ``` -The signature of `overwrite` is clearly valid: it takes mutable references to two values -of the same type, and overwrites one with the other. We have seen already that `&` is -variant, and `'static` is a subtype of *any* `'a`, so `&'static str` is a -subtype of `&'a str`. Therefore, if `&mut` was -*also* variant, then the lifetime of the `&'static str` would successfully be -"shrunk" down to the shorter lifetime of the string, and `overwrite` would be -called successfully. The string would subsequently be dropped, and `forever_str` -would point to freed memory when we print it! +The signature of `overwrite` is clearly valid: it takes mutable references to +two values of the same type, and overwrites one with the other. If `&mut` was +variant, then `&mut &'a str` would be a subtype of `&mut &'static str`, since +`&'a str` is a subtype of `&'static str`. Therefore the lifetime of +`forever_str` would successfully be "shrunk" down to the shorter lifetime of +`string`, and `overwrite` would be called successfully. `string` would +subsequently be dropped, and `forever_str` would point to freed memory when we +print it! Therefore `&mut` should be invariant. -Therefore `&mut` should be invariant. This is the general theme of variance vs +This is the general theme of variance vs invariance: if variance would allow you to *store* a short-lived value in a longer-lived slot, then you must be invariant. `Box` and `Vec` are interesting cases because they're variant, but you can -definitely store values in them! This is fine because *you can only store values -in them through a mutable reference*! The mutable reference makes the whole type -invariant, and therefore prevents you from getting in trouble. +definitely store values in them! This is where Rust gets really clever: it's +fine for them to be variant because you can only store values +in them *via a mutable reference*! The mutable reference makes the whole type +invariant, and therefore prevents you from smuggling a short-lived type into +them. + +Being variant *does* allows them to be weakened when shared immutably. +So you can pass a `&Box<&'static str>` where a `&Box<&'a str>` is expected. -Being variant allows them to be variant when shared immutably (so you can pass -a `&Box<&'static str>` where a `&Box<&'a str>` is expected). It also allows you to -forever weaken the type by moving it into a weaker slot. That is, you can do: +However what should happen when passing *by-value* is less obvious. It turns out +that, yes, you can use subtyping when passing by-value. That is, this works: ```rust fn get_box<'a>(&'a u8) -> Box<&'a str> { @@ -104,14 +110,16 @@ fn get_box<'a>(&'a u8) -> Box<&'a str> { } ``` -which is fine because unlike the mutable borrow case, there's no one else who -"remembers" the old lifetime in the box. +Weakening when you pass by-value is fine because there's no one else who +"remembers" the old lifetime in the Box. The reason a variant `&mut` was +trouble was because there's always someone else who remembers the original +subtype: the actual owner. -The variance of the cell types similarly follows. `&` is like an `&mut` for a +The invariance of the cell types can be seen as follows: `&` is like an `&mut` for a cell, because you can still store values in them through an `&`. Therefore cells must be invariant to avoid lifetime smuggling. -`Fn` is the most subtle case, because it has mixed variance. To see why +`Fn` is the most subtle case because it has mixed variance. To see why `Fn(T) -> U` should be invariant over T, consider the following function signature: @@ -120,7 +128,7 @@ signature: fn foo(&'a str) -> usize; ``` -This signature claims that it can handle any &str that lives *at least* as long +This signature claims that it can handle any `&str` that lives *at least* as long as `'a`. Now if this signature was variant with respect to `&str`, that would mean ```rust diff --git a/unwinding.md b/unwinding.md index 925f304236623..0526896550287 100644 --- a/unwinding.md +++ b/unwinding.md @@ -263,17 +263,18 @@ impl BinaryHeap { Although all unsafe code *must* ensure some minimal level of exception safety, some types may choose to explicitly *poison* themselves if they witness a panic. -The most notable example of this is the standard library's Mutex type. A Mutex -will poison itself if one of its MutexGuards (the thing it returns when a lock -is obtained) is dropped during a panic. Any future attempts to lock the Mutex -will return an `Err`. +Poisoning doesn't entail anything in particular. Generally it just means +preventing normal usage from proceeding. The most notable example of this is the +standard library's Mutex type. A Mutex will poison itself if one of its +MutexGuards (the thing it returns when a lock is obtained) is dropped during a +panic. Any future attempts to lock the Mutex will return an `Err`. Mutex poisons not for *true* safety in the sense that Rust normally cares about. It poisons as a safety-guard against blindly using the data that comes out of a Mutex that has witnessed a panic while locked. The data in such a Mutex was likely in the middle of being modified, and as such may be in an inconsistent or incomplete state. It is important to note that one cannot violate memory safety with such a type -if it is correctly written. After all, it must be exception safe! +if it is correctly written. After all, it must be minimally exception safe! However if the Mutex contained, say, a BinaryHeap that does not actually have the heap property, it's unlikely that any code that uses it will do @@ -288,7 +289,7 @@ the Err exposes a method to get the lock anyway. It *is* safe, after all. Rust's unwinding strategy is not specified to be fundamentally compatible with any other language's unwinding. As such, unwinding into Rust from another language, or unwinding into another language from Rust is Undefined Behaviour. -What you do at that point is up to you, but you must *absolutely* catch any -panics at the FFI boundary! At best, your application will crash and burn. At -worst, your application *won't* crash and burn, and will proceed with completely -clobbered state. +You must *absolutely* catch any panics at the FFI boundary! What you do at that +point is up to you, but *something* must be done. If you fail to do this, +at best, your application will crash and burn. At worst, your application *won't* +crash and burn, and will proceed with completely clobbered state. From 35b8001f684399992978c60fcb3d51232b3ca85d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 6 Jul 2015 23:37:44 -0700 Subject: [PATCH 049/104] cleanup --- subtyping.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/subtyping.md b/subtyping.md index 31aba0adbf98c..24f974ca73ac8 100644 --- a/subtyping.md +++ b/subtyping.md @@ -48,11 +48,11 @@ interactions with other features.) Some important variances: * `&` is variant (as is `*const` by metaphor) -* `&mut` is invariant (as is `*mut` by metaphor) +* `&mut` is invariant * `Fn(T) -> U` is invariant with respect to `T`, but variant with respect to `U` * `Box`, `Vec`, and all other collections are variant * `UnsafeCell`, `Cell`, `RefCell`, `Mutex` and all "interior mutability" - types are invariant + types are invariant (as is `*mut` by metaphor) To understand why these variances are correct and desirable, we will consider several examples. We have already covered why `&` should be variant when introducing subtyping: @@ -158,7 +158,7 @@ in its place. Therefore functions *are* variant over their return type. `*const` has the exact same semantics as `&`, so variance follows. `*mut` on the other hand can dereference to an &mut whether shared or not, so it is marked -as invariant in analogy to cells. +as invariant just like cells. This is all well and good for the types the standard library provides, but how is variance determined for type that *you* define? A struct, informally From 987a8687db1a2a5a9388265a6bb5a1590a05dd69 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 09:33:20 -0700 Subject: [PATCH 050/104] split out and rework drop flags section --- SUMMARY.md | 1 + checked-uninit.md | 24 --------------- drop-flags.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 24 deletions(-) create mode 100644 drop-flags.md diff --git a/SUMMARY.md b/SUMMARY.md index 225708e21869f..3b5a04c5a3eb7 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -23,6 +23,7 @@ * [Transmutes](transmutes.md) * [Uninitialized Memory](uninitialized.md) * [Checked](checked-uninit.md) + * [Drop Flags](drop-flags.md) * [Unchecked](unchecked-uninit.md) * [Ownership-Oriented Resource Management](raii.md) * [Constructors](constructors.md) diff --git a/checked-uninit.md b/checked-uninit.md index e39a329bfd29b..8896fc9de0199 100644 --- a/checked-uninit.md +++ b/checked-uninit.md @@ -83,27 +83,3 @@ fn main() { 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 -a value, 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 hidden -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 danger. diff --git a/drop-flags.md b/drop-flags.md new file mode 100644 index 0000000000000..2d5bae6dcfe9c --- /dev/null +++ b/drop-flags.md @@ -0,0 +1,78 @@ +% Drop Flags + +The examples in the previous section introduce an interesting problem for Rust. +We have seen that's possible to conditionally initialize, deinitialize, and +*reinitialize* locations of memory totally safely. For Copy types, this isn't +particularly notable since they're just a random pile of bits. However types with +destructors are a different story: Rust needs to know whether to call a destructor +whenever a variable is assigned to, or a variable goes out of scope. How can it +do this with conditional initialization? + +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 toggled. When a variable *might* need to be dropped, this flag +is evaluated to determine if it *should* be dropped. + +Of course, it is *often* the case that a value's initialization state can be +*statically* known at every point in the program. If this is the case, then the +compiler can theoretically generate more effecient code! For instance, +straight-line code has such *static drop semantics*: + +```rust +let mut x = Box::new(0); // x was uninit +let mut y = x; // y was uninit +x = Box::new(0); // x was uninit +y = x; // y was init; Drop y! + // y was init; Drop y! + // x was uninit +``` + +And even branched code where all branches have the same behaviour with respect +to initialization: + +```rust +let mut x = Box::new(0); // x was uninit +if condition { + drop(x) // x gets moved out +} else { + println!("{}", x); + drop(x) // x gets moved out +} +x = Box::new(0); // x was uninit + // x was init; Drop x! +``` + +However code like this *requires* runtime information to correctly Drop: + +```rust +let x; +if condition { + x = Box::new(0); // x was uninit + println!("{}", x); +} + // x might be uninit; check the flag! +``` + +Of course, in this case it's trivial to retrieve static drop semantics: + +```rust +if condition { + let x = Box::new(0); + println!("{}", x); +} +``` + +As of Rust 1.0, the drop flags are actually not-so-secretly stashed in a hidden +field of any type that implements Drop. Rust sets the drop flag by +overwriting the *entire* value with a particular byte. This is pretty obviously +Not The Fastest and causes a bunch of trouble with optimizing code. It's legacy +from a time when you could do much more complex conditional initialization. + +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. + +Regardless, 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 +you can work with them in Safe Rust, but you're *never* in danger. \ No newline at end of file From 50d8656945513c6b327122e5a40650c66baa87cb Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 09:39:21 -0700 Subject: [PATCH 051/104] void types --- exotic-sizes.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/exotic-sizes.md b/exotic-sizes.md index 8e05485055f77..ea8dc86d1f0ac 100644 --- a/exotic-sizes.md +++ b/exotic-sizes.md @@ -3,6 +3,10 @@ Most of the time, we think in terms of types with a fixed, positive size. This is not always the case, however. + + + + # Dynamically Sized Types (DSTs) Rust also supports types without a statically known size. On the surface, @@ -34,19 +38,20 @@ a variable position based on its alignment.** + + # Zero Sized Types (ZSTs) Rust actually allows types to be specified that occupy *no* space: ```rust struct Foo; // No fields = no size -enum Bar; // No variants = no size // All fields have no size = no size struct Baz { foo: Foo, - bar: Bar, - qux: (), // empty tuple has no size + qux: (), // empty tuple has no size + baz: [u8; 0], // empty array has no size } ``` @@ -67,3 +72,16 @@ standard allocators (including jemalloc, the one used by Rust) generally conside passing in `0` as Undefined Behaviour. + + + +# Void Types + +Rust also enables types to be declared that *cannot even be instantiated*. These +types can only be talked about at the type level, and never at the value level. + +```rust +enum Foo { } // No variants = VOID +``` + +TODO: WHY?! \ No newline at end of file From 2e653f3cce3e5a75861c7c6b9b08729f16b967bf Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 09:48:57 -0700 Subject: [PATCH 052/104] shard out concurrency --- SUMMARY.md | 3 + atomics.md | 47 +++++++++++ concurrency.md | 214 ++--------------------------------------------- races.md | 66 +++++++++++++++ send-and-sync.md | 76 +++++++++++++++++ 5 files changed, 197 insertions(+), 209 deletions(-) create mode 100644 atomics.md create mode 100644 races.md create mode 100644 send-and-sync.md diff --git a/SUMMARY.md b/SUMMARY.md index 3b5a04c5a3eb7..1456e3602e0b9 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -31,6 +31,9 @@ * [Leaking](leaking.md) * [Unwinding](unwinding.md) * [Concurrency](concurrency.md) + * [Races](races.md) + * [Send and Sync](send-and-sync.md) + * [Atomics](atomics.md) * [Example: Implementing Vec](vec.md) * [Layout](vec-layout.md) * [Allocating](vec-alloc.md) diff --git a/atomics.md b/atomics.md new file mode 100644 index 0000000000000..e13fb01c06b60 --- /dev/null +++ b/atomics.md @@ -0,0 +1,47 @@ +% Atomics + +Rust pretty blatantly just inherits C11's memory model for atomics. This is not +due this model being particularly excellent or easy to understand. Indeed, this +model is quite complex and known to have [several flaws][C11-busted]. Rather, +it is a pragmatic concession to the fact that *everyone* is pretty bad at modeling +atomics. At very least, we can benefit from existing tooling and research around +C. + +Trying to fully explain the model is fairly hopeless. If you want all the +nitty-gritty details, you should check out [C's specification][C11-model]. +Still, we'll try to cover the basics and some of the problems Rust developers +face. + +The C11 memory model is fundamentally about trying to bridge the gap between C's +single-threaded semantics, common compiler optimizations, and hardware peculiarities +in the face of a multi-threaded environment. It does this by splitting memory +accesses into two worlds: data accesses, and atomic accesses. + +Data accesses are the bread-and-butter of the programming world. They are +fundamentally unsynchronized and compilers are free to aggressively optimize +them. In particular data accesses are free to be reordered by the compiler +on the assumption that the program is single-threaded. The hardware is also free +to propagate the changes made in data accesses as lazily and inconsistently as +it wants to other threads. Mostly critically, data accesses are where we get data +races. These are pretty clearly awful semantics to try to write a multi-threaded +program with. + +Atomic accesses are the answer to this. Each atomic access can be marked with +an *ordering*. The set of orderings Rust exposes are: + +* Sequentially Consistent (SeqCst) +* Release +* Acquire +* Relaxed + +(Note: We explicitly do not expose the C11 *consume* ordering) + +TODO: give simple "basic" explanation of these +TODO: implementing Arc example (why does Drop need the trailing barrier?) + + + + + +[C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf +[C11-model]: http://en.cppreference.com/w/c/atomic/memory_order diff --git a/concurrency.md b/concurrency.md index 71cfec3393e53..e5276323267c4 100644 --- a/concurrency.md +++ b/concurrency.md @@ -1,217 +1,13 @@ % Concurrency and Paralellism - - -# Data Races and Race Conditions - -Safe Rust guarantees an absence of data races, which are defined as: - -* two or more threads concurrently accessing a location of memory -* one of them is a write -* one of them is unsynchronized - -A data race has Undefined Behaviour, and is therefore impossible to perform -in Safe Rust. Data races are *mostly* prevented through rust's ownership system: -it's impossible to alias a mutable reference, so it's impossible to perform a -data race. Interior mutability makes this more complicated, which is largely why -we have the Send and Sync traits (see below). - -However Rust *does not* prevent general race conditions. This is -pretty fundamentally impossible, and probably honestly undesirable. Your hardware -is racy, your OS is racy, the other programs on your computer are racy, and the -world this all runs in is racy. Any system that could genuinely claim to prevent -*all* race conditions would be pretty awful to use, if not just incorrect. - -So it's perfectly "fine" for a Safe Rust program to get deadlocked or do -something incredibly stupid with incorrect synchronization. Obviously such a -program isn't very good, but Rust can only hold your hand so far. Still, a -race condition can't violate memory safety in a Rust program on -its own. Only in conjunction with some other unsafe code can a race condition -actually violate memory safety. For instance: - -```rust -use std::thread; -use std::sync::atomic::{AtomicUsize, Ordering}; -use std::sync::Arc; - -let data = vec![1, 2, 3, 4]; -// Arc so that the memory the AtomicUsize is stored in still exists for -// the other thread to increment, even if we completely finish executing -// before it. Rust won't compile the program without it, because of the -// lifetime requirements of thread::spawn! -let idx = Arc::new(AtomicUsize::new(0)); -let other_idx = idx.clone(); - -// `move` captures other_idx by-value, moving it into this thread -thread::spawn(move || { - // It's ok to mutate idx because this value - // is an atomic, so it can't cause a Data Race. - other_idx.fetch_add(10, Ordering::SeqCst); -}); - -// Index with the value loaded from the atomic. This is safe because we -// read the atomic memory only once, and then pass a *copy* of that value -// to the Vec's indexing implementation. This indexing will be correctly -// bounds checked, and there's no chance of the value getting changed -// in the middle. However our program may panic if the thread we spawned -// managed to increment before this ran. A race condition because correct -// program execution (panicing is rarely correct) depends on order of -// thread execution. -println!("{}", data[idx.load(Ordering::SeqCst)]); - -if idx.load(Ordering::SeqCst) < data.len() { - unsafe { - // Incorrectly loading the idx *after* we did the bounds check. - // It could have changed. This is a race condition, *and dangerous* - // because we decided to do `get_unchecked`, which is `unsafe`. - println!("{}", data.get_unchecked(idx.load(Ordering::SeqCst))); - } -} -``` - - - - -# Send and Sync - -Not everything obeys inherited mutability, though. Some types allow you to multiply -alias a location in memory while mutating it. Unless these types use synchronization -to manage this access, they are absolutely not thread safe. Rust captures this with -through the `Send` and `Sync` traits. - -* A type is Send if it is safe to send it to another thread. -* A type is Sync if it is safe to share between threads (`&T` is Send). - -Send and Sync are *very* fundamental to Rust's concurrency story. As such, a -substantial amount of special tooling exists to make them work right. First and -foremost, they're *unsafe traits*. This means that they are unsafe *to implement*, -and other unsafe code can *trust* that they are correctly implemented. Since -they're *marker traits* (they have no associated items like methods), correctly -implemented simply means that they have the intrinsic properties an implementor -should have. Incorrectly implementing Send or Sync can cause Undefined Behaviour. - -Send and Sync are also what Rust calls *opt-in builtin traits*. -This means that, unlike every other trait, they are *automatically* derived: -if a type is composed entirely of Send or Sync types, then it is Send or Sync. -Almost all primitives are Send and Sync, and as a consequence pretty much -all types you'll ever interact with are Send and Sync. - -Major exceptions include: - -* raw pointers are neither Send nor Sync (because they have no safety guards) -* `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) -* `Rc` isn't Send or Sync (because the refcount is shared and unsynchronized) - -`Rc` and `UnsafeCell` are very fundamentally not thread-safe: they enable -unsynchronized shared mutable state. However raw pointers are, strictly speaking, -marked as thread-unsafe as more of a *lint*. Doing anything useful -with a raw pointer requires dereferencing it, which is already unsafe. In that -sense, one could argue that it would be "fine" for them to be marked as thread safe. - -However it's important that they aren't thread safe to prevent types that -*contain them* from being automatically marked as thread safe. These types have -non-trivial untracked ownership, and it's unlikely that their author was -necessarily thinking hard about thread safety. In the case of Rc, we have a nice -example of a type that contains a `*mut` that is *definitely* not thread safe. - -Types that aren't automatically derived can *opt-in* to Send and Sync by simply -implementing them: - -```rust -struct MyBox(*mut u8); - -unsafe impl Send for MyBox {} -unsafe impl Sync for MyBox {} -``` - -In the *incredibly rare* case that a type is *inappropriately* automatically -derived to be Send or Sync, then one can also *unimplement* Send and Sync: - -```rust -struct SpecialThreadToken(u8); - -impl !Send for SpecialThreadToken {} -impl !Sync for SpecialThreadToken {} -``` - -Note that *in and of itself* it is impossible to incorrectly derive Send and Sync. -Only types that are ascribed special meaning by other unsafe code can possible cause -trouble by being incorrectly Send or Sync. - -Most uses of raw pointers should be encapsulated behind a sufficient abstraction -that Send and Sync can be derived. For instance all of Rust's standard -collections are Send and Sync (when they contain Send and Sync types) -in spite of their pervasive use raw pointers to -manage allocations and complex ownership. Similarly, most iterators into these -collections are Send and Sync because they largely behave like an `&` or `&mut` -into the collection. - -TODO: better explain what can or can't be Send or Sync. Sufficient to appeal -only to data races? - - - - -# Atomics - -Rust pretty blatantly just inherits C11's memory model for atomics. This is not -due this model being particularly excellent or easy to understand. Indeed, this -model is quite complex and known to have [several flaws][C11-busted]. Rather, -it is a pragmatic concession to the fact that *everyone* is pretty bad at modeling -atomics. At very least, we can benefit from existing tooling and research around -C. - -Trying to fully explain the model is fairly hopeless. If you want all the -nitty-gritty details, you should check out [C's specification][C11-model]. -Still, we'll try to cover the basics and some of the problems Rust developers -face. - -The C11 memory model is fundamentally about trying to bridge the gap between C's -single-threaded semantics, common compiler optimizations, and hardware peculiarities -in the face of a multi-threaded environment. It does this by splitting memory -accesses into two worlds: data accesses, and atomic accesses. - -Data accesses are the bread-and-butter of the programming world. They are -fundamentally unsynchronized and compilers are free to aggressively optimize -them. In particular data accesses are free to be reordered by the compiler -on the assumption that the program is single-threaded. The hardware is also free -to propagate the changes made in data accesses as lazily and inconsistently as -it wants to other threads. Mostly critically, data accesses are where we get data -races. These are pretty clearly awful semantics to try to write a multi-threaded -program with. - -Atomic accesses are the answer to this. Each atomic access can be marked with -an *ordering*. The set of orderings Rust exposes are: - -* Sequentially Consistent (SeqCst) -* Release -* Acquire -* Relaxed - -(Note: We explicitly do not expose the C11 *consume* ordering) - -TODO: give simple "basic" explanation of these -TODO: implementing Arc example (why does Drop need the trailing barrier?) - - - - -# Actually Doing Things Concurrently - Rust as a language doesn't *really* have an opinion on how to do concurrency or parallelism. The standard library exposes OS threads and blocking sys-calls -because *everyone* has those and they're uniform enough that you can provide +because *everyone* has those, and they're uniform enough that you can provide an abstraction over them in a relatively uncontroversial way. Message passing, green threads, and async APIs are all diverse enough that any abstraction over them tends to involve trade-offs that we weren't willing to commit to for 1.0. -However Rust's current design is setup so that you can set up your own -concurrent paradigm or library as you see fit. Just require the right -lifetimes and Send and Sync where appropriate and everything should Just Work -with everyone else's stuff. - - - - -[C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf -[C11-model]: http://en.cppreference.com/w/c/atomic/memory_order +However the way Rust models concurrency makes it relatively easy design your own +concurrency paradigm as a library and have *everyone else's* code Just Work +with yours. Just require the right lifetimes and Send and Sync where appropriate +and you're off to the races. Or rather, not having races. Races are bad. diff --git a/races.md b/races.md new file mode 100644 index 0000000000000..240e4aca7f6b6 --- /dev/null +++ b/races.md @@ -0,0 +1,66 @@ +% Data Races and Race Conditions + +Safe Rust guarantees an absence of data races, which are defined as: + +* two or more threads concurrently accessing a location of memory +* one of them is a write +* one of them is unsynchronized + +A data race has Undefined Behaviour, and is therefore impossible to perform +in Safe Rust. Data races are *mostly* prevented through rust's ownership system: +it's impossible to alias a mutable reference, so it's impossible to perform a +data race. Interior mutability makes this more complicated, which is largely why +we have the Send and Sync traits (see below). + +However Rust *does not* prevent general race conditions. This is +pretty fundamentally impossible, and probably honestly undesirable. Your hardware +is racy, your OS is racy, the other programs on your computer are racy, and the +world this all runs in is racy. Any system that could genuinely claim to prevent +*all* race conditions would be pretty awful to use, if not just incorrect. + +So it's perfectly "fine" for a Safe Rust program to get deadlocked or do +something incredibly stupid with incorrect synchronization. Obviously such a +program isn't very good, but Rust can only hold your hand so far. Still, a +race condition can't violate memory safety in a Rust program on +its own. Only in conjunction with some other unsafe code can a race condition +actually violate memory safety. For instance: + +```rust +use std::thread; +use std::sync::atomic::{AtomicUsize, Ordering}; +use std::sync::Arc; + +let data = vec![1, 2, 3, 4]; +// Arc so that the memory the AtomicUsize is stored in still exists for +// the other thread to increment, even if we completely finish executing +// before it. Rust won't compile the program without it, because of the +// lifetime requirements of thread::spawn! +let idx = Arc::new(AtomicUsize::new(0)); +let other_idx = idx.clone(); + +// `move` captures other_idx by-value, moving it into this thread +thread::spawn(move || { + // It's ok to mutate idx because this value + // is an atomic, so it can't cause a Data Race. + other_idx.fetch_add(10, Ordering::SeqCst); +}); + +// Index with the value loaded from the atomic. This is safe because we +// read the atomic memory only once, and then pass a *copy* of that value +// to the Vec's indexing implementation. This indexing will be correctly +// bounds checked, and there's no chance of the value getting changed +// in the middle. However our program may panic if the thread we spawned +// managed to increment before this ran. A race condition because correct +// program execution (panicing is rarely correct) depends on order of +// thread execution. +println!("{}", data[idx.load(Ordering::SeqCst)]); + +if idx.load(Ordering::SeqCst) < data.len() { + unsafe { + // Incorrectly loading the idx *after* we did the bounds check. + // It could have changed. This is a race condition, *and dangerous* + // because we decided to do `get_unchecked`, which is `unsafe`. + println!("{}", data.get_unchecked(idx.load(Ordering::SeqCst))); + } +} +``` diff --git a/send-and-sync.md b/send-and-sync.md new file mode 100644 index 0000000000000..0ac14a85f847f --- /dev/null +++ b/send-and-sync.md @@ -0,0 +1,76 @@ +% Send and Sync + +Not everything obeys inherited mutability, though. Some types allow you to multiply +alias a location in memory while mutating it. Unless these types use synchronization +to manage this access, they are absolutely not thread safe. Rust captures this with +through the `Send` and `Sync` traits. + +* A type is Send if it is safe to send it to another thread. +* A type is Sync if it is safe to share between threads (`&T` is Send). + +Send and Sync are *very* fundamental to Rust's concurrency story. As such, a +substantial amount of special tooling exists to make them work right. First and +foremost, they're *unsafe traits*. This means that they are unsafe *to implement*, +and other unsafe code can *trust* that they are correctly implemented. Since +they're *marker traits* (they have no associated items like methods), correctly +implemented simply means that they have the intrinsic properties an implementor +should have. Incorrectly implementing Send or Sync can cause Undefined Behaviour. + +Send and Sync are also what Rust calls *opt-in builtin traits*. +This means that, unlike every other trait, they are *automatically* derived: +if a type is composed entirely of Send or Sync types, then it is Send or Sync. +Almost all primitives are Send and Sync, and as a consequence pretty much +all types you'll ever interact with are Send and Sync. + +Major exceptions include: + +* raw pointers are neither Send nor Sync (because they have no safety guards) +* `UnsafeCell` isn't Sync (and therefore `Cell` and `RefCell` aren't) +* `Rc` isn't Send or Sync (because the refcount is shared and unsynchronized) + +`Rc` and `UnsafeCell` are very fundamentally not thread-safe: they enable +unsynchronized shared mutable state. However raw pointers are, strictly speaking, +marked as thread-unsafe as more of a *lint*. Doing anything useful +with a raw pointer requires dereferencing it, which is already unsafe. In that +sense, one could argue that it would be "fine" for them to be marked as thread safe. + +However it's important that they aren't thread safe to prevent types that +*contain them* from being automatically marked as thread safe. These types have +non-trivial untracked ownership, and it's unlikely that their author was +necessarily thinking hard about thread safety. In the case of Rc, we have a nice +example of a type that contains a `*mut` that is *definitely* not thread safe. + +Types that aren't automatically derived can *opt-in* to Send and Sync by simply +implementing them: + +```rust +struct MyBox(*mut u8); + +unsafe impl Send for MyBox {} +unsafe impl Sync for MyBox {} +``` + +In the *incredibly rare* case that a type is *inappropriately* automatically +derived to be Send or Sync, then one can also *unimplement* Send and Sync: + +```rust +struct SpecialThreadToken(u8); + +impl !Send for SpecialThreadToken {} +impl !Sync for SpecialThreadToken {} +``` + +Note that *in and of itself* it is impossible to incorrectly derive Send and Sync. +Only types that are ascribed special meaning by other unsafe code can possible cause +trouble by being incorrectly Send or Sync. + +Most uses of raw pointers should be encapsulated behind a sufficient abstraction +that Send and Sync can be derived. For instance all of Rust's standard +collections are Send and Sync (when they contain Send and Sync types) +in spite of their pervasive use raw pointers to +manage allocations and complex ownership. Similarly, most iterators into these +collections are Send and Sync because they largely behave like an `&` or `&mut` +into the collection. + +TODO: better explain what can or can't be Send or Sync. Sufficient to appeal +only to data races? \ No newline at end of file From d8f460c29d6b7e07775562e2090f3f36c6d651e0 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 10:03:51 -0700 Subject: [PATCH 053/104] improve joke --- concurrency.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concurrency.md b/concurrency.md index e5276323267c4..95973b35d4ffe 100644 --- a/concurrency.md +++ b/concurrency.md @@ -10,4 +10,4 @@ them tends to involve trade-offs that we weren't willing to commit to for 1.0. However the way Rust models concurrency makes it relatively easy design your own concurrency paradigm as a library and have *everyone else's* code Just Work with yours. Just require the right lifetimes and Send and Sync where appropriate -and you're off to the races. Or rather, not having races. Races are bad. +and you're off to the races. Or rather, off to the... not... having... races. \ No newline at end of file From 668bdd3650f8fcce956d8e47ae74247a50da3e46 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 21:19:04 -0700 Subject: [PATCH 054/104] flesh out atomics --- atomics.md | 214 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 197 insertions(+), 17 deletions(-) diff --git a/atomics.md b/atomics.md index e13fb01c06b60..9bafb761321de 100644 --- a/atomics.md +++ b/atomics.md @@ -7,27 +7,138 @@ it is a pragmatic concession to the fact that *everyone* is pretty bad at modeli atomics. At very least, we can benefit from existing tooling and research around C. -Trying to fully explain the model is fairly hopeless. If you want all the -nitty-gritty details, you should check out [C's specification][C11-model]. -Still, we'll try to cover the basics and some of the problems Rust developers -face. +Trying to fully explain the model in this book is fairly hopeless. It's defined +in terms of madness-inducing causality graphs that require a full book to properly +understand in a practical way. If you want all the nitty-gritty details, you +should check out [C's specification][C11-model]. Still, we'll try to cover the +basics and some of the problems Rust developers face. -The C11 memory model is fundamentally about trying to bridge the gap between C's -single-threaded semantics, common compiler optimizations, and hardware peculiarities -in the face of a multi-threaded environment. It does this by splitting memory -accesses into two worlds: data accesses, and atomic accesses. +The C11 memory model is fundamentally about trying to bridge the gap between +the semantics we want, the optimizations compilers want, and the inconsistent +chaos our hardware wants. *We* would like to just write programs and have them +do exactly what we said but, you know, *fast*. Wouldn't that be great? + + + + +# Compiler Reordering + +Compilers fundamentally want to be able to do all sorts of crazy transformations +to reduce data dependencies and eleminate dead code. In particular, they may +radically change the actual order of events, or make events never occur! If we +write something like + +```rust,ignore +x = 1; +y = 3; +x = 2; +``` + +The compiler may conclude that it would *really* be best if your program did + +```rust,ignore +x = 2; +y = 3; +``` + +This has inverted the order of events *and* completely eliminated one event. From +a single-threaded perspective this is completely unobservable: after all the +statements have executed we are in exactly the same state. But if our program is +multi-threaded, we may have been relying on `x` to *actually* be assigned to 1 before +`y` was assigned. We would *really* like the compiler to be able to make these kinds +of optimizations, because they can seriously improve performance. On the other hand, +we'd really like to be able to depend on our program *doing the thing we said*. + + + + +# Hardware Reordering + +On the other hand, even if the compiler totally understood what we wanted and +respected our wishes, our *hardware* might instead get us in trouble. Trouble comes +from CPUs in the form of memory hierarchies. There is indeed a global shared memory +space somewhere in your hardware, but from the perspective of each CPU core it is +*so very far away* and *so very slow*. Each CPU would rather work with its local +cache of the data and only go through all the *anguish* of talking to shared +memory *only* when it doesn't actually have that memory in cache. + +After all, that's the whole *point* of the cache, right? If every read from the +cache had to run back to shared memory to double check that it hadn't changed, +what would the point be? The end result is that the hardware doesn't guarantee +that events that occur in the same order on *one* thread, occur in the same order +on *another* thread. To guarantee this, we must issue special instructions to +the CPU telling it to be a bit less smart. + +For instance, say we convince the compiler to emit this logic: + +```text +initial state: x = 0, y = 1 + +THREAD 1 THREAD2 +y = 3; if x == 1 { +x = 1; y *= 2; + } +``` + +Ideally this program has 2 possible final states: + +* `y = 3`: (thread 2 did the check before thread 1 completed) +* `y = 6`: (thread 2 did the check after thread 1 completed) + +However there's a third potential state that the hardware enables: + +* `y = 2`: (thread 2 saw `x = 2`, but not `y = 3`, and then overwrote `y = 3`) + +``` + +It's worth noting that different kinds of CPU provide different guarantees. It +is common to seperate hardware into two categories: strongly-ordered and weakly- +ordered. Most notably x86/64 provides strong ordering guarantees, while ARM and +provides weak ordering guarantees. This has two consequences for +concurrent programming: + +* Asking for stronger guarantees on strongly-ordered hardware may be cheap or + even *free* because they already provide strong guarantees unconditionally. + Weaker guarantees may only yield performance wins on weakly-ordered hardware. + +* Asking for guarantees that are *too* weak on strongly-ordered hardware + is more likely to *happen* to work, even though your program is strictly + incorrect. If possible, concurrent algorithms should be tested on + weakly-ordered hardware. + + + + + +# Data Accesses + +The C11 memory model attempts to bridge the gap by allowing us to talk about +the *causality* of our program. Generally, this is by establishing a +*happens before* relationships between parts of the program and the threads +that are running them. This gives the hardware and compiler room to optimize the +program more aggressively where a strict happens-before relationship isn't +established, but forces them to be more careful where one *is* established. +The way we communicate these relationships are through *data accesses* and +*atomic accesses*. Data accesses are the bread-and-butter of the programming world. They are fundamentally unsynchronized and compilers are free to aggressively optimize -them. In particular data accesses are free to be reordered by the compiler +them. In particular, data accesses are free to be reordered by the compiler on the assumption that the program is single-threaded. The hardware is also free -to propagate the changes made in data accesses as lazily and inconsistently as -it wants to other threads. Mostly critically, data accesses are where we get data -races. These are pretty clearly awful semantics to try to write a multi-threaded -program with. +to propagate the changes made in data accesses to other threads +as lazily and inconsistently as it wants. Mostly critically, data accesses are +how data races happen. Data accesses are very friendly to the hardware and +compiler, but as we've seen they offer *awful* semantics to try to +write synchronized code with. -Atomic accesses are the answer to this. Each atomic access can be marked with -an *ordering*. The set of orderings Rust exposes are: +Atomic accesses are how we tell the hardware and compiler that our program is +multi-threaded. Each atomic access can be marked with +an *ordering* that specifies what kind of relationship it establishes with +other accesses. In practice, this boils down to telling the compiler and hardware +certain things they *can't* do. For the compiler, this largely revolves +around re-ordering of instructions. For the hardware, this largely revolves +around how writes are propagated to other threads. The set of orderings Rust +exposes are: * Sequentially Consistent (SeqCst) * Release @@ -36,11 +147,80 @@ an *ordering*. The set of orderings Rust exposes are: (Note: We explicitly do not expose the C11 *consume* ordering) -TODO: give simple "basic" explanation of these -TODO: implementing Arc example (why does Drop need the trailing barrier?) +TODO: negative reasoning vs positive reasoning? + + + + +# Sequentially Consistent + +Sequentially Consistent is the most powerful of all, implying the restrictions +of all other orderings. A Sequentially Consistent operation *cannot* +be reordered: all accesses on one thread that happen before and after it *stay* +before and after it. A program that has sequential consistency has the very nice +property that there is a single global execution of the program's instructions +that all threads agree on. This execution is also particularly nice to reason +about: it's just an interleaving of each thread's individual executions. + +The relative developer-friendliness of sequential consistency doesn't come for +free. Even on strongly-ordered platforms, sequential consistency involves +emitting memory fences. + +In practice, sequential consistency is rarely necessary for program correctness. +However sequential consistency is definitely the right choice if you're not +confident about the other memory orders. Having your program run a bit slower +than it needs to is certainly better than it running incorrectly! It's also +completely trivial to downgrade to a weaker consistency later. + + + + +# Acquire-Release +Acquire and Release are largely intended to be paired. Their names hint at +their use case: they're perfectly suited for acquiring and releasing locks, +and ensuring that critical sections don't overlap. +An acquire access ensures that every access after it *stays* after it. However +operations that occur before an acquire are free to be reordered to occur after +it. +A release access ensures that every access before it *stays* before it. However +operations that occur after a release are free to be reordered to occur before +it. + +Basic use of release-acquire is simple: you acquire a location of memory to +begin the critical section, and the release that location to end it. If +thread A releases a location of memory and thread B acquires that location of +memory, this establishes that A's critical section *happened before* B's +critical section. All accesses that happened before the release will be observed +by anything that happens after the acquire. + +On strongly-ordered platforms most accesses have release or acquire semantics, +making release and acquire often totally free. This is not the case on +weakly-ordered platforms. + + + + +# Relaxed + +Relaxed accesses are the absolute weakest. They can be freely re-ordered and +provide no happens-before relationship. Still, relaxed operations *are* still +atomic, which is valuable. Relaxed operations are appropriate for things that +you definitely want to happen, but don't particularly care about much else. For +instance, incrementing a counter can be relaxed if you're not using the +counter to synchronize any other accesses. + +There's rarely a benefit in making an operation relaxed on strongly-ordered +platforms, since they usually provide release-acquire semantics anyway. However +relaxed operations can be cheaper on weakly-ordered platforms. + + + + + +TODO: implementing Arc example (why does Drop need the trailing barrier?) [C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf From 778a4fa390590752df3624fe295b484a8a40288a Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 21:30:03 -0700 Subject: [PATCH 055/104] new chapter --- SUMMARY.md | 5 +++-- atomics.md | 3 --- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index 1456e3602e0b9..1d66f1bfdea80 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -34,7 +34,7 @@ * [Races](races.md) * [Send and Sync](send-and-sync.md) * [Atomics](atomics.md) -* [Example: Implementing Vec](vec.md) +* [Implementing Vec](vec.md) * [Layout](vec-layout.md) * [Allocating](vec-alloc.md) * [Push and Pop](vec-push-pop.md) @@ -43,4 +43,5 @@ * [Insert and Remove](vec-insert-remove.md) * [IntoIter](vec-into-iter.md) * [Drain](vec-drain.md) - * [Final Code](vec-final.md) \ No newline at end of file + * [Final Code](vec-final.md) +* [Implementing Arc and Mutex](arc-and-mutex.md) diff --git a/atomics.md b/atomics.md index 9bafb761321de..2a080adc2bc67 100644 --- a/atomics.md +++ b/atomics.md @@ -220,8 +220,5 @@ relaxed operations can be cheaper on weakly-ordered platforms. -TODO: implementing Arc example (why does Drop need the trailing barrier?) - - [C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf [C11-model]: http://en.cppreference.com/w/c/atomic/memory_order From 498e44d87a93183ac04690e09a39fee47dfe85b0 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 21:30:14 -0700 Subject: [PATCH 056/104] new chapter for reals --- arc-and-mutex.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 arc-and-mutex.md diff --git a/arc-and-mutex.md b/arc-and-mutex.md new file mode 100644 index 0000000000000..d28180fa9cf58 --- /dev/null +++ b/arc-and-mutex.md @@ -0,0 +1,7 @@ +% Implementing Arc and Mutex + +Knowing the theory is all fine and good, but the *best* was to understand +something is to use it. To better understand atomics and interior mutability, +we'll be implementing versions of the standard library's Arc and Mutex types. + +TODO: ALL OF THIS OMG From fcf4a7e5c87cf80ff8d7c142fbdfd8fd398ad3a7 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Tue, 7 Jul 2015 21:31:09 -0700 Subject: [PATCH 057/104] oops --- atomics.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/atomics.md b/atomics.md index 2a080adc2bc67..69c0874dc186d 100644 --- a/atomics.md +++ b/atomics.md @@ -89,8 +89,6 @@ However there's a third potential state that the hardware enables: * `y = 2`: (thread 2 saw `x = 2`, but not `y = 3`, and then overwrote `y = 3`) -``` - It's worth noting that different kinds of CPU provide different guarantees. It is common to seperate hardware into two categories: strongly-ordered and weakly- ordered. Most notably x86/64 provides strong ordering guarantees, while ARM and From 29e71b92bc5992dd2bf85dc4b27b60aaf0dcead8 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 8 Jul 2015 10:42:35 -0700 Subject: [PATCH 058/104] niko discussion affects --- atomics.md | 2 +- references.md | 33 ++++++++++++++++++++++----------- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/atomics.md b/atomics.md index 69c0874dc186d..39ea2150973a0 100644 --- a/atomics.md +++ b/atomics.md @@ -24,7 +24,7 @@ do exactly what we said but, you know, *fast*. Wouldn't that be great? # Compiler Reordering Compilers fundamentally want to be able to do all sorts of crazy transformations -to reduce data dependencies and eleminate dead code. In particular, they may +to reduce data dependencies and eliminate dead code. In particular, they may radically change the actual order of events, or make events never occur! If we write something like diff --git a/references.md b/references.md index fa47a69a7eaae..1039cb1197b64 100644 --- a/references.md +++ b/references.md @@ -25,14 +25,16 @@ as its direct children. Each variable's direct children would be their fields From this view, every value in Rust has a unique *path* in the tree of ownership. References to a value can subsequently be interpreted as a path in this tree. -Of particular interest are *prefixes*: `x` is a prefix of `y` if `x` owns `y` +Of particular interest are *ancestors* and *descendants*: if `x` owns `y`, then +`x` is an *ancestor* of `y`, and `y` is a *descendant* of `x`. Note that this is +an inclusive relationship: `x` is a descendant and ancestor of itself. -However much data doesn't reside on the stack, and we must also accommodate this. +Tragically, plenty of data doesn't reside on the stack, and we must also accommodate this. Globals and thread-locals are simple enough to model as residing at the bottom of the stack (though we must be careful with mutable globals). Data on the heap poses a different problem. -If all Rust had on the heap was data uniquely by a pointer on the stack, +If all Rust had on the heap was data uniquely owned by a pointer on the stack, then we can just treat that pointer as a struct that owns the value on the heap. Box, Vec, String, and HashMap, are examples of types which uniquely own data on the heap. @@ -51,6 +53,10 @@ types provide exclusive access through runtime restrictions. However it is also possible to establish unique ownership without interior mutability. For instance, if an Rc has refcount 1, then it is safe to mutate or move its internals. +In order to correctly communicate to the type system that a variable or field of +a struct can have interior mutability, it must be wrapped in an UnsafeCell. This +does not in itself make it safe to perform interior mutability operations on that +value. You still must yourself ensure that mutual exclusion is upheld. @@ -61,9 +67,9 @@ dereferenced. Shared references are always live unless they are literally unreac (for instance, they reside in freed or leaked memory). Mutable references can be reachable but *not* live through the process of *reborrowing*. -A mutable reference can be reborrowed to either a shared or mutable reference. -Further, the reborrow can produce exactly the same reference, or point to a -path it is a prefix of. For instance, a mutable reference can be reborrowed +A mutable reference can be reborrowed to either a shared or mutable reference to +one of its descendants. A reborrowed reference will only be live again once all +reborrows derived from it expire. For instance, a mutable reference can be reborrowed to point to a field of its referent: ```rust @@ -79,7 +85,7 @@ let x = &mut (1, 2); ``` It is also possible to reborrow into *multiple* mutable references, as long as -they are *disjoint*: no reference is a prefix of another. Rust +they are *disjoint*: no reference is an ancestor of another. Rust explicitly enables this to be done with disjoint struct fields, because disjointness can be statically proven: @@ -89,6 +95,7 @@ let x = &mut (1, 2); // reborrow x to two disjoint subfields let y = &mut x.0; let z = &mut x.1; + // y and z are now live, but x isn't *y = 3; *z = 4; @@ -105,14 +112,14 @@ To simplify things, we can model variables as a fake type of reference: *owned* references. Owned references have much the same semantics as mutable references: they can be re-borrowed in a mutable or shared manner, which makes them no longer live. Live owned references have the unique property that they can be moved -out of (though mutable references *can* be swapped out of). This is +out of (though mutable references *can* be swapped out of). This power is only given to *live* owned references because moving its referent would of course invalidate all outstanding references prematurely. As a local lint against inappropriate mutation, only variables that are marked as `mut` can be borrowed mutably. -It is also interesting to note that Box behaves exactly like an owned +It is interesting to note that Box behaves exactly like an owned reference. It can be moved out of, and Rust understands it sufficiently to reason about its paths like a normal variable. @@ -123,8 +130,12 @@ reason about its paths like a normal variable. With liveness and paths defined, we can now properly define *aliasing*: -**A mutable reference is aliased if there exists another live reference to it or -one of its prefixes.** +**A mutable reference is aliased if there exists another live reference to one of +its ancestors or descendants.** + +(If you prefer, you may also say the two live references alias *each other*. +This has no semantic consequences, but is probably a more useful notion when +verifying the soundness of a construct.) That's it. Super simple right? Except for the fact that it took us two pages to define all of the terms in that defintion. You know: Super. Simple. From e167ee825984b649c1e5e1754b8479f70f1043c5 Mon Sep 17 00:00:00 2001 From: mdinger Date: Wed, 8 Jul 2015 15:41:39 -0400 Subject: [PATCH 059/104] typos --- meet-safe-and-unsafe.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/meet-safe-and-unsafe.md b/meet-safe-and-unsafe.md index e12997f6f2461..dfcbd4a216c63 100644 --- a/meet-safe-and-unsafe.md +++ b/meet-safe-and-unsafe.md @@ -14,12 +14,12 @@ on a leap year? Are we ready for that? Unsafe better be, because if they get built to Unsafe's standards! That's where Safe comes in. Safe has to handle *everything else*. Since Safe needs -to *get work done*, they've grown to be fairly carless and clumsy! Safe doesn't worry +to *get work done*, they've grown to be fairly careless and clumsy! Safe doesn't worry about all the crazy eventualities that Unsafe does, because life is too short to deal with leap-year-earthquakes. Of course, this means there's some jobs that Safe just can't handle. Safe is all about quantity over quality. -Unsafe loves Safe to bits, but knows that tey *can never trust them to do the +Unsafe loves Safe to bits, but knows that they *can never trust them to do the right thing*. Still, Unsafe acknowledges that not every problem needs quite the attention to detail that they apply. Indeed, Unsafe would *love* if Safe could do *everything* for them. To accomplish this, Unsafe spends most of their time From acd3c5947a4b85113a0c21d435dec5bd1bd22956 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Wed, 8 Jul 2015 15:04:55 -0700 Subject: [PATCH 060/104] fix typo --- working-with-unsafe.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/working-with-unsafe.md b/working-with-unsafe.md index 6725132466191..57b71d1603391 100644 --- a/working-with-unsafe.md +++ b/working-with-unsafe.md @@ -33,7 +33,7 @@ fn do_idx(idx: usize, arr: &[u8]) -> Option { } ``` -This program is now unsound, an yet *we only modified safe code*. This is the +This program is now unsound, and yet *we only modified safe code*. This is the fundamental problem of safety: it's non-local. The soundness of our unsafe operations necessarily depends on the state established by "safe" operations. Although safety *is* modular (we *still* don't need to worry about about From 62e827cfc7b76c0a8a2485fb421f6f41af289048 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 11:12:16 -0700 Subject: [PATCH 061/104] rewrite intro --- README.md | 45 ++++++++--- SUMMARY.md | 2 +- meet-safe-and-unsafe.md | 174 ++++++++++++++++++++++------------------ safe-unsafe-meaning.md | 105 ++++++++++++------------ working-with-unsafe.md | 30 +++++-- 5 files changed, 202 insertions(+), 154 deletions(-) diff --git a/README.md b/README.md index a801a21db3d53..874f6f2ac6121 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,39 @@ -% The Unsafe Rust Programming Language +% The Advanced Rust Programming Language # NOTE: This is a draft document, and may contain serious errors -**This document is about advanced functionality and low-level development practices -in the Rust Programming Language. Most of the things discussed won't matter -to the average Rust programmer. However if you wish to correctly write unsafe -code in Rust, this text contains invaluable information.** +So you've played around with Rust a bit. You've written a few simple programs and +you think you grok the basics. Maybe you've even read through +*[The Rust Programming Language][trpl]*. Now you want to get neck-deep in all the +nitty-gritty details of the language. You want to know those weird corner-cases. +You want to know what the heck `unsafe` really means, and how to properly use it. +This is the book for you. -The Unsafe Rust Programming Language (TURPL) seeks to complement -[The Rust Programming Language Book][trpl] (TRPL). -Where TRPL introduces the language and teaches the basics, TURPL dives deep into -the specification of the language, and all the nasty bits necessary to write -Unsafe Rust. TURPL does not assume you have read TRPL, but does assume you know -the basics of the language and systems programming. We will not explain the -stack or heap. We will not explain the basic syntax. +To be clear, this book goes into *serious* detail. We're going to dig into +exception-safety and pointer aliasing. We're going to talk about memory +models. We're even going to do some type-theory. This is stuff that you +absolutely *don't* need to know to write fast and safe Rust programs. +You could probably close this book *right now* and still have a productive +and happy career in Rust. +However if you intend to write unsafe code -- or just *really* want to dig into +the guts of the language -- this book contains *invaluable* information. +Unlike *The Rust Programming Language* we *will* be assuming considerable prior +knowledge. In particular, you should be comfortable with: -[trpl]: https://doc.rust-lang.org/book/ \ No newline at end of file +* Basic Systems Programming: + * Pointers + * [The stack and heap][] + * The memory hierarchy (caches) + * Threads + +* [Basic Rust][] + +Due to the nature of advanced Rust programming, we will be spending a lot of time +talking about *safety* and *guarantees*. In particular, a significant portion of +the book will be dedicated to correctly writing and understanding Unsafe Rust. + +[trpl]: https://doc.rust-lang.org/book/ +[The stack and heap]: https://doc.rust-lang.org/book/the-stack-and-the-heap.html +[Basic Rust]: https://doc.rust-lang.org/book/syntax-and-semantics.html diff --git a/SUMMARY.md b/SUMMARY.md index 1d66f1bfdea80..dc494d2b0c940 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,7 +1,7 @@ # Summary * [Meet Safe and Unsafe](meet-safe-and-unsafe.md) - * [What Do Safe and Unsafe Mean](safe-unsafe-meaning.md) + * [How Safe and Unsafe Interact](safe-unsafe-meaning.md) * [Working with Unsafe](working-with-unsafe.md) * [Data Layout](data.md) * [repr(Rust)](repr-rust.md) diff --git a/meet-safe-and-unsafe.md b/meet-safe-and-unsafe.md index dfcbd4a216c63..5ff000f2bbce9 100644 --- a/meet-safe-and-unsafe.md +++ b/meet-safe-and-unsafe.md @@ -1,82 +1,98 @@ % Meet Safe and Unsafe -Safe and Unsafe are Rust's chief engineers. - -TODO: ADORABLE PICTURES OMG - -Unsafe handles all the dangerous internal stuff. They build the foundations -and handle all the dangerous materials. By all accounts, Unsafe is really a bit -unproductive, because the nature of their work means that they have to spend a -lot of time checking and double-checking everything. What if there's an earthquake -on a leap year? Are we ready for that? Unsafe better be, because if they get -*anything* wrong, everything will blow up! What Unsafe brings to the table is -*quality*, not quantity. Still, nothing would ever get done if everything was -built to Unsafe's standards! - -That's where Safe comes in. Safe has to handle *everything else*. Since Safe needs -to *get work done*, they've grown to be fairly careless and clumsy! Safe doesn't worry -about all the crazy eventualities that Unsafe does, because life is too short to deal -with leap-year-earthquakes. Of course, this means there's some jobs that Safe just -can't handle. Safe is all about quantity over quality. - -Unsafe loves Safe to bits, but knows that they *can never trust them to do the -right thing*. Still, Unsafe acknowledges that not every problem needs quite the -attention to detail that they apply. Indeed, Unsafe would *love* if Safe could do -*everything* for them. To accomplish this, Unsafe spends most of their time -building *safe abstractions*. These abstractions handle all the nitty-gritty -details for Safe, and choose good defaults so that the simplest solution (which -Safe will inevitably use) is usually the *right* one. Once a safe abstraction is -built, Unsafe ideally needs to never work on it again, and Safe can blindly use -it in all their work. - -Unsafe's attention to detail means that all the things that they mark as ok for -Safe to use can be combined in arbitrarily ridiculous ways, and all the rules -that Unsafe is forced to uphold will never be violated. If they *can* be violated -by Safe, that means *Unsafe*'s the one in the wrong. Safe can work carelessly, -knowing that if anything blows up, it's not *their* fault. Safe can also call in -Unsafe at any time if there's a hard problem they can't quite work out, or if they -can't meet the client's quality demands. Of course, Unsafe will beg and plead Safe -to try their latest safe abstraction first! - -In addition to being adorable, Safe and Unsafe are what makes Rust possible. -Rust can be thought of as two different languages: Safe Rust, and Unsafe Rust. -Any time someone opines the guarantees of Rust, they are almost surely talking about -Safe. However Safe is not sufficient to write every program. For that, -we need the Unsafe superset. - -Most fundamentally, writing bindings to other languages -(such as the C exposed by your operating system) is never going to be safe. Rust -can't control what other languages do to program execution! However Unsafe is -also necessary to construct fundamental abstractions where the type system is not -sufficient to automatically prove what you're doing is sound. - -Indeed, the Rust standard library is implemented in Rust, and it makes substantial -use of Unsafe for implementing IO, memory allocation, collections, -synchronization, and other low-level computational primitives. - -Upon hearing this, many wonder why they would not simply just use C or C++ in place of -Rust (or just use a "real" safe language). If we're going to do unsafe things, why not -lean on these much more established languages? - -The most important difference between C++ and Rust is a matter of defaults: -Rust is 100% safe by default. Even when you *opt out* of safety in Rust, it is a modular -action. In deciding to work with unchecked uninitialized memory, this does not -suddenly make dangling or null pointers a problem. When using unchecked indexing on `x`, -one does not have to suddenly worry about indexing out of bounds on `y`. -C and C++, by contrast, have pervasive unsafety baked into the language. Even the -modern best practices like `unique_ptr` have various safety pitfalls. - -It cannot be emphasized enough that Unsafe should be regarded as an exceptional -thing, not a normal one. Unsafe is often the domain of *fundamental libraries*: anything that needs -to make FFI bindings or define core abstractions. These fundamental libraries then expose -a safe interface for intermediate libraries and applications to build upon. And these -safe interfaces make an important promise: if your application segfaults, it's not your -fault. *They* have a bug. - -And really, how is that different from *any* safe language? Python, Ruby, and Java libraries -can internally do all sorts of nasty things. The languages themselves are no -different. Safe languages *regularly* have bugs that cause critical vulnerabilities. -The fact that Rust is written with a healthy spoonful of Unsafe is no different. -However it *does* mean that Rust doesn't need to fall back to the pervasive unsafety of -C to do the nasty things that need to get done. +Programmers in safe "high-level" languages face a fundamental dilemma. On one +hand, it would be *really* great to just say what you want and not worry about +how it's done. On the other hand, that can lead to some *really* poor +performance. It may be necessary to drop down to less clear or idiomatic +practices to get the performance characteristics you want. Or maybe you just +throw up your hands in disgust and decide to shell out to an implementation in +a less sugary-wonderful *unsafe* language. +Worse, when you want to talk directly to the operating system, you *have* to +talk to an unsafe language: *C*. C is ever-present and unavoidable. It's the +lingua-franca of the programming world. +Even other safe languages generally expose C interfaces for the world at large! +Regardless of *why* you're doing it, as soon as your program starts talking to +C it stops being safe. + +With that said, Rust is *totally* a safe programming language. + +Well, Rust *has* a safe programming language. Let's step back a bit. + +Rust can be thought of as being composed of two +programming languages: *Safe* and *Unsafe*. Safe is For Reals Totally Safe. +Unsafe, unsurprisingly, is *not* For Reals Totally Safe. In fact, Unsafe lets +you do some really crazy unsafe things. + +Safe is *the* Rust programming language. If all you do is write Safe Rust, +you will never have to worry about type-safety or memory-safety. You will never +endure a null or dangling pointer, or any of that Undefined Behaviour nonsense. + +*That's totally awesome*. + +The standard library also gives you enough utilities out-of-the-box that you'll +be able to write awesome high-performance applications and libraries in pure +idiomatic Safe Rust. + +But maybe you want to talk to another language. Maybe you're writing a +low-level abstraction not exposed by the standard library. Maybe you're +*writing* the standard library (which is written entirely in Rust). Maybe you +need to do something the type-system doesn't understand and just *frob some dang +bits*. Maybe you need Unsafe Rust. + +Unsafe Rust is exactly like Safe Rust with *all* the same rules and semantics. +However Unsafe Rust lets you do some *extra* things that are Definitely Not Safe. + +The only things that are different in Unsafe Rust are that you can: + +* Dereference raw pointers +* Call `unsafe` functions (including C functions, intrinsics, and the raw allocator) +* Implement `unsafe` traits +* Mutate statics + +That's it. The reason these operations are relegated to Unsafe is that misusing +any of these things will cause the ever dreaded Undefined Behaviour. Invoking +Undefined Behaviour gives the compiler full rights to do arbitrarily bad things +to your program. You definitely *should not* invoke Undefined Behaviour. + +Unlike C, Undefined Behaviour is pretty limited in scope in Rust. All the core +language cares about is preventing the following things: + +* Dereferencing null or dangling pointers +* Reading [uninitialized memory][] +* Breaking the [pointer aliasing rules][] +* Producing invalid primitive values: + * dangling/null references + * a `bool` that isn't 0 or 1 + * an undefined `enum` discriminant + * a `char` outside the ranges [0x0, 0xD7FF] and [0xE000, 0x10FFFF] + * A non-utf8 `str` +* Unwinding into another language +* Causing a [data race][race] +* Double-dropping a value + +That's it. That's all the Undefined Behaviour baked into Rust. Of course, unsafe +functions and traits are free to declare arbitrary other constraints that a +program must maintain to avoid Undefined Behaviour. However these are generally +just things that will transitively lead to one of the above problems. Some +additional constraints may also derive from compiler intrinsics that make special +assumptions about how code can be optimized. + +Rust is otherwise quite permissive with respect to other dubious operations. Rust +considers it "safe" to: + +* Deadlock +* Have a [race condition][race] +* Leak memory +* Fail to call destructors +* Overflow integers +* Abort the program +* Delete the production database + +However any program that actually manages to do such a thing is *probably* +incorrect. Rust provides lots of tools to make these things rare, but +these problems are considered impractical to categorically prevent. + +[pointer aliasing rules]: references.html +[uninitialized memory]: uninitialized.html +[race]: races.html diff --git a/safe-unsafe-meaning.md b/safe-unsafe-meaning.md index 6c3d4087b8198..082970d203872 100644 --- a/safe-unsafe-meaning.md +++ b/safe-unsafe-meaning.md @@ -1,38 +1,17 @@ -% What do Safe and Unsafe really mean? - -Rust cares about preventing the following things: - -* Dereferencing null or dangling pointers -* Reading [uninitialized memory][] -* Breaking the [pointer aliasing rules][] -* Producing invalid primitive values: - * dangling/null references - * a `bool` that isn't 0 or 1 - * an undefined `enum` discriminant - * a `char` larger than char::MAX (TODO: check if stronger restrictions apply) - * A non-utf8 `str` -* Unwinding into another language -* Causing a [data race][] -* Invoking Misc. Undefined Behaviour (in e.g. compiler intrinsics) - -That's it. That's all the Undefined Behaviour in Rust. Libraries are free to -declare arbitrary requirements if they could transitively cause memory safety -issues, but it all boils down to the above actions. Rust is otherwise -quite permisive with respect to other dubious operations. Rust considers it -"safe" to: - -* Deadlock -* Have a Race Condition -* Leak memory -* Fail to call destructors -* Overflow integers -* Delete the production database - -However any program that does such a thing is *probably* incorrect. Rust -provides lots of tools to make doing these things rare, but these problems are -considered impractical to categorically prevent. - -Rust models the seperation between Safe and Unsafe with the `unsafe` keyword. +% How Safe and Unsafe Interact + +So what's the relationship between Safe and Unsafe? How do they interact? + +Rust models the seperation between Safe and Unsafe with the `unsafe` keyword, which +can be thought as a sort of *foreign function interface* (FFI) between Safe and Unsafe. +This is the magic behind why we can say Safe is a safe language: all the scary unsafe +bits are relagated *exclusively* to FFI *just like every other safe language*. + +However because one language is a subset of the other, the two can be cleanly +intermixed as long as the boundary between Safe and Unsafe is denoted with the +`unsafe` keyword. No need to write headers, initialize runtimes, or any of that +other FFI boiler-plate. + There are several places `unsafe` can appear in Rust today, which can largely be grouped into two categories: @@ -44,7 +23,7 @@ you to write `unsafe` elsewhere: the danger. * On trait declarations, `unsafe` is declaring that *implementing* the trait is an unsafe operation, as it has contracts that other unsafe code is free to - trust blindly. + trust blindly. (More on this below.) * I am declaring that I have, to the best of my knowledge, adhered to the unchecked contracts: @@ -55,14 +34,14 @@ unchecked contracts: There is also `#[unsafe_no_drop_flag]`, which is a special case that exists for historical reasons and is in the process of being phased out. See the section on -[destructors][] for details. +[drop flags][] for details. Some examples of unsafe functions: * `slice::get_unchecked` will perform unchecked indexing, allowing memory safety to be freely violated. * `ptr::offset` is an intrinsic that invokes Undefined Behaviour if it is - not "in bounds" as defined by LLVM (see the lifetimes section for details). + not "in bounds" as defined by LLVM. * `mem::transmute` reinterprets some value as having the given type, bypassing type safety in arbitrary ways. (see [conversions][] for details) * All FFI functions are `unsafe` because they can do arbitrary things. @@ -72,14 +51,34 @@ Some examples of unsafe functions: As of Rust 1.0 there are exactly two unsafe traits: * `Send` is a marker trait (it has no actual API) that promises implementors - are safe to send to another thread. + are safe to send (move) to another thread. * `Sync` is a marker trait that promises that threads can safely share implementors through a shared reference. -The need for unsafe traits boils down to the fundamental lack of trust that Unsafe -has for Safe. All safe traits are free to declare arbitrary contracts, but because -implementing them is a job for Safe, Unsafe can't trust those contracts to actually -be upheld. +The need for unsafe traits boils down to the fundamental property of safe code: + +**No matter how completely awful Safe code is, it can't cause Undefined +Behaviour.** + +This means that Unsafe, **the royal vanguard of Undefined Behaviour**, has to be +*super paranoid* about generic safe code. Unsafe is free to trust *specific* safe +code (or else you would degenerate into infinite spirals of paranoid despair). +It is generally regarded as ok to trust the standard library to be correct, as +std is effectively an extension of the language (and you *really* just have to trust +the language). If `std` fails to uphold the guarantees it declares, then it's +basically a language bug. + +That said, it would be best to minimize *needlessly* relying on properties of +concrete safe code. Bugs happen! Of course, I must reinforce that this is only +a concern for Unsafe code. Safe code can't blindly trust anyone and everyone +as far as basic memory-safety is concerned. + +On the other hand, safe traits are free to declare arbitrary contracts, but because +implementing them is Safe, Unsafe can't trust those contracts to actually +be upheld. This is different from the concrete case because *anyone* can +randomly implement the interface. There is something fundamentally different +about trusting a *particular* piece of code to be correct, and trusting *all the +code that will ever be written* to be correct. For instance Rust has `PartialOrd` and `Ord` traits to try to differentiate between types which can "just" be compared, and those that actually implement a @@ -99,14 +98,13 @@ destructors will be successfully called! Hooray! However BTreeMap is implemented using a modest spoonful of Unsafe (most collections are). That means that it is not necessarily *trivially true* that a bad Ord implementation will make BTreeMap behave safely. Unsafe must be sure not to rely -on Ord *where safety is at stake*, because Ord is provided by Safe, and memory -safety is not Safe's responsibility to uphold. *It must be impossible for Safe -code to violate memory safety*. +on Ord *where safety is at stake*. Ord is provided by Safe, and safety is not +Safe's responsibility to uphold. But wouldn't it be grand if there was some way for Unsafe to trust *some* trait contracts *somewhere*? This is the problem that unsafe traits tackle: by marking *the trait itself* as unsafe *to implement*, Unsafe can trust the implementation -to be correct (because Unsafe can trust themself). +to be correct. Rust has traditionally avoided making traits unsafe because it makes Unsafe pervasive, which is not desirable. Send and Sync are unsafe is because @@ -114,11 +112,12 @@ thread safety is a *fundamental property* that Unsafe cannot possibly hope to defend against in the same way it would defend against a bad Ord implementation. The only way to possibly defend against thread-unsafety would be to *not use threading at all*. Making every operation atomic isn't even sufficient, because -it's possible for complex invariants between disjoint locations in memory. +it's possible for complex invariants to exist between disjoint locations in +memory. For instance, the pointer and capacity of a Vec must be in sync. Even concurrent paradigms that are traditionally regarded as Totally Safe like message passing implicitly rely on some notion of thread safety -- are you -really message-passing if you send a *pointer*? Send and Sync therefore require +really message-passing if you pass a *pointer*? Send and Sync therefore require some *fundamental* level of trust that Safe code can't provide, so they must be unsafe to implement. To help obviate the pervasive unsafety that this would introduce, Send (resp. Sync) is *automatically* derived for all types composed only @@ -128,8 +127,6 @@ primitives). -[pointer aliasing rules]: lifetimes.html#references -[uninitialized memory]: uninitialized.html -[data race]: concurrency.html -[destructors]: raii.html -[conversions]: conversions.html \ No newline at end of file + +[drop flags]: drop-flags.html +[conversions]: conversions.html diff --git a/working-with-unsafe.md b/working-with-unsafe.md index 57b71d1603391..b1174a74c0bcc 100644 --- a/working-with-unsafe.md +++ b/working-with-unsafe.md @@ -1,11 +1,11 @@ % Working with Unsafe -Rust generally only gives us the tools to talk about safety in a scoped and -binary manner. Unfortunately reality is significantly more complicated than that. +Rust generally only gives us the tools to talk about Unsafe in a scoped and +binary manner. Unfortunately, reality is significantly more complicated than that. For instance, consider the following toy function: ```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { +pub fn index(idx: usize, arr: &[u8]) -> Option { if idx < arr.len() { unsafe { Some(*arr.get_unchecked(idx)) @@ -22,7 +22,7 @@ function, the scope of the unsafe block is questionable. Consider changing the `<` to a `<=`: ```rust -fn do_idx(idx: usize, arr: &[u8]) -> Option { +pub fn index(idx: usize, arr: &[u8]) -> Option { if idx <= arr.len() { unsafe { Some(*arr.get_unchecked(idx)) @@ -45,7 +45,7 @@ implementation of `Vec`: ```rust // Note this defintion is insufficient. See the section on lifetimes. -struct Vec { +pub struct Vec { ptr: *mut T, len: usize, cap: usize, @@ -55,7 +55,7 @@ struct Vec { // We currently live in a nice imaginary world of only positive fixed-size // types. impl Vec { - fn push(&mut self, elem: T) { + pub fn push(&mut self, elem: T) { if self.len == self.cap { // not important for this example self.reallocate(); @@ -80,9 +80,25 @@ adding the following method: This code is safe, but it is also completely unsound. Changing the capacity violates the invariants of Vec (that `cap` reflects the allocated space in the -Vec). This is not something the rest of `Vec` can guard against. It *has* to +Vec). This is not something the rest of Vec can guard against. It *has* to trust the capacity field because there's no way to verify it. `unsafe` does more than pollute a whole function: it pollutes a whole *module*. Generally, the only bullet-proof way to limit the scope of unsafe code is at the module boundary with privacy. + +However this works *perfectly*. The existence of `make_room` is *not* a +problem for the soundness of Vec because we didn't mark it as public. Only the +module that defines this function can call it. Also, `make_room` directly +accesses the private fields of Vec, so it can only be written in the same module +as Vec. + +It is therefore possible for us to write a completely safe abstraction that +relies on complex invariants. This is *critical* to the relationship between +Safe Rust and Unsafe Rust. We have already seen that Unsafe code must trust +*some* Safe code, but can't trust *arbitrary* Safe code. However if Unsafe +couldn't prevent client Safe code from messing with its state in arbitrary ways, +safety would be a lost cause. + +Safety lives! + From cbc6408281ce7d67a3454761e832d402971a85cf Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 11:46:57 -0700 Subject: [PATCH 062/104] fix --- safe-unsafe-meaning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/safe-unsafe-meaning.md b/safe-unsafe-meaning.md index 082970d203872..2a593ffc5a7a1 100644 --- a/safe-unsafe-meaning.md +++ b/safe-unsafe-meaning.md @@ -70,7 +70,7 @@ basically a language bug. That said, it would be best to minimize *needlessly* relying on properties of concrete safe code. Bugs happen! Of course, I must reinforce that this is only -a concern for Unsafe code. Safe code can't blindly trust anyone and everyone +a concern for Unsafe code. Safe code can blindly trust anyone and everyone as far as basic memory-safety is concerned. On the other hand, safe traits are free to declare arbitrary contracts, but because From d66c67be784a4d0678f60158adb9e76c6b58d9c3 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 17:49:58 -0700 Subject: [PATCH 063/104] clarify atomics --- atomics.md | 85 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 57 insertions(+), 28 deletions(-) diff --git a/atomics.md b/atomics.md index 39ea2150973a0..82e69dd2e13fc 100644 --- a/atomics.md +++ b/atomics.md @@ -10,8 +10,8 @@ C. Trying to fully explain the model in this book is fairly hopeless. It's defined in terms of madness-inducing causality graphs that require a full book to properly understand in a practical way. If you want all the nitty-gritty details, you -should check out [C's specification][C11-model]. Still, we'll try to cover the -basics and some of the problems Rust developers face. +should check out [C's specification (Section 7.17)][C11-model]. Still, we'll try +to cover the basics and some of the problems Rust developers face. The C11 memory model is fundamentally about trying to bridge the gap between the semantics we want, the optimizations compilers want, and the inconsistent @@ -127,7 +127,8 @@ to propagate the changes made in data accesses to other threads as lazily and inconsistently as it wants. Mostly critically, data accesses are how data races happen. Data accesses are very friendly to the hardware and compiler, but as we've seen they offer *awful* semantics to try to -write synchronized code with. +write synchronized code with. Actually, that's too weak. *It is literally +impossible to write correct synchronized code using only data accesses*. Atomic accesses are how we tell the hardware and compiler that our program is multi-threaded. Each atomic access can be marked with @@ -146,29 +147,33 @@ exposes are: (Note: We explicitly do not expose the C11 *consume* ordering) TODO: negative reasoning vs positive reasoning? - +TODO: "can't forget to synchronize" # Sequentially Consistent Sequentially Consistent is the most powerful of all, implying the restrictions -of all other orderings. A Sequentially Consistent operation *cannot* +of all other orderings. Intuitively, a sequentially consistent operation *cannot* be reordered: all accesses on one thread that happen before and after it *stay* -before and after it. A program that has sequential consistency has the very nice -property that there is a single global execution of the program's instructions -that all threads agree on. This execution is also particularly nice to reason -about: it's just an interleaving of each thread's individual executions. +before and after it. A data-race-free program that uses only sequentially consistent +atomics and data accesses has the very nice property that there is a single global +execution of the program's instructions that all threads agree on. This execution +is also particularly nice to reason about: it's just an interleaving of each thread's +individual executions. This *does not* hold if you start using the weaker atomic +orderings. The relative developer-friendliness of sequential consistency doesn't come for -free. Even on strongly-ordered platforms, sequential consistency involves +free. Even on strongly-ordered platforms sequential consistency involves emitting memory fences. In practice, sequential consistency is rarely necessary for program correctness. However sequential consistency is definitely the right choice if you're not confident about the other memory orders. Having your program run a bit slower than it needs to is certainly better than it running incorrectly! It's also -completely trivial to downgrade to a weaker consistency later. +*mechanically* trivial to downgrade atomic operations to have a weaker +consistency later on. Just change `SeqCst` to e.g. `Relaxed` and you're done! Of +course, proving that this transformation is *correct* is whole other matter. @@ -179,20 +184,42 @@ Acquire and Release are largely intended to be paired. Their names hint at their use case: they're perfectly suited for acquiring and releasing locks, and ensuring that critical sections don't overlap. -An acquire access ensures that every access after it *stays* after it. However -operations that occur before an acquire are free to be reordered to occur after -it. +Intuitively, an acquire access ensures that every access after it *stays* after +it. However operations that occur before an acquire are free to be reordered to +occur after it. Similarly, a release access ensures that every access before it +*stays* before it. However operations that occur after a release are free to +be reordered to occur before it. + +When thread A releases a location in memory and then thread B subsequently +acquires *the same* location in memory, causality is established. Every write +that happened *before* A's release will be observed by B *after* it's release. +However no causality is established with any other threads. Similarly, no +causality is established if A and B access *different* locations in memory. + +Basic use of release-acquire is therefore simple: you acquire a location of +memory to begin the critical section, and then release that location to end it. +For instance, a simple spinlock might look like: + +```rust +use std::sync::Arc; +use std::sync::atomic::{AtomicBool, Ordering}; +use std::thread; -A release access ensures that every access before it *stays* before it. However -operations that occur after a release are free to be reordered to occur before -it. +fn main() { + let lock = Arc::new(AtomicBool::new(true)); // value answers "am I locked?" -Basic use of release-acquire is simple: you acquire a location of memory to -begin the critical section, and the release that location to end it. If -thread A releases a location of memory and thread B acquires that location of -memory, this establishes that A's critical section *happened before* B's -critical section. All accesses that happened before the release will be observed -by anything that happens after the acquire. + // ... distribute lock to threads somehow ... + + // Try to acquire the lock by setting it to false + while !lock.compare_and_swap(true, false, Ordering::Acquire) { } + // broke out of the loop, so we successfully acquired the lock! + + // ... scary data accesses ... + + // ok we're done, release the lock + lock.store(true, Ordering::Release); +} +``` On strongly-ordered platforms most accesses have release or acquire semantics, making release and acquire often totally free. This is not the case on @@ -205,10 +232,12 @@ weakly-ordered platforms. Relaxed accesses are the absolute weakest. They can be freely re-ordered and provide no happens-before relationship. Still, relaxed operations *are* still -atomic, which is valuable. Relaxed operations are appropriate for things that -you definitely want to happen, but don't particularly care about much else. For -instance, incrementing a counter can be relaxed if you're not using the -counter to synchronize any other accesses. +atomic. That is, they don't count as data accesses and any read-modify-write +operations done to them occur atomically. Relaxed operations are appropriate for +things that you definitely want to happen, but don't particularly otherwise care +about. For instance, incrementing a counter can be safely done by multiple +threads using a relaxed `fetch_add` if you're not using the counter to +synchronize any other accesses. There's rarely a benefit in making an operation relaxed on strongly-ordered platforms, since they usually provide release-acquire semantics anyway. However @@ -219,4 +248,4 @@ relaxed operations can be cheaper on weakly-ordered platforms. [C11-busted]: http://plv.mpi-sws.org/c11comp/popl15.pdf -[C11-model]: http://en.cppreference.com/w/c/atomic/memory_order +[C11-model]: http://www.open-std.org/jtc1/sc22/wg14/www/standards.html#9899 From bdc62e009cc5b62fcf356e7977c6397296b2077d Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 21:37:19 -0700 Subject: [PATCH 064/104] fix definition --- references.md | 2 +- working-with-unsafe.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/references.md b/references.md index 1039cb1197b64..24c6b607840d8 100644 --- a/references.md +++ b/references.md @@ -138,7 +138,7 @@ This has no semantic consequences, but is probably a more useful notion when verifying the soundness of a construct.) That's it. Super simple right? Except for the fact that it took us two pages -to define all of the terms in that defintion. You know: Super. Simple. +to define all of the terms in that definition. You know: Super. Simple. Actually it's a bit more complicated than that. In addition to references, Rust has *raw pointers*: `*const T` and `*mut T`. Raw pointers have no inherent diff --git a/working-with-unsafe.md b/working-with-unsafe.md index b1174a74c0bcc..69d0b31cf88d6 100644 --- a/working-with-unsafe.md +++ b/working-with-unsafe.md @@ -44,7 +44,7 @@ Trickier than that is when we get into actual statefulness. Consider a simple implementation of `Vec`: ```rust -// Note this defintion is insufficient. See the section on lifetimes. +// Note this definition is insufficient. See the section on lifetimes. pub struct Vec { ptr: *mut T, len: usize, From d4268f944714dc01fe98c6353d7a23bd9631e4c2 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 22:09:44 -0700 Subject: [PATCH 065/104] shard out and clean up unwinding --- SUMMARY.md | 2 + exception-safety.md | 217 ++++++++++++++++++++++++++++++++++++ poisoning.md | 35 ++++++ unwinding.md | 266 ++------------------------------------------ 4 files changed, 264 insertions(+), 256 deletions(-) create mode 100644 exception-safety.md create mode 100644 poisoning.md diff --git a/SUMMARY.md b/SUMMARY.md index dc494d2b0c940..8a8ea6dfab799 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -30,6 +30,8 @@ * [Destructors](destructors.md) * [Leaking](leaking.md) * [Unwinding](unwinding.md) + * [Exception Safety](exception-safety.md) + * [Poisoning](poisoning.md) * [Concurrency](concurrency.md) * [Races](races.md) * [Send and Sync](send-and-sync.md) diff --git a/exception-safety.md b/exception-safety.md new file mode 100644 index 0000000000000..12e000b5ef6e4 --- /dev/null +++ b/exception-safety.md @@ -0,0 +1,217 @@ +% Exception Safety + +Although programs should use unwinding sparingly, there's *a lot* of code that +*can* panic. If you unwrap a None, index out of bounds, or divide by 0, your +program *will* panic. On debug builds, *every* arithmetic operation can panic +if it overflows. Unless you are very careful and tightly control what code runs, +pretty much everything can unwind, and you need to be ready for it. + +Being ready for unwinding is often referred to as *exception safety* +in the broader programming world. In Rust, their are two levels of exception +safety that one may concern themselves with: + +* In unsafe code, we *must* be exception safe to the point of not violating + memory safety. We'll call this *minimal* exception safety. + +* In safe code, it is *good* to be exception safe to the point of your program + doing the right thing. We'll call this *maximal* exception safety. + +As is the case in many places in Rust, Unsafe code must be ready to deal with +bad Safe code when it comes to unwinding. Code that transiently creates +unsound states must be careful that a panic does not cause that state to be +used. Generally this means ensuring that only non-panicking code is run while +these states exist, or making a guard that cleans up the state in the case of +a panic. This does not necessarily mean that the state a panic witnesses is a +fully *coherent* state. We need only guarantee that it's a *safe* state. + +Most Unsafe code is leaf-like, and therefore fairly easy to make exception-safe. +It controls all the code that runs, and most of that code can't panic. However +it is not uncommon for Unsafe code to work with arrays of temporarily +uninitialized data while repeatedly invoking caller-provided code. Such code +needs to be careful and consider exception safety. + + + + + +## Vec::push_all + +`Vec::push_all` is a temporary hack to get extending a Vec by a slice reliably +effecient without specialization. Here's a simple implementation: + +```rust,ignore +impl Vec { + fn push_all(&mut self, to_push: &[T]) { + self.reserve(to_push.len()); + unsafe { + // can't overflow because we just reserved this + self.set_len(self.len() + to_push.len()); + + for (i, x) in to_push.iter().enumerate() { + self.ptr().offset(i as isize).write(x.clone()); + } + } + } +} +``` + +We bypass `push` in order to avoid redundant capacity and `len` checks on the +Vec that we definitely know has capacity. The logic is totally correct, except +there's a subtle problem with our code: it's not exception-safe! `set_len`, +`offset`, and `write` are all fine, but *clone* is the panic bomb we over-looked. + +Clone is completely out of our control, and is totally free to panic. If it does, +our function will exit early with the length of the Vec set too large. If +the Vec is looked at or dropped, uninitialized memory will be read! + +The fix in this case is fairly simple. If we want to guarantee that the values +we *did* clone are dropped we can set the len *in* the loop. If we just want to +guarantee that uninitialized memory can't be observed, we can set the len *after* +the loop. + + + + + +## BinaryHeap::sift_up + +Bubbling an element up a heap is a bit more complicated than extending a Vec. +The pseudocode is as follows: + +```text +bubble_up(heap, index): + while index != 0 && heap[index] < heap[parent(index)]: + heap.swap(index, parent(index)) + index = parent(index) + +``` + +A literal transcription of this code to Rust is totally fine, but has an annoying +performance characteristic: the `self` element is swapped over and over again +uselessly. We would *rather* have the following: + +```text +bubble_up(heap, index): + let elem = heap[index] + while index != 0 && element < heap[parent(index)]: + heap[index] = heap[parent(index)] + index = parent(index) + heap[index] = elem +``` + +This code ensures that each element is copied as little as possible (it is in +fact necessary that elem be copied twice in general). However it now exposes +some exception safety trouble! At all times, there exists two copies of one +value. If we panic in this function something will be double-dropped. +Unfortunately, we also don't have full control of the code: that comparison is +user-defined! + +Unlike Vec, the fix isn't as easy here. One option is to break the user-defined +code and the unsafe code into two separate phases: + +```text +bubble_up(heap, index): + let end_index = index; + while end_index != 0 && heap[end_index] < heap[parent(end_index)]: + end_index = parent(end_index) + + let elem = heap[index] + while index != end_index: + heap[index] = heap[parent(index)] + index = parent(index) + heap[index] = elem +``` + +If the user-defined code blows up, that's no problem anymore, because we haven't +actually touched the state of the heap yet. Once we do start messing with the +heap, we're working with only data and functions that we trust, so there's no +concern of panics. + +Perhaps you're not happy with this design. Surely, it's cheating! And we have +to do the complex heap traversal *twice*! Alright, let's bite the bullet. Let's +intermix untrusted and unsafe code *for reals*. + +If Rust had `try` and `finally` like in Java, we could do the following: + +```text +bubble_up(heap, index): + let elem = heap[index] + try: + while index != 0 && element < heap[parent(index)]: + heap[index] = heap[parent(index)] + index = parent(index) + finally: + heap[index] = elem +``` + +The basic idea is simple: if the comparison panics, we just toss the loose +element in the logically uninitialized index and bail out. Anyone who observes +the heap will see a potentially *inconsistent* heap, but at least it won't +cause any double-drops! If the algorithm terminates normally, then this +operation happens to coincide precisely with the how we finish up regardless. + +Sadly, Rust has no such construct, so we're going to need to roll our own! The +way to do this is to store the algorithm's state in a separate struct with a +destructor for the "finally" logic. Whether we panic or not, that destructor +will run and clean up after us. + +```rust +struct Hole<'a, T: 'a> { + data: &'a mut [T], + /// `elt` is always `Some` from new until drop. + elt: Option, + pos: usize, +} + +impl<'a, T> Hole<'a, T> { + fn new(data: &'a mut [T], pos: usize) -> Self { + unsafe { + let elt = ptr::read(&data[pos]); + Hole { + data: data, + elt: Some(elt), + pos: pos, + } + } + } + + fn pos(&self) -> usize { self.pos } + + fn removed(&self) -> &T { self.elt.as_ref().unwrap() } + + unsafe fn get(&self, index: usize) -> &T { &self.data[index] } + + unsafe fn move_to(&mut self, index: usize) { + let index_ptr: *const _ = &self.data[index]; + let hole_ptr = &mut self.data[self.pos]; + ptr::copy_nonoverlapping(index_ptr, hole_ptr, 1); + self.pos = index; + } +} + +impl<'a, T> Drop for Hole<'a, T> { + fn drop(&mut self) { + // fill the hole again + unsafe { + let pos = self.pos; + ptr::write(&mut self.data[pos], self.elt.take().unwrap()); + } + } +} + +impl BinaryHeap { + fn sift_up(&mut self, pos: usize) { + unsafe { + // Take out the value at `pos` and create a hole. + let mut hole = Hole::new(&mut self.data, pos); + + while hole.pos() != 0 { + let parent = parent(hole.pos()); + if hole.removed() <= hole.get(parent) { break } + hole.move_to(parent); + } + // Hole will be unconditionally filled here; panic or not! + } + } +} +``` diff --git a/poisoning.md b/poisoning.md new file mode 100644 index 0000000000000..6fb16f28e3435 --- /dev/null +++ b/poisoning.md @@ -0,0 +1,35 @@ +% Poisoning + +Although all unsafe code *must* ensure it has minimal exception safety, not all +types ensure *maximal* exception safety. Even if the type does, your code may +ascribe additional meaning to it. For instance, an integer is certainly +exception-safe, but has no semantics on its own. It's possible that code that +panics could fail to correctly update the integer, producing an inconsistent +program state. + +This is *usually* fine, because anything that witnesses an exception is about +to get destroyed. For instance, if you send a Vec to another thread and that +thread panics, it doesn't matter if the Vec is in a weird state. It will be +dropped and go away forever. However some types are especially good at smuggling +values across the panic boundary. + +These types may choose to explicitly *poison* themselves if they witness a panic. +Poisoning doesn't entail anything in particular. Generally it just means +preventing normal usage from proceeding. The most notable example of this is the +standard library's Mutex type. A Mutex will poison itself if one of its +MutexGuards (the thing it returns when a lock is obtained) is dropped during a +panic. Any future attempts to lock the Mutex will return an `Err` or panic. + +Mutex poisons not for *true* safety in the sense that Rust normally cares about. It +poisons as a safety-guard against blindly using the data that comes out of a Mutex +that has witnessed a panic while locked. The data in such a Mutex was likely in the +middle of being modified, and as such may be in an inconsistent or incomplete state. +It is important to note that one cannot violate memory safety with such a type +if it is correctly written. After all, it must be minimally exception-safe! + +However if the Mutex contained, say, a BinaryHeap that does not actually have the +heap property, it's unlikely that any code that uses it will do +what the author intended. As such, the program should not proceed normally. +Still, if you're double-plus-sure that you can do *something* with the value, +the Mutex exposes a method to get the lock anyway. It *is* safe, after all. +Just maybe nonsense. diff --git a/unwinding.md b/unwinding.md index 0526896550287..59494d8647467 100644 --- a/unwinding.md +++ b/unwinding.md @@ -2,14 +2,13 @@ Rust has a *tiered* error-handling scheme: -* If something might reasonably be absent, Option is used -* If something goes wrong and can reasonably be handled, Result is used -* If something goes wrong and cannot reasonably be handled, the thread panics -* If something catastrophic happens, the program aborts +* If something might reasonably be absent, Option is used. +* If something goes wrong and can reasonably be handled, Result is used. +* If something goes wrong and cannot reasonably be handled, the thread panics. +* If something catastrophic happens, the program aborts. Option and Result are overwhelmingly preferred in most situations, especially since they can be promoted into a panic or abort at the API user's discretion. -However, anything and everything *can* panic, and you need to be ready for this. Panics cause the thread to halt normal execution and unwind its stack, calling destructors as if every function instantly returned. @@ -27,13 +26,13 @@ Rust very poor for long-running systems! As the Rust we know today came to be, this style of programming grew out of fashion in the push for less-and-less abstraction. Light-weight tasks were -killed in the name of heavy-weight OS threads. Still, panics could only be -caught by the parent thread. This means catching a panic requires spinning up -an entire OS thread! This unfortunately stands in conflict to Rust's philosophy -of zero-cost abstractions. +killed in the name of heavy-weight OS threads. Still, on stable Rust as of 1.0 +panics can only be caught by the parent thread. This means catching a panic +requires spinning up an entire OS thread! This unfortunately stands in conflict +to Rust's philosophy of zero-cost abstractions. -In the near future there will be a stable interface for catching panics in an -arbitrary location, though we would encourage you to still only do this +There is an *unstable* API called `catch_panic` that enables catching a panic +without spawning a thread. Still, we would encourage you to only do this sparingly. In particular, Rust's current unwinding implementation is heavily optimized for the "doesn't unwind" case. If a program doesn't unwind, there should be no runtime cost for the program being *ready* to unwind. As a @@ -41,251 +40,6 @@ consequence, *actually* unwinding will be more expensive than in e.g. Java. Don't build your programs to unwind under normal circumstances. Ideally, you should only panic for programming errors or *extreme* problems. - - - -# Exception Safety - -Being ready for unwinding is often referred to as *exception safety* -in the broader programming world. In Rust, their are two levels of exception -safety that one may concern themselves with: - -* In unsafe code, we *must* be exception safe to the point of not violating - memory safety. - -* In safe code, it is *good* to be exception safe to the point of your program - doing the right thing. - -As is the case in many places in Rust, unsafe code must be ready to deal with -bad safe code, and that includes code that panics. Code that transiently creates -unsound states must be careful that a panic does not cause that state to be -used. Generally this means ensuring that only non-panicking code is run while -these states exist, or making a guard that cleans up the state in the case of -a panic. This does not necessarily mean that the state a panic witnesses is a -fully *coherent* state. We need only guarantee that it's a *safe* state. - -Most unsafe code is leaf-like, and therefore fairly easy to make exception-safe. -It controls all the code that runs, and most of that code can't panic. However -it is often the case that code that works with arrays works with temporarily -uninitialized data while repeatedly invoking caller-provided code. Such code -needs to be careful, and consider exception-safety. - - - - - -## Vec::push_all - -`Vec::push_all` is a temporary hack to get extending a Vec by a slice reliably -effecient without specialization. Here's a simple implementation: - -```rust,ignore -impl Vec { - fn push_all(&mut self, to_push: &[T]) { - self.reserve(to_push.len()); - unsafe { - // can't overflow because we just reserved this - self.set_len(self.len() + to_push.len()); - - for (i, x) in to_push.iter().enumerate() { - self.ptr().offset(i as isize).write(x.clone()); - } - } - } -} -``` - -We bypass `push` in order to avoid redundant capacity and `len` checks on the -Vec that we definitely know has capacity. The logic is totally correct, except -there's a subtle problem with our code: it's not exception-safe! `set_len`, -`offset`, and `write` are all fine, but *clone* is the panic bomb we over-looked. - -Clone is completely out of our control, and is totally free to panic. If it does, -our function will exit early with the length of the Vec set too large. If -the Vec is looked at or dropped, uninitialized memory will be read! - -The fix in this case is fairly simple. If we want to guarantee that the values -we *did* clone are dropped we can set the len *in* the loop. If we just want to -guarantee that uninitialized memory can't be observed, we can set the len *after* -the loop. - - - - - -## BinaryHeap::sift_up - -Bubbling an element up a heap is a bit more complicated than extending a Vec. -The pseudocode is as follows: - -```text -bubble_up(heap, index): - while index != 0 && heap[index] < heap[parent(index)]: - heap.swap(index, parent(index)) - index = parent(index) - -``` - -A literal transcription of this code to Rust is totally fine, but has an annoying -performance characteristic: the `self` element is swapped over and over again -uselessly. We would *rather* have the following: - -```text -bubble_up(heap, index): - let elem = heap[index] - while index != 0 && element < heap[parent(index)]: - heap[index] = heap[parent(index)] - index = parent(index) - heap[index] = elem -``` - -This code ensures that each element is copied as little as possible (it is in -fact necessary that elem be copied twice in general). However it now exposes -some exception-safety trouble! At all times, there exists two copies of one -value. If we panic in this function something will be double-dropped. -Unfortunately, we also don't have full control of the code: that comparison is -user-defined! - -Unlike Vec, the fix isn't as easy here. One option is to break the user-defined -code and the unsafe code into two separate phases: - -```text -bubble_up(heap, index): - let end_index = index; - while end_index != 0 && heap[end_index] < heap[parent(end_index)]: - end_index = parent(end_index) - - let elem = heap[index] - while index != end_index: - heap[index] = heap[parent(index)] - index = parent(index) - heap[index] = elem -``` - -If the user-defined code blows up, that's no problem anymore, because we haven't -actually touched the state of the heap yet. Once we do start messing with the -heap, we're working with only data and functions that we trust, so there's no -concern of panics. - -Perhaps you're not happy with this design. Surely, it's cheating! And we have -to do the complex heap traversal *twice*! Alright, let's bite the bullet. Let's -intermix untrusted and unsafe code *for reals*. - -If Rust had `try` and `finally` like in Java, we could do the following: - -```text -bubble_up(heap, index): - let elem = heap[index] - try: - while index != 0 && element < heap[parent(index)]: - heap[index] = heap[parent(index)] - index = parent(index) - finally: - heap[index] = elem -``` - -The basic idea is simple: if the comparison panics, we just toss the loose -element in the logically uninitialized index and bail out. Anyone who observes -the heap will see a potentially *inconsistent* heap, but at least it won't -cause any double-drops! If the algorithm terminates normally, then this -operation happens to coincide precisely with the how we finish up regardless. - -Sadly, Rust has no such construct, so we're going to need to roll our own! The -way to do this is to store the algorithm's state in a separate struct with a -destructor for the "finally" logic. Whether we panic or not, that destructor -will run and clean up after us. - -```rust -struct Hole<'a, T: 'a> { - data: &'a mut [T], - /// `elt` is always `Some` from new until drop. - elt: Option, - pos: usize, -} - -impl<'a, T> Hole<'a, T> { - fn new(data: &'a mut [T], pos: usize) -> Self { - unsafe { - let elt = ptr::read(&data[pos]); - Hole { - data: data, - elt: Some(elt), - pos: pos, - } - } - } - - fn pos(&self) -> usize { self.pos } - - fn removed(&self) -> &T { self.elt.as_ref().unwrap() } - - unsafe fn get(&self, index: usize) -> &T { &self.data[index] } - - unsafe fn move_to(&mut self, index: usize) { - let index_ptr: *const _ = &self.data[index]; - let hole_ptr = &mut self.data[self.pos]; - ptr::copy_nonoverlapping(index_ptr, hole_ptr, 1); - self.pos = index; - } -} - -impl<'a, T> Drop for Hole<'a, T> { - fn drop(&mut self) { - // fill the hole again - unsafe { - let pos = self.pos; - ptr::write(&mut self.data[pos], self.elt.take().unwrap()); - } - } -} - -impl BinaryHeap { - fn sift_up(&mut self, pos: usize) { - unsafe { - // Take out the value at `pos` and create a hole. - let mut hole = Hole::new(&mut self.data, pos); - - while hole.pos() != 0 { - let parent = parent(hole.pos()); - if hole.removed() <= hole.get(parent) { break } - hole.move_to(parent); - } - // Hole will be unconditionally filled here; panic or not! - } - } -} -``` - - - - -## Poisoning - -Although all unsafe code *must* ensure some minimal level of exception safety, -some types may choose to explicitly *poison* themselves if they witness a panic. -Poisoning doesn't entail anything in particular. Generally it just means -preventing normal usage from proceeding. The most notable example of this is the -standard library's Mutex type. A Mutex will poison itself if one of its -MutexGuards (the thing it returns when a lock is obtained) is dropped during a -panic. Any future attempts to lock the Mutex will return an `Err`. - -Mutex poisons not for *true* safety in the sense that Rust normally cares about. It -poisons as a safety-guard against blindly using the data that comes out of a Mutex -that has witnessed a panic while locked. The data in such a Mutex was likely in the -middle of being modified, and as such may be in an inconsistent or incomplete state. -It is important to note that one cannot violate memory safety with such a type -if it is correctly written. After all, it must be minimally exception safe! - -However if the Mutex contained, say, a BinaryHeap that does not actually have the -heap property, it's unlikely that any code that uses it will do -what the author intended. As such, the program should not proceed normally. -Still, if you're double-plus-sure that you can do *something* with the value, -the Err exposes a method to get the lock anyway. It *is* safe, after all. - - - -# FFI - Rust's unwinding strategy is not specified to be fundamentally compatible with any other language's unwinding. As such, unwinding into Rust from another language, or unwinding into another language from Rust is Undefined Behaviour. From d96a518316da8eb1ab4a7af1b8b34b1f5b00fd3f Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 22:36:09 -0700 Subject: [PATCH 066/104] several fixups --- other-reprs.md | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/other-reprs.md b/other-reprs.md index 068d30c5e3da5..d168dcbe360be 100644 --- a/other-reprs.md +++ b/other-reprs.md @@ -26,9 +26,26 @@ the FFI boundary. * DSTs, tuples, and tagged unions are not a concept in C and as such are never FFI safe. -* **The drop flag will still be added** +* **The [drop flag][] will still be added** -* This is equivalent to `repr(u32)` for enums (see below) +* This is equivalent to one of `repr(u\*)` (see the next section) for enums. The + chosen size is the default enum size for the target platform's C ABI. Note that + enum representation in C is undefined, and this may be incorrect when the C + code is compiled with certain flags. + + + +# repr(u8), repr(u16), repr(u32), repr(u64) + +These specify the size to make a C-like enum. If the discriminant overflows the +integer it has to fit in, it will be an error. You can manually ask Rust to +allow this by setting the overflowing element to explicitly be 0. However Rust +will not allow you to create an enum where two variants have the same discriminant. + +On non-C-like enums, this will inhibit certain optimizations like the null-pointer +optimization. + +These reprs have no affect on a struct. @@ -40,22 +57,15 @@ byte. This may improve the memory footprint, but will likely have other negative side-effects. In particular, most architectures *strongly* prefer values to be aligned. This -may mean the unaligned loads are penalized (x86), or even fault (ARM). In -particular, the compiler may have trouble with references to unaligned fields. +may mean the unaligned loads are penalized (x86), or even fault (some ARM chips). +For simple cases like directly loading or storing a packed field, the compiler +might be able to paper over alignment issues with shifts and masks. However if +you take a reference to a packed field, it's unlikely that the compiler will be +able to emit code to avoid an unaligned load. `repr(packed)` is not to be used lightly. Unless you have extreme requirements, this should not be used. This repr is a modifier on `repr(C)` and `repr(rust)`. - - - -# repr(u8), repr(u16), repr(u32), repr(u64) - -These specify the size to make a C-like enum. If the discriminant overflows the -integer it has to fit in, it will be an error. You can manually ask Rust to -allow this by setting the overflowing element to explicitly be 0. However Rust -will not allow you to create an enum where two variants. - -These reprs have no affect on a struct or non-C-like enum. \ No newline at end of file +[drop flag]: drop-flags.html From 667afb82261103abf6533b3f287b8969beee5bb3 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 22:37:03 -0700 Subject: [PATCH 067/104] remove salsh --- other-reprs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/other-reprs.md b/other-reprs.md index d168dcbe360be..829a15e6355b2 100644 --- a/other-reprs.md +++ b/other-reprs.md @@ -28,7 +28,7 @@ the FFI boundary. * **The [drop flag][] will still be added** -* This is equivalent to one of `repr(u\*)` (see the next section) for enums. The +* This is equivalent to one of `repr(u*)` (see the next section) for enums. The chosen size is the default enum size for the target platform's C ABI. Note that enum representation in C is undefined, and this may be incorrect when the C code is compiled with certain flags. From c7919f2d9835578321bf7556ad1a01fa42e8a7e8 Mon Sep 17 00:00:00 2001 From: Alexis Beingessner Date: Mon, 13 Jul 2015 23:13:56 -0700 Subject: [PATCH 068/104] remove chaff --- FiraSans-Medium.woff | Bin 89883 -> 0 bytes FiraSans-Regular.woff | Bin 91946 -> 0 bytes Heuristica-Italic.woff | Bin 119956 -> 0 bytes SourceCodePro-Regular.woff | Bin 55472 -> 0 bytes SourceCodePro-Semibold.woff | Bin 55360 -> 0 bytes SourceSerifPro-Bold.woff | Bin 48720 -> 0 bytes SourceSerifPro-Regular.woff | Bin 49960 -> 0 bytes rust.css | 407 ------------------------------------ 8 files changed, 407 deletions(-) delete mode 100644 FiraSans-Medium.woff delete mode 100644 FiraSans-Regular.woff delete mode 100644 Heuristica-Italic.woff delete mode 100644 SourceCodePro-Regular.woff delete mode 100644 SourceCodePro-Semibold.woff delete mode 100644 SourceSerifPro-Bold.woff delete mode 100644 SourceSerifPro-Regular.woff delete mode 100644 rust.css diff --git a/FiraSans-Medium.woff b/FiraSans-Medium.woff deleted file mode 100644 index 5627227744ae5b2ffb83e632cb32b237428c8962..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 89883 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%0Dk_#%Y{EcU_rFP4oA@FKf8}T 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