many many pnkfelix fixes

Author: Gankra

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<T>` can be effeciently implemented
-as a thin wrapper around `HashMap<T, ()>` 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<Key, Value>`, it is common to implement a `Set<Key>` as just a thin wrapper
+around `Map<Key, UselessJunk>`. 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<Key> = Map<Key, ()>`. 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<T, Void>`. 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<T, Void>` 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

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]

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

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,