Add more rules about when expressions diverge

rust-lang#2067 added a chapter on
divergence along with rules for some of the more subtle expressions like
`if` or `match`. This adds rules for almost all the rest of the
expressions.

Most of these are pretty straightforward propagation rules which could
be left implicit. It may seem a little excessive to have a separate rule
for each one, but I think the consistency is worth it because there are
various subtleties. This also may help us be clear about these things
when adding new expressions to the language to ensure we think about the
divergence rules.

This does not cover const expressions (const blocks, static, const,
array repeat, etc.) because I still do not yet fully know how those
should be documented (see
rust-lang#2153).

I'm not entirely excited by having the long list of rules in the
divergence chapter, mostly because of the length. However, I think it is
helpful to cross-index these kinds of things.

There are some interesting subtleties that I noticed:

- `while` loops cannot diverge. It's a little surprising to me (I would
  expect the condition to allow it to diverge). I suspect this is due to
  the desugaring to a loop expression using `break`, which does not
  diverge.
- Updated details for let-chains.
- I couldn't think of a way for a `path` expression to refer to a never
  type on stable, so I left a comment in there to update it when never
  type is stabilized. I am writing this as-if the uninhabited-static
  lint is an error and not supported.

References for the implementation:
- Place expression with never must be read: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/expr.rs#L318-L326
- `break` is never: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/expr.rs#L819-L820
- `continue` is never: https://github.com/rust-lang/rust/blob/0376d43d443cba463a0b6a6ec9140ea17d7b7130/compiler/rustc_hir_typeck/src/expr.rs#L861
- `return` is never: https://github.com/rust-lang/rust/blob/0376d43d443cba463a0b6a6ec9140ea17d7b7130/compiler/rustc_hir_typeck/src/expr.rs#L921
- `if` divergence: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/expr.rs#L1236-L1242
- `loop`: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/expr.rs#L1450-L1456
- `asm!`: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/expr.rs#L3684
- `match`: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/_match.rs#L19-L178
- block break: https://github.com/rust-lang/rust/blob/59fd4ef94daa991e6797b5aa6127e824f3067def/compiler/rustc_hir_typeck/src/fn_ctxt/checks.rs#L1167-L1171
- lazy bool: https://github.com/rust-lang/rust/blob/0376d43d443cba463a0b6a6ec9140ea17d7b7130/compiler/rustc_hir_typeck/src/op.rs#L111

Closes rust-lang#2152

Author: ehuss

dev-guide/src/rules/index.md

@@ -33,6 +33,7 @@ When assigning rules to new paragraphs or modifying rule names, use the followin
    - `intro`: The beginning paragraph of each section. It should explain the construct being defined overall.
    - `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
    - `namespace`: For items only, specifies the namespace(s) the item introduces a name in. It may also be used elsewhere when defining a namespace (e.g., `r[attribute.diagnostic.namespace]`).
+   - `diverging`: The divergence behavior of an expression. Be sure to update the Divergence chapter, too.
 6. When a rule doesn't fall under the above keywords, or for section rule IDs, name the subrule as follows:
    - If the rule names a specific Rust language construct (e.g., an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s).
    - Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".

src/divergence.md

@@ -17,17 +17,47 @@ fn example() {
 
 See the following rules for specific expression divergence behavior:
 
+- [asm.diverging.naked_asm] --- `naked_asm!`.
+- [asm.diverging.noreturn] --- `noreturn` in `asm!`.
+- [expr.arith-logic.diverging] --- Arithmetic and logic expressions.
+- [expr.array.diverging] --- Array expressions.
+- [expr.array.index.diverging] --- Index expressions.
+- [expr.as.diverging] --- `as` expressions.
+- [expr.assign.diverging] --- Assignment expressions.
+- [expr.await.diverging] --- `.await` expressions.
+- [expr.block.async.diverging] --- Async block expressions.
 - [expr.block.diverging] --- Block expressions.
+- [expr.bool-logic.diverging] --- Lazy boolean expressions.
+- [expr.borrow.diverging] --- Borrow expressions.
+- [expr.call.diverging] --- Call expressions.
+- [expr.closure.diverging] --- Closure expressions.
+- [expr.cmp.diverging] --- Comparison expressions.
+- [expr.compound-assign.diverging] --- Compound assignment expressions.
+- [expr.deref.diverging] --- Dereference expressions.
+- [expr.field.diverging] --- Field expressions.
 - [expr.if.diverging] --- `if` expressions.
+- [expr.literal.diverging] --- Literal expressions.
 - [expr.loop.block-labels.type] --- Labeled block expressions with `break`.
 - [expr.loop.break-value.diverging] --- `loop` expressions with `break`.
 - [expr.loop.break.diverging] --- `break` expressions.
 - [expr.loop.continue.diverging] --- `continue` expressions.
+- [expr.loop.for.diverging] --- `for` expressions.
 - [expr.loop.infinite.diverging] --- Infinite `loop` expressions.
+- [expr.loop.while.diverging] --- `while` expressions.
 - [expr.match.diverging] --- `match` expressions.
 - [expr.match.empty] --- Empty `match` expressions.
+- [expr.method.diverging] --- Method call expressions.
+- [expr.negate.diverging] --- Negation expressions.
+- [expr.paren.diverging] --- Parenthesized expressions.
+- [expr.path.diverging] --- Path expressions.
+- [expr.placeholder.diverging] --- Underscore expressions.
+- [expr.range.diverging] --- Range expressions.
 - [expr.return.diverging] --- `return` expressions.
-- [type.never.constraint] --- Function calls returning `!`.
+- [expr.struct.diverging] --- Struct expressions.
+- [expr.try.diverging] --- Try propagation expressions.
+- [expr.tuple-index.diverging] --- Tuple indexing expressions.
+- [expr.tuple.diverging] --- Tuple expressions.
+- [statement.let.diverging] --- `let` statements.
 
 > [!NOTE]
 > The [`panic!`] macro and related panic-generating macros like [`unreachable!`] also have the type [`!`] and are diverging.

src/expressions/array-expr.md

@@ -72,6 +72,9 @@ const EMPTY: Vec<i32> = Vec::new();
 [EMPTY; 2];
 ```
 
+r[expr.array.diverging]
+An array expression [diverges] if any of its operands diverges.
+
 r[expr.array.index]
 ## Array and slice indexing expressions
 
@@ -113,6 +116,35 @@ arr[10];                  // warning: index out of bounds
 r[expr.array.index.trait-impl]
 The array index expression can be implemented for types other than arrays and slices by implementing the [Index] and [IndexMut] traits.
 
+r[expr.array.index.diverging]
+An index expression [diverges] if either of its operands diverges, or if the type of the indexed element is the [never type] and the value is guaranteed to be read.
+
+> [!EXAMPLE]
+> ```rust
+> fn phantom_place<F: FnOnce() -> T, T>() -> [T; 1] { loop {} }
+>
+> fn diverging_place_read() -> ! {
+>     // Create an array with the never type.
+>     let x /* : [!; 1] */ = phantom_place::<fn() -> !, _>();
+>     // A read of a place expression produces a diverging block.
+>     x[0];
+> }
+> ```
+>
+> The following example contrasts with the above because it does not perform a read. This means it does not diverge, causing a compile error.
+>
+> ```rust,compile_fail
+> # fn phantom_place<F: FnOnce() -> T, T>() -> [T; 1] { loop {} }
+> #
+> fn diverging_place_no_read() -> ! {
+>     // Create an array with the never type.
+>     let x /* : [!; 1] */ = phantom_place::<fn() -> !, _>();
+>     // This does not constitute a read.
+>     let _ = x[0];
+>     // ERROR: Expected type !, found ()
+> }
+> ```
+
 [`Copy`]: ../special-types-and-traits.md#copy
 [IndexMut]: std::ops::IndexMut
 [Index]: std::ops::Index
@@ -121,9 +153,11 @@ The array index expression can be implemented for types other than arrays and sl
 [const block expression]: expr.block.const
 [constant expression]: ../const_eval.md#constant-expressions
 [constant item]: ../items/constant-items.md
+[diverges]: divergence
 [inferred const]: items.generics.const.inferred
 [literal]: ../tokens.md#literals
 [memory location]: ../expressions.md#place-expressions-and-value-expressions
+[never type]: type.never
 [panic]: ../panic.md
 [path]: path-expr.md
 [slice]: ../types/slice.md

src/expressions/await-expr.md

@@ -29,6 +29,9 @@ r[expr.await.edition2018]
 > [!EDITION-2018]
 > Await expressions are only available beginning with Rust 2018.
 
+r[expr.await.diverging]
+An await expression [diverges] if the future's output type is the [never type].
+
 r[expr.await.task]
 ## Task context
 
@@ -63,6 +66,8 @@ where the `yield` pseudo-code returns `Poll::Pending` and, when re-invoked, resu
 [`poll::Pending`]: std::task::Poll::Pending
 [`poll::Ready`]: std::task::Poll::Ready
 [async context]: ../expressions/block-expr.md#async-context
+[diverges]: divergence
 [future]: std::future::Future
+[never type]: type.never
 [`IntoFuture`]: std::future::IntoFuture
 [`IntoFuture::into_future`]: std::future::IntoFuture::into_future

src/expressions/block-expr.md

@@ -191,6 +191,9 @@ The actual data format for this type is unspecified.
 > [!NOTE]
 > The future type that rustc generates is roughly equivalent to an enum with one variant per `await` point, where each variant stores the data needed to resume from its corresponding point.
 
+r[expr.block.async.diverging]
+An async block expression does not itself [diverge], but evaluating the future (such as through `await`) diverges if the output type is the [never type].
+
 r[expr.block.async.edition2018]
 > [!EDITION-2018]
 > Async blocks are only available beginning with Rust 2018.
@@ -352,6 +355,7 @@ fn is_unix_platform() -> bool {
 [call expressions]: call-expr.md
 [capture modes]: ../types/closure.md#capture-modes
 [constant items]: ../items/constant-items.md
+[diverge]: divergence
 [diverges]: expr.block.diverging
 [final operand]: expr.block.inner-attributes
 [free item]: ../glossary.md#free-item

src/expressions/call-expr.md

@@ -32,6 +32,9 @@ let three: i32 = add(1i32, 2i32);
 let name: &'static str = (|| "Rust")();
 ```
 
+r[expr.call.diverging]
+A call expression [diverges] if any of its operands diverges, or if the return type of the function is the [never type].
+
 r[expr.call.desugar]
 ## Disambiguating function calls
 
@@ -103,5 +106,7 @@ Refer to [RFC 132] for further details and motivations.
 [`default()`]: std::default::Default::default
 [`size_of()`]: std::mem::size_of
 [automatically dereferenced]: field-expr.md#automatic-dereferencing
+[diverges]: divergence
 [fully-qualified syntax]: ../paths.md#qualified-paths
+[never type]: type.never
 [non-function types]: ../types/function-item.md

src/expressions/closure-expr.md

@@ -31,6 +31,9 @@ A closure expression denotes a function that maps a list of parameters onto the
 r[expr.closure.unique-type]
 Each closure expression has a unique, anonymous type.
 
+r[expr.closure.diverging]
+A closure expression itself does not [diverge]. However, calling the closure diverges if the return type is the [never type].
+
 r[expr.closure.captures]
 Significantly, closure expressions _capture their environment_, which regular [function definitions] do not.
 
@@ -105,6 +108,8 @@ Attributes on closure parameters follow the same rules and restrictions as [regu
 [block]: block-expr.md
 [call traits and coercions]: ../types/closure.md#call-traits-and-coercions
 [closure type]: ../types/closure.md
+[diverge]: divergence
 [function definitions]: ../items/functions.md
+[never type]: type.never
 [patterns]: ../patterns.md
 [regular function parameters]: ../items/functions.md#attributes-on-function-parameters

src/expressions/field-expr.md

@@ -42,6 +42,43 @@ foo().x;
 (mystruct.function_field)() // Call expression containing a field expression
 ```
 
+r[expr.field.diverging]
+A field expression [diverges] if its expression operand diverges or if the type of the field is the [never type] and the value is guaranteed to be read.
+
+> [!EXAMPLE]
+> ```rust
+> struct S<T> {
+>     f: T
+> }
+>
+> fn phantom_place<F: FnOnce() -> T, T>() -> S<T> { loop {} }
+>
+> fn diverging_place_read() -> ! {
+>     // Create a struct with a field with the never type.
+>     let x /* : S<!> */ = phantom_place::<fn() -> !, _>();
+>     // A read of a place expression produces a diverging block.
+>     x.f;
+> }
+> ```
+>
+> The following example contrasts with the above because it does not perform a read. This means it does not diverge, causing a compile error.
+>
+> ```rust,compile_fail
+> # struct S<T> {
+> #     f: T
+> # }
+> #
+> # fn phantom_place<F: FnOnce() -> T, T>() -> S<T> { loop {} }
+> #
+> fn diverging_place_no_read() -> ! {
+>     // Create a struct with a field with the never type.
+>     let x /* : S<!> */ = phantom_place::<fn() -> !, _>();
+>     // This does not constitute a read.
+>     let _ = x.f;
+>     // ERROR: Expected type !, found ()
+> }
+> ```
+
 r[expr.field.autoref-deref]
 ## Automatic dereferencing
 
@@ -71,8 +108,10 @@ let d: String = x.f3;           // Move out of x.f3
 [`drop`]: ../special-types-and-traits.md#drop
 [identifier]: ../identifiers.md
 [call expression]: call-expr.md
+[diverges]: divergence
 [method call expression]: method-call-expr.md
 [mutable]: ../expressions.md#mutability
+[never type]: type.never
 [parenthesized expression]: grouped-expr.md
 [place expression]: ../expressions.md#place-expressions-and-value-expressions
 [struct]: ../items/structs.md

src/expressions/grouped-expr.md

@@ -44,4 +44,8 @@ assert_eq!( a.f (), "The method f");
 assert_eq!((a.f)(), "The field f");
 ```
 
+r[expr.paren.diverging]
+A parenthesized expression [diverges] if its operand diverges.
+
+[diverges]: divergence
 [place]: ../expressions.md#place-expressions-and-value-expressions

src/expressions/if-expr.md

@@ -73,6 +73,8 @@ assert_eq!(y, "Bigger");
 r[expr.if.diverging]
 An `if` expression [diverges] if either the condition expression diverges or if all arms diverge.
 
+The condition expression diverges if the leftmost condition in the `&&` chain diverges, where `let` patterns are considered to diverge if the scrutinee diverges.
+
 ```rust,no_run
 fn diverging_condition() -> ! {
     // Diverges because the condition expression diverges