Write chapter on divergence

Author: jackh726

src/SUMMARY.md

@@ -97,6 +97,7 @@
     - [Subtyping and variance](subtyping.md)
     - [Trait and lifetime bounds](trait-bounds.md)
     - [Type coercions](type-coercions.md)
+    - [Divergence](divergence.md)
     - [Destructors](destructors.md)
     - [Lifetime elision](lifetime-elision.md)
 

src/divergence.md

@@ -0,0 +1,52 @@
+r[divergence]
+# Divergence
+
+r[divergence.intro]
+Divergence is the state where a particular section of code could never be encountered at runtime. Importantly, while there are certain language constructs that immediately produce a _diverging expression_ of the type [`!`](./types/never.md), divergence can also propogate to the surrounding block.
+
+Any expression of type [`!`](./types/never.md) is a _diverging expression_, but there are also diverging expressions which are not of type `!` (e.g. `Some(panic!())`).
+
+r[divergence.diverging-expressions]
+## Producing diverging expressions
+
+r[divergence.diverging-expressions.unconditional]
+The following language constructs unconditonally produce a _diverging expression_ of the type [`!`](./types/never.md):
+
+* [A call to a function returning `!`.](./types/never.md#r-type.never.constraint)
+* [A `loop` expression with no corresponding break.](./expressions/loop-expr.md#r-expr.loop.infinite.diverging)
+* [A `break` expression](./expressions/loop-expr.md#r-expr.loop.break.type)
+* [A `continue` expression](./expressions/loop-expr.md#r-expr.loop.continue.type)
+* [A `return` expression](./expressions/return-expr.md#r-expr.return.type)
+* [A `match` expression with no arms](./expressions/match-expr.md#r-expr.match.type.diverging.empty)
+* [A `block` expression that it itself is diverging.](../expressions/block-expr.md#r-expr.block.type.diverging)
+
+r[divergence.diverging-expressions.conditional]
+In a control flow expression, if all arms diverge, then the entire expression also diverges.
+
+r[divergence.fallback]
+## Fallback
+If a type to be inferred is only unified with diverging expressions, then that type will be inferred to be `!`.
+
+The following fails to compile because `!` does not implement `Debug`:
+```rust,compile_fail,E0277
+fn foo() -> i32 { 22 }
+match foo() {
+    4 => Default::default(),
+    _ => return,
+};
+```
+
+> [!EDITION-2024]
+> Before the 2024 edition, the type was inferred to instead be `()`.
+
+Importantly, type unification may happen *structurally*, so the fallback `!` may be part of a larger type. The following compiles:
+```rust
+fn foo() -> i32 { 22 }
+// This has the type `Option<!>`, not `!`
+match foo() {
+    4 => Default::default(),
+    _ => Some(return),
+};
+```
+
+<!-- TODO: This last point should likely should be moved to a more general "type inference" section discussing generalization + unification. -->

src/expressions/block-expr.md

@@ -44,7 +44,7 @@ r[expr.block.result]
 Then the final operand is executed, if given.
 
 r[expr.block.type]
-The type of a block is the type of the final operand, or `()` if the final operand is omitted.
+Typically, the type of a block is the type of the final operand, or `()` if the final operand is omitted.
 
 ```rust
 # fn fn_call() {}
@@ -60,8 +60,8 @@ let five: i32 = {
 assert_eq!(5, five);
 ```
 
-> [!NOTE]
-> As a control flow expression, if a block expression is the outer expression of an expression statement, the expected type is `()` unless it is followed immediately by a semicolon.
+r[expr.block.type.diverging]
+However, if there are any values unconditionally created within a block that are [diverging](../divergence.md), then the block itself is considered diverging.
 
 r[expr.block.value]
 Blocks are always [value expressions] and evaluate the last operand in value expression context.

src/expressions/loop-expr.md

@@ -308,6 +308,9 @@ Example:
 r[expr.loop.break.value]
 A `break` expression is only permitted in the body of a loop, and has one of the forms `break`, `break 'label` or ([see below](#break-and-loop-values)) `break EXPR` or `break 'label EXPR`.
 
+r[expr.loop.break.type]
+A `break` expression itself has a type of [`!`](../types/never.md).
+
 r[expr.loop.block-labels]
 ## Labelled block expressions
 
@@ -367,6 +370,9 @@ Like `break`, `continue` is normally associated with the innermost enclosing loo
 r[expr.loop.continue.in-loop-only]
 A `continue` expression is only permitted in the body of a loop.
 
+r[expr.loop.continue.type]
+A `continue` expression itself has a type of [`!`](../types/never.md).
+
 r[expr.loop.break-value]
 ## `break` and loop values
 

src/expressions/match-expr.md

@@ -96,6 +96,28 @@ Every binding in each `|` separated pattern must appear in all of the patterns i
 r[expr.match.binding-restriction]
 Every binding of the same name must have the same type, and have the same binding mode.
 
+r[expr.match.type]
+The type of the overall `match` expression is the least upper bound of the individual match arms.
+
+r[expr.match.type.diverging.empty]
+If there are no match arms, then the `match` expression is diverging and the type is [`!`](../types/never.md).
+
+r[expr.match.type.diverging.conditional]
+If either the scrutinee expression or all of the match arms diverge, then the entire `match` expression also diverges.
+
+> [!NOTE]
+> If even the entire `match` expression diverges, its type may not be [`!`](../types/never.md).
+>
+>```rust,compile_fail,E0004
+>    let a = match true {
+>        true => Some(panic!()),
+>        false => None,
+>    };
+>    // Fails to compile because `a` has the type `Option<!>`
+>    // (or, `Option<()>` in edition 2021 and below)
+>    match a {}
+>```
+
 r[expr.match.guard]
 ## Match guards
 

src/expressions/return-expr.md

@@ -22,3 +22,6 @@ fn max(a: i32, b: i32) -> i32 {
     return b;
 }
 ```
+
+r[expr.return.type]
+A `return` expression itself has a type of [`!`](../types/never.md).