document Closure capture precision by tshepang · Pull Request #698 · rust-lang/fls

tshepang · 2026-04-20T15:05:46Z

This captures some gaps FLS has compared to Reference, and the content is adjusted from Closure capture precision section.

Co-authored-by: Ana Hobden <operator@hoverbear.org>

kirtchev-adacore

This is it for now. I will have to revisit the remaining rules once the "place" business has been cleared up. I think we can find better wording/grouping of the remaining rules, as they feel somewhat randomly sprinkled.

View changes since this review

kirtchev-adacore · 2026-04-21T08:01:12Z

+The closure :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:
+
+- :dp:`fls_4TESOxGpEY2h`
+  When a :t:`capture path` and one of the ancestors of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures, using the strict weak ordering: :t:`immutable borrow` < :t:`unique immutable borrow` < :t:`mutable borrow` < :t:`move <by move>`.


It is unclear what an "ancestor" is. Be careful when using the term "path", because we also have these paths. What the Reference describes is already documented in 6.22:12 The capture mode ....

I would rephrase the paragraph as follows (note that it is part of a list!):

When a :t:capture path and an ancestor :t:capture path and both :t:captured, the ancestor :t:capture path is :t:captured with the highest :t:capture mode among the two :t:[capture path]s.

Note that I intentionally dropped "by a closure" because a "capturing expression" is either an async block expression or a closure expression, and I suspect that these rules do apply when the context is an async block expression.

I also dropped the ordering because it is already documented by "capture mode". On a side note, perhaps 6.22:14 should be changed to "1. By immutable reference capture. (lowest precedence)" and 6:22:17 to "4. By value capture. (highest precedence)", or just use a small table similar to expression precedence.

kirtchev-adacore · 2026-04-21T08:03:56Z

+  The :t:`capture path` is truncated at the rightmost :t:`dereference` in the capture path if the dereference is applied to a :t:`shared reference`.
+
+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.


The Reference is unclear what "place" refers to - is it a "place projection", a "place expression", or a "place". I suspect the former, but this needs confirmation. Once that is cleared up, there are options to refactor some of the rules below.

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

…tions

tshepang · 2026-04-21T13:37:06Z

all addressed but #698 (comment)

kirtchev-adacore

I will probably need to read Capture precision to ensure that no rules have been omitted.

View changes since this review

kirtchev-adacore · 2026-04-22T07:51:35Z

+A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`.
+
+:dp:`fls_TbfUxVf8PKPs`
+A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:


Suggested change

A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:

A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, as follows:

The FLS avoids using the term "rules", as everything pretty much is a rule.

Note that there is no need to mention truncation here because there is a dedicated rule further below.

Separate completeness point on this section: it still seems to need the Reference's Box vs other Deref exception.

Precise capture through (*b).field is special-cased for Box; other Deref types like Rc capture the dereference base instead.

Could this section add a short rule or note making that distinction explicit? Otherwise the current summary overstates capture precision through dereference projections.

Support:

Reference type.closure.capture.precision.box-deref

Reference type.closure.capture.precision.box-non-move.not-moved

Reference type.closure.capture.precision.box-non-move.moved

Reference type.closure.capture.precision.box-move.read

FLS does not talk about Box, so I decided to omit it... what think you about this @kirtchev-adacore

When the FLS was first written, only the alloc and core libraries were in scope. This was intentional, as alloc and core are OS-agnostic, and are very tightly coupled with the language semantics. std is another story.

We can either keep it the same way but start writing down somewhere which std-related items were not included in the FLS (in case we want to include them later), or start introducing std items into the FLS.

I think this needs a higher level discussion.

kirtchev-adacore · 2026-04-22T07:52:27Z

+A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:
+
+- :dp:`fls_4TESOxGpEY2h`
+  When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`.


Suggested change

When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`.

- When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is :t:`captured` with the highest :t:`capture mode` among the two :t:`[capture path]s`.

This and the following rules should be list items.

The shared-prefix rule also seems to need the Reference's recursive-propagation note.

A deeper descendant can strengthen an intermediate ancestor, and that stronger mode may then need to propagate again to a more distant ancestor.

Could a short note be added here saying this rule may need to be applied recursively?

Support:

Reference type.closure.capture.precision.shared-prefix

was thinking an ancestor should cover that, since ancestor can mean parent, grand parent, great grand parent, and so on... unless you don't think that is strong enough

This and the following rules should be list items.

it already is... see the line prior

kirtchev-adacore · 2026-04-22T07:52:55Z

+  When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`.
+
+- :dp:`fls_eNkZWskzznW6`
+  The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.


Suggested change

The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.

- The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.

List item.

#698 (comment)

kirtchev-adacore · 2026-04-22T09:11:46Z

+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.
+
+:dp:`fls_gujpU7p5n9Zx`
+A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums.
+
+:dp:`fls_t8tFLUg8O83Q`
+A :t:`place` is not captured by being matched against a :t:`rest pattern`.
+
+:dp:`fls_RaONmCLH2KGM`
+The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing <index expression>`, or :t:`slicing <slice>`.
+
+:dp:`fls_Vt9C9mKxHOwo`
+A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.
+
+:dp:`fls_Fs12dmznjsMf`
+Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.
+
+:dp:`fls_7EXHdE2eOVek`
+Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.
+
+:dp:`fls_iLH8X2U4ADHb`
+Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`.
+
+:dp:`fls_HMJUXHrvOmPl`
+Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`.
+
+:dp:`fls_Gj1znNpthHY6`
+Matching an array against a slice pattern does not capture the :t:`place`.
+
+:dp:`fls_IFyJvb6mlFU4`
+Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.
+
+:dp:`fls_7NEEJgKSpQQ8`
+Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.
+
+:dp:`fls_kYFd3p06pWWV`
+Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself.
+
+:dp:`fls_fATMTNUOHsfb`
+Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct.
+
+:dp:`fls_fITor3jpmgrl`
+Taking the address of an unaligned :t:`field` captures the entire struct.


I made significant reorderings and rewording of some of the paragraphs.

Suggested change

:dp:`fls_v8IFXHJnXhez`

A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.

:dp:`fls_gujpU7p5n9Zx`

A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums.

:dp:`fls_t8tFLUg8O83Q`

A :t:`place` is not captured by being matched against a :t:`rest pattern`.

:dp:`fls_RaONmCLH2KGM`

The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing <index expression>`, or :t:`slicing <slice>`.

:dp:`fls_Vt9C9mKxHOwo`

A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.

:dp:`fls_Fs12dmznjsMf`

Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.

:dp:`fls_7EXHdE2eOVek`

Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.

:dp:`fls_iLH8X2U4ADHb`

Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`.

:dp:`fls_HMJUXHrvOmPl`

Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`.

:dp:`fls_Gj1znNpthHY6`

Matching an array against a slice pattern does not capture the :t:`place`.

:dp:`fls_IFyJvb6mlFU4`

Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.

:dp:`fls_7NEEJgKSpQQ8`

Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.

:dp:`fls_kYFd3p06pWWV`

Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself.

:dp:`fls_fATMTNUOHsfb`

Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct.

:dp:`fls_fITor3jpmgrl`

Taking the address of an unaligned :t:`field` captures the entire struct.

:dp:`fls_Vt9C9mKxHOwo`

A :t:`place` is :t:`captured` by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.

:dp:`fls_v8IFXHJnXhez`

A :t:`place` is not :t:`captured` when an :t:`underscore expression` is used to bind it.

:dp:`fls_gujpU7p5n9Zx`

A :t:`place` is not :t:`captured` by destructuring :t:`[struct]s`, :t:`[tuple]s`, and :t:`[enum]s` with a single :t:`enum variant`.

:dp:`fls_t8tFLUg8O83Q`

A :t:`place` is not :t:`captured` by being matched against a :t:`rest pattern`.

:dp:`fls_RaONmCLH2KGM`

An :t:`array` or :t:`slice` is :t:`captured` whole.

:dp:`fls_Fs12dmznjsMf`

Matching against an :t:`enum variant` of an :t:`enum` with more than one :t:`[enum variant]s` :t:`captures` the :t:`place` by :t:`immutable borrow`.

:dp:`fls_7EXHdE2eOVek`

Matching against an :t:`enum variant` of an :t:`enum` with one :t:`enum variant` does not :t:`capture` the :t:`place`, unless it is subject to :t:`attribute` ``non_exhaustive``, in which case the :t:`place` is captured by :t:`immutable borrow`.

:dp:`fls_iLH8X2U4ADHb`

Matching against a :t:`range pattern` :t:`captures` the :t:`place` by :t:`immutable borrow`.

:dp:`fls_HMJUXHrvOmPl`

Matching a :t:`slice` against a :t:`slice pattern`, other than one with only a single :t:`rest pattern`, :t:`captures` the :t:`slice` by :t:`immutable borrow`.

:dp:`fls_Gj1znNpthHY6`

Matching an :t:`array` against a :t:`slice pattern` does not :t:`capture` the :t:`place`.

:dp:`fls_IFyJvb6mlFU4`

A :t:`closure expression` subject to keyword ``move`` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.

:dp:`fls_7NEEJgKSpQQ8`

A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.

:dp:`fls_kYFd3p06pWWV`

A :t:`closure expression` :t:`captures` the prefix of a :t:`capture path` of a :t:`union` that runs up to the :t:`union` itself.

:dp:`fls_fATMTNUOHsfb`

A :t:`closure expression` :t:`captures` the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a :t:`struct` that uses the :t:`attribute` :c:`repr` with modifier ``packed``, in unaligned :t:`[field]s` in a :t:`struct`.

:dp:`fls_fITor3jpmgrl`

Taking the address of an unaligned :t:`field` captures the entire struct.

Several rules in this block still seem too strong relative to the Reference.

_ here should use the FLS term underscore pattern, not underscore expression, and _ does not introduce a binding.

The destructuring / .. / array-vs-slice rules should say does not by itself read or capture. That qualifier matters because subpatterns can still capture subplaces; e.g. let (x0, ..) = x; still captures x.0.

Could this subsection be adjusted along those lines?

Support:

FLS glossary underscore expression / underscore pattern in src/glossary.rst:4799-4811

Reference type.closure.capture.precision.wildcard.reads

Reference type.closure.capture.precision.wildcard.destructuring

Reference type.closure.capture.precision.wildcard.fields

Reference type.closure.capture.precision.slice-patterns.arrays

rust-lang/rust#138961

Separate point on the Matching a slice against a slice pattern... rule in this block: the current summary seems to compress away an important Reference detail.

Upstream treats this as a read of the slice length, but the captured place is the slice pointee rather than the wide-pointer place.

That distinction matters for cases like &mut [T] and &mut &'l [u8], where the effective capture is *x / **x, not x / *x.

Could that pointee-vs-wide-pointer behavior be made explicit here, or backed with a brief note/example mirroring the Reference?

Support:

Reference type.closure.capture.precision.slice-patterns.slices

Make closure capturing have consistent and correct behaviour around patterns rust#138961

Document how closure capturing interacts with discriminant reads reference#1837

Separate point on the repr(packed) rule in this block: this still seems narrower than the Reference.

Upstream truncates at the first field access into any repr(packed) struct, and explicitly says this includes fields that are currently aligned as well, for future-compatibility reasons.

Could this sentence be widened accordingly instead of limiting it to unaligned fields?

Support:

Reference type.closure.capture.precision.unaligned

PLeVasseur

Thanks for pulling this material into 6.22. The remaining comments are mainly about semantic completeness and alignment with the Rust Reference so the new section lands as dependable spec text.

View changes since this review

PLeVasseur · 2026-04-22T17:55:09Z

+A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`.
+
+:dp:`fls_rdDT7jsaOMbs`


Two semantic gaps still seem unresolved here.

place projection still seems narrower than the Reference because it omits automatic dereferences. Upstream says dereference (and automatic dereferences), and that matters because these rules operate on the projected place, not only explicit * syntax.

This subsection should also say how capture path relates to the existing capture target / capturing environment model above. Earlier in 6.22, a capture target is only a variable or a field of a variable; here, capture paths now include dereferences, indexing, raw-pointer truncation, union truncation, and packed-struct truncation, so it is hard to tell whether capture path refines that model or replaces it for this subsection.

Could this subsection tighten both definitions together, perhaps by widening place projection and adding a short bridge sentence about how capture path fits the model above?

Support:

Reference type.closure.capture.precision.place-projection

Reference type.closure.capture.precision

src/expressions.rst:5103-5184

src/glossary.rst:768-785

PLeVasseur · 2026-04-22T17:55:10Z

 - `Const blocks are no longer evaluated to determine if expressions involving fallible operations can implicitly be constant-promoted <https://github.com/rust-lang/rust/pull/150557>`_
 - `Make operational semantics of pattern matching independent of crate and module <https://github.com/rust-lang/rust/pull/150681>`_

+  Changed paragraphs:


The paragraph-ID list itself looks fine, but this changelog attribution still seems too broad.

The changed capture-mode paragraphs fit rust-lang/rust#150681, but the new capture-precision block spans multiple sources: some items align with the later pattern/discriminant work in rust-lang/rust#138961 and rust-lang/reference#1837, while others are pre-existing Reference behavior now being documented here.

Could this entry be split, or reworded so #150681 is not presented as introducing the whole block? The note that these paragraphs mostly document behavior that existed before this release already points in that direction.

Support:

Make closure capturing have consistent and correct behaviour around patterns rust#138961

Document how closure capturing interacts with discriminant reads reference#1837

Make operational semantics of pattern matching independent of crate and module rust#150681

PLeVasseur · 2026-04-22T17:55:11Z

+A :dt:`capture path` is a sequence starting with a :t:`variable` from the :t:`capturing environment` followed by zero or more :t:`[place projection]s` from that :t:`variable`.
+
+:dp:`fls_TbfUxVf8PKPs`
+A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:


Separate completeness point on this section: it still seems to need the Reference's Box vs other Deref exception.

Precise capture through (*b).field is special-cased for Box; other Deref types like Rc capture the dereference base instead.

Could this section add a short rule or note making that distinction explicit? Otherwise the current summary overstates capture precision through dereference projections.

Support:

Reference type.closure.capture.precision.box-deref

Reference type.closure.capture.precision.box-non-move.not-moved

Reference type.closure.capture.precision.box-non-move.moved

Reference type.closure.capture.precision.box-move.read

PLeVasseur · 2026-04-22T17:55:12Z

+A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:
+
+- :dp:`fls_4TESOxGpEY2h`
+  When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`.


The shared-prefix rule also seems to need the Reference's recursive-propagation note.

A deeper descendant can strengthen an intermediate ancestor, and that stronger mode may then need to propagate again to a more distant ancestor.

Could a short note be added here saying this rule may need to be applied recursively?

Support:

Reference type.closure.capture.precision.shared-prefix

PLeVasseur · 2026-04-22T17:55:13Z

+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.
+
+:dp:`fls_gujpU7p5n9Zx`
+A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums.
+
+:dp:`fls_t8tFLUg8O83Q`
+A :t:`place` is not captured by being matched against a :t:`rest pattern`.
+
+:dp:`fls_RaONmCLH2KGM`
+The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing <index expression>`, or :t:`slicing <slice>`.
+
+:dp:`fls_Vt9C9mKxHOwo`
+A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.
+
+:dp:`fls_Fs12dmznjsMf`
+Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.
+
+:dp:`fls_7EXHdE2eOVek`
+Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.
+
+:dp:`fls_iLH8X2U4ADHb`
+Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`.
+
+:dp:`fls_HMJUXHrvOmPl`
+Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`.
+
+:dp:`fls_Gj1znNpthHY6`
+Matching an array against a slice pattern does not capture the :t:`place`.
+
+:dp:`fls_IFyJvb6mlFU4`
+Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.
+
+:dp:`fls_7NEEJgKSpQQ8`
+Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.
+
+:dp:`fls_kYFd3p06pWWV`
+Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself.
+
+:dp:`fls_fATMTNUOHsfb`
+Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct.
+
+:dp:`fls_fITor3jpmgrl`
+Taking the address of an unaligned :t:`field` captures the entire struct.


Several rules in this block still seem too strong relative to the Reference.

_ here should use the FLS term underscore pattern, not underscore expression, and _ does not introduce a binding.

The destructuring / .. / array-vs-slice rules should say does not by itself read or capture. That qualifier matters because subpatterns can still capture subplaces; e.g. let (x0, ..) = x; still captures x.0.

Could this subsection be adjusted along those lines?

Support:

FLS glossary underscore expression / underscore pattern in src/glossary.rst:4799-4811

Reference type.closure.capture.precision.wildcard.reads

Reference type.closure.capture.precision.wildcard.destructuring

Reference type.closure.capture.precision.wildcard.fields

Reference type.closure.capture.precision.slice-patterns.arrays

rust-lang/rust#138961

PLeVasseur · 2026-04-22T17:55:14Z

+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.
+
+:dp:`fls_gujpU7p5n9Zx`
+A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums.
+
+:dp:`fls_t8tFLUg8O83Q`
+A :t:`place` is not captured by being matched against a :t:`rest pattern`.
+
+:dp:`fls_RaONmCLH2KGM`
+The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing <index expression>`, or :t:`slicing <slice>`.
+
+:dp:`fls_Vt9C9mKxHOwo`
+A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.
+
+:dp:`fls_Fs12dmznjsMf`
+Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.
+
+:dp:`fls_7EXHdE2eOVek`
+Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.
+
+:dp:`fls_iLH8X2U4ADHb`
+Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`.
+
+:dp:`fls_HMJUXHrvOmPl`
+Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`.
+
+:dp:`fls_Gj1znNpthHY6`
+Matching an array against a slice pattern does not capture the :t:`place`.
+
+:dp:`fls_IFyJvb6mlFU4`
+Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.
+
+:dp:`fls_7NEEJgKSpQQ8`
+Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.
+
+:dp:`fls_kYFd3p06pWWV`
+Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself.
+
+:dp:`fls_fATMTNUOHsfb`
+Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct.
+
+:dp:`fls_fITor3jpmgrl`
+Taking the address of an unaligned :t:`field` captures the entire struct.


Separate point on the Matching a slice against a slice pattern... rule in this block: the current summary seems to compress away an important Reference detail.

Upstream treats this as a read of the slice length, but the captured place is the slice pointee rather than the wide-pointer place.

That distinction matters for cases like &mut [T] and &mut &'l [u8], where the effective capture is *x / **x, not x / *x.

Could that pointee-vs-wide-pointer behavior be made explicit here, or backed with a brief note/example mirroring the Reference?

Support:

Reference type.closure.capture.precision.slice-patterns.slices

Make closure capturing have consistent and correct behaviour around patterns rust#138961

Document how closure capturing interacts with discriminant reads reference#1837

PLeVasseur · 2026-04-22T17:55:15Z

+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.
+
+:dp:`fls_gujpU7p5n9Zx`
+A :t:`place` is not captured by destructuring tuples, structs, and single-variant enums.
+
+:dp:`fls_t8tFLUg8O83Q`
+A :t:`place` is not captured by being matched against a :t:`rest pattern`.
+
+:dp:`fls_RaONmCLH2KGM`
+The entire :t:`slice` or :t:`array` is always captured even if used with :t:`underscore expression`, :t:`indexing <index expression>`, or :t:`slicing <slice>`.
+
+:dp:`fls_Vt9C9mKxHOwo`
+A :t:`place` is captured by :t:`immutable borrow` if its :t:`discriminant` is read by :t:`pattern matching`.
+
+:dp:`fls_Fs12dmznjsMf`
+Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.
+
+:dp:`fls_7EXHdE2eOVek`
+Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.
+
+:dp:`fls_iLH8X2U4ADHb`
+Matching against a :t:`range pattern` captures the place by :t:`immutable borrow`.
+
+:dp:`fls_HMJUXHrvOmPl`
+Matching a :t:`slice` against a slice :t:`pattern`, other than one with only a single rest pattern ``[..]``, captures the slice by :t:`immutable borrow`.
+
+:dp:`fls_Gj1znNpthHY6`
+Matching an array against a slice pattern does not capture the :t:`place`.
+
+:dp:`fls_IFyJvb6mlFU4`
+Move closures can only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`reference`.
+
+:dp:`fls_7NEEJgKSpQQ8`
+Closures will only capture the prefix of a :t:`capture path` that runs up to, but not including, the first :t:`dereference` of a :t:`raw pointer`.
+
+:dp:`fls_kYFd3p06pWWV`
+Closures will only capture the prefix of a :t:`capture path` of a :t:`union` that runs up to the union itself.
+
+:dp:`fls_fATMTNUOHsfb`
+Closures will only capture the prefix of the :t:`capture path` that runs up to, but not including, the first :t:`field access expression` into a structure that uses the :t:`attribute` ``packed`` representation, in unaligned :t:`[field]s` in a struct.
+
+:dp:`fls_fITor3jpmgrl`
+Taking the address of an unaligned :t:`field` captures the entire struct.


Separate point on the repr(packed) rule in this block: this still seems narrower than the Reference.

Upstream truncates at the first field access into any repr(packed) struct, and explicitly says this includes fields that are currently aligned as well, for future-compatibility reasons.

Could this sentence be widened accordingly instead of limiting it to unaligned fields?

Support:

Reference type.closure.capture.precision.unaligned

PLeVasseur · 2026-04-22T19:30:46Z

+  The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.
+
+:dp:`fls_v8IFXHJnXhez`
+A :t:`place` is not captured when an :t:`underscore expression` is used to bind it.


Optional completeness point: upstream also states that values matched with wildcards must still be initialized.

If you want closer Reference parity in this subsection, consider adding a short note or rule for that as well.

Support:

Reference type.closure.capture.precision.wildcard.initialized

View changes since the review

PLeVasseur · 2026-04-22T19:30:47Z

+Matching against a variant of an enum that has more than one variant captures the :t:`place` by :t:`immutable borrow`.
+
+:dp:`fls_7EXHdE2eOVek`
+Matching against a variant of an enum that has one variant does not capture the place, unless it is marked with :t:`attribute` ``non_exhaustive``, in which case the place is captured by :t:`immutable borrow`.


Separate completeness point on the discriminant-read rules: this block still seems to omit the Reference rule for uninhabited variants.

Even if all variants but the one being matched against are uninhabited, the discriminant is still read if it otherwise would be.

Could this subsection add that explicitly?

Support:

Reference type.closure.capture.precision.discriminants.uninhabited-variants

Make operational semantics of pattern matching independent of crate and module rust#150681

View changes since the review

…erload the term) Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

document Closure capture precision

c732101

Hoverbear reviewed Apr 20, 2026

View reviewed changes

Comment thread src/types-and-traits.rst Outdated

typo

c0edef2

Co-authored-by: Ana Hobden <operator@hoverbear.org>

kirtchev-adacore self-requested a review April 21, 2026 07:11

kirtchev-adacore requested changes Apr 21, 2026

View reviewed changes

tshepang and others added 4 commits April 21, 2026 11:34

use a defined term

675a96e

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

remove a redundancy, and add some links

8e81cd6

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

grammar and consistency fix

40847f4

link-it

7be2ad5

Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

tshepang force-pushed the tshepang/capture-precision branch from e3ed8e9 to 7be2ad5 Compare April 21, 2026 09:49

tshepang added 7 commits April 21, 2026 13:28

define the term before using it

4bb12b8

be more consise and clear, remove redundancy, and link to a definition

55c761f

be more consise and clear, remove redundancy, and link to some defini…

ef632c1

…tions

clarity

032028c

missing word

ce486db

dangling term

83df9a6

move to a more suitable place

06229e7

tshepang requested a review from kirtchev-adacore April 21, 2026 13:36

kirtchev-adacore requested changes Apr 22, 2026

View reviewed changes

PLeVasseur requested changes Apr 22, 2026

View reviewed changes

PLeVasseur reviewed Apr 22, 2026

View reviewed changes

tshepang and others added 2 commits April 23, 2026 18:14

be less verbose (and nearly all the paragraphs are rules, so don't ov…

d318d3c

…erload the term) Co-authored-by: Hristian Kirtchev <60669983+kirtchev-adacore@users.noreply.github.com>

link-it

85fc279

	A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, which may be truncated based on these rules:
	A :t:`closure expression` :t:`[borrow]s` or :t:`moves <by move>` the :t:`capture path`, as follows:

	When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is captured with the highest :t:`capture mode` among the two :t:`[capture path]s`.
	- When a :t:`capture path` and an ancestor :t:`capture path` are both :t:`captured <capturing>`, the ancestor :t:`capture path` is :t:`captured` with the highest :t:`capture mode` among the two :t:`[capture path]s`.

	The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.
	- The :t:`capture path` is truncated at the rightmost :t:`dereference` in the :t:`capture path` if the :t:`dereference` is applied to a :t:`shared reference`.

		A :dt:`place projection` is a :t:`field access expression`, :t:`dereference`, :t:`array` or :t:`slice` :t:`index expression`, or :t:`pattern` destructuring applied to a :t:`variable`.

		:dp:`fls_rdDT7jsaOMbs`

Conversation

tshepang commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

kirtchev-adacore left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kirtchev-adacore Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kirtchev-adacore left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • edited by tshepang Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PLeVasseur Apr 22, 2026 • edited by tshepang Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tshepang commented Apr 20, 2026 •

edited

Loading

kirtchev-adacore left a comment •

edited by rustbot

Loading

kirtchev-adacore Apr 21, 2026 •

edited

Loading

tshepang commented Apr 21, 2026 •

edited

Loading

kirtchev-adacore left a comment •

edited by rustbot

Loading

tshepang Apr 23, 2026 •

edited

Loading

tshepang Apr 23, 2026 •

edited

Loading

PLeVasseur Apr 22, 2026 •

edited

Loading

PLeVasseur Apr 22, 2026 •

edited by tshepang

Loading

PLeVasseur left a comment •

edited by rustbot

Loading

PLeVasseur Apr 22, 2026 •

edited

Loading

PLeVasseur Apr 22, 2026 •

edited by tshepang

Loading

PLeVasseur Apr 22, 2026 •

edited

Loading

PLeVasseur Apr 22, 2026 •

edited by tshepang

Loading

PLeVasseur Apr 22, 2026 •

edited by rustbot

Loading

PLeVasseur Apr 22, 2026 •

edited by tshepang

Loading