Add some missing sections to the types system section

Author: matthewjasper

src/SUMMARY.md

@@ -32,6 +32,8 @@
 
 - [Type system](type-system.md)
     - [Types](types.md)
+    - [Dynamically Sized Types](dynamically-sized-types.md)
+    - [Interior mutability](interior-mutability.md)
     - [Subtyping](subtyping.md)
     - [Type coercions](type-coercions.md)
 

src/dynamically-sized-types.md

@@ -0,0 +1,32 @@
+# Dynamically Sized Types
+
+Most types have a fixed size that is known at compile time and implement the
+trait [`Sized`][sized]. A type with a size that is known only at run-time is
+called a _dynamically sized type_ (_DST_) or (informally) an unsized type.
+[Slices] and [trait objects] are two examples of <abbr title="dynamically sized
+types">DSTs</abbr>. Such types can only be used in certain cases:
+
+* [Pointer types] to <abbr title="dynamically sized types">DSTs</abbr> are
+  sized but have twice the size of pointers to sized types
+    * Pointers to slices also store the number of elements of the slice.
+    * Pointers to trait objects also store a pointer to a vtable.
+* <abbr title="dynamically sized types">DSTs</abbr> can be provided as
+  type arguments when a bound of `?Sized`. By default any type parameter
+  has a `?Sized` bound.
+* Traits may be implemented for <abbr title="dynamically sized
+  types">DSTs</abbr>. Unlike type parameters`Self: ?Sized` by default in trait
+  definitions.
+* Structs may contain a <abbr title="dynamically sized type">DST</abbr> as the
+  last field, this makes the struct itself a
+  <abbr title="dynamically sized type">DST</abbr>.
+
+Notably: [variables], function parameters, [const] and [static] items must be
+`Sized`.
+
+[sized]: the-sized-trait.html
+[Slices]: #array-and-slice-types
+[trait objects]: #trait-objects
+[Pointer types]: #pointer-types
+[variables]: variables.html
+[const]: items.html#constant-items
+[static]: items.html#static-items

src/interior-mutability.md

@@ -0,0 +1,30 @@
+# Interior Mutability
+
+Sometimes a type needs be mutated while having multiple aliases, in Rust this
+is achieved using a pattern called _interior mutability_. A type has interior
+mutability if its internal state can be changed through a [shared reference] to
+it. This goes against the usual [requirement][ub] that the value pointed to by a
+shared reference is not mutated.
+
+[`std::cell::UnsafeCell<T>`] type is the only legal way in Rust to disable this
+requirement. When `UnsafeCell<T>` is immutably aliased, it is still safe to
+mutate, or obtain a mutable reference to, the `T` it contains. As with all
+other types, it is undefined behavior to have multiple `&mut UnsafeCell<T>`
+aliases.
+
+Other types with interior mutability can be created by using `UnsafeCell<T>` as
+a field. The standard library provides a variety of types that provide safe
+interior mutability APIs. For example, [`std::cell::RefCell<T>`] uses run-time
+borrow checks to ensure the usual rules around multiple references. The
+[`std::sync::atomic`] module contains types that wrap a value that is only
+accessed with atomic operations, allowing the value to be shared and mutated
+across threads.
+
+[shared reference]: types.hmtl#shared-references
+[ub]: behavior-considered-undefined.html
+[`std::mem::transmute`]: ../std/mem/fn.transmute.html
+[`std::cell::UnsafeCell<T>`]: ../std/cell/struct.UnsafeCell.html
+[`std::cell::RefCell<T>`]: ../std/cell/struct.RefCell.html
+[`std::sync::atomic`]: ../std/sync/atomic.html
+
+

src/types.md

@@ -93,8 +93,8 @@ Tuple types and values are denoted by listing the types or values of their
 elements, respectively, in a parenthesized, comma-separated list.
 
 Because tuple elements don't have a name, they can only be accessed by
-pattern-matching or by using `N` directly as a field to access the
-`N`th element.
+pattern-matching or by using `N` directly as a field to access the `N`th
+element.
 
 An example of a tuple type and its use:
 
@@ -149,7 +149,7 @@ array or slice is always bounds-checked in safe methods and operators.
 The [`Vec<T>`] standard library type provides a heap allocated resizable array
 type.
 
-[dynamically sized type]: #dynamically-sized-types
+[dynamically sized type]: dynamically-sized-types.html
 [`Vec<T>`]: ../std/vec/struct.Vec.html
 
 ## Struct types
@@ -162,13 +162,13 @@ expression](expressions.html#struct-expressions).
 
 The memory layout of a `struct` is undefined by default to allow for compiler
 optimizations like field reordering, but it can be fixed with the
-`#[repr(...)]` attribute. In either case, fields may be given in any order in
-a corresponding struct *expression*; the resulting `struct` value will always
+`#[repr(...)]` attribute. In either case, fields may be given in any order in a
+corresponding struct *expression*; the resulting `struct` value will always
 have the same memory layout.
 
 The fields of a `struct` may be qualified by [visibility
-modifiers](visibility-and-privacy.html), to allow access to data in a
-struct outside a module.
+modifiers](visibility-and-privacy.html), to allow access to data in a struct
+outside a module.
 
 A _tuple struct_ type is just like a struct type, except that the fields are
 anonymous.
@@ -202,6 +202,21 @@ named reference to an [`enum` item](items.html#enumerations).
 [^enumtype]: The `enum` type is analogous to a `data` constructor declaration in
              ML, or a *pick ADT* in Limbo.
 
+## Union types
+
+A *union type* is a nominal, heterogeneous C-like union, denoted by the name of
+a [`union` item](items.html#unions).
+
+A union contains the value of any one of its fields. Since the accessing the
+wrong field can cause unexpected or undefined behaviour, `unsafe` is required
+to read from a union field or to write to a field that doesn't implement
+[`Copy`].
+
+The memory layout of a `union` is undefined by default, but the `#[repr(...)]`
+attribute can be used to fix a layout.
+
+[`Copy`]: the-copy-trait.html
+
 ## Recursive types
 
 Nominal types &mdash; [structs](#struct-types),
@@ -240,7 +255,7 @@ copied, stored into data structs, and returned from functions.
 
 These point to memory _owned by some other value_. When a shared reference to a
 value is created it prevents direct mutation of the value. [Interior
-mutability](#interior-mutability) provides an exception for this in certain
+mutability](interior-mutability.html) provides an exception for this in certain
 circumstances. As the name suggests, any number of shared references to a value
 may exit. A shared reference type is written `&type`, or `&'a type` when you
 need to specify an explicit lifetime. Copying a reference is a "shallow"
@@ -249,6 +264,12 @@ operation: it involves only copying the pointer itself, that is, pointers are
 referencing of a [temporary value](expressions.html#temporary-lifetimes) will
 keep it alive during the scope of the reference itself.
 
+### Mutable references (`&mut`)
+
+These also point to memory owned by some other value. A mutable reference type
+is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been
+borrowed) is the only way to access the value it points to, so is not `Copy`.
+
 ### Raw pointers (`*const` and `*mut`)
 
 Raw pointers are pointers without safety or liveness guarantees. Raw pointers
@@ -262,7 +283,8 @@ foreign code, and writing performance-critical or low-level functions.
 
 When comparing pointers they are compared by their address, rather than by what
 they point to. When comparing pointers to [dynamically sized
-types](#dynamically-sized-types) they also have their addition data compared.
+types](dynamically-sized-types.html) they also have their addition data
+compared.
 
 ### Smart Pointers
 
@@ -365,9 +387,9 @@ more of the closure traits:
     moved in the body of the closure. `Fn` inherits from `FnMut`, which itself
     inherits from `FnOnce`.
 
-Closures that don't use anything from their environment ("non capturing closures")
-can be coerced to function pointers (`fn`) with the matching signature.
-To adopt the example from the section above:
+Closures that don't use anything from their environment ("non capturing
+closures") can be coerced to function pointers (`fn`) with the matching
+signature. To adopt the example from the section above:
 
 ```rust
 let add = |x, y| x + y;
@@ -382,9 +404,11 @@ x = bo(5,7);
 ## Trait objects
 
 In Rust, trait names also refer to [dynamically sized types] called _trait
-objects_. Like all DSTs, trait objects are used behind some kind of pointer:
-`&SomeTrait` or `Box<SomeTrait>`. Each instance of a pointer to a trait object
-includes:
+objects_. Like all <abbr title="dynamically sized types">DSTs</abbr>, trait
+objects are used behind some kind of pointer: `&SomeTrait` or `Box<SomeTrait>`.
+Each instance of a pointer to a trait object includes:
+
+[dynamically sized types]: dynamically-sized-types.html
 
  - a pointer to an instance of a type `T` that implements `SomeTrait`
  - a _virtual method table_, often just called a _vtable_, which contains, for
@@ -464,11 +488,11 @@ Box<Foo + 'static>
 impl Foo {}
 impl Foo + 'static {}
 
-// ...so are these as &'a T requires T: 'a
+// ...so are these, because &'a T requires T: 'a
 &'a Foo
 &'a (Foo + 'a)
 
-// ...std::cell::Ref<'a, T> also requires T: 'a, so these are also the same
+// std::cell::Ref<'a, T> also requires T: 'a, so these are the same
 std::cell::Ref<'a, Foo>
 std::cell::Ref<'a, Foo + 'a>