The *`collapse_debuginfo` [attribute]* controls whether code locations from a macro definition are collapsed into a single location associated with the macro's call site,
when generating debuginfo for code calling this macro.
The attribute uses the [_MetaListIdents_] syntax to specify its inputs, and can only be applied to macro definitions.
Accepted options:
- `#[collapse_debuginfo(yes)]` — code locations in debuginfo are collapsed.
- `#[collapse_debuginfo(no)]` — code locations in debuginfo are not collapsed.
- `#[collapse_debuginfo(external)]` — code locations in debuginfo are collapsed only if the macro comes from a different crate.
The `external` behavior is the default for macros that don't have this attribute, unless they are built-in macros.
For built-in macros the default is `yes`.
> **Note**: `rustc` has a `-C collapse-macro-debuginfo` CLI option to override both the default collapsing behavior and `#[collapse_debuginfo]` attributes.
The compiler prefers to capture a closed-over variable by immutable borrow,
The compiler prefers to capture a value by immutable borrow,
followed by unique immutable borrow (see below), by mutable borrow, and finally
by move. It will pick the first choice of these that is compatible with how the
captured variable is used inside the closure body. The compiler does not take
surrounding code into account, such as the lifetimes of involved variables, or
captured value is used inside the closure body. The compiler does not take
surrounding code into account, such as the lifetimes of involved variables or fields, or
of the closure itself.
If the `move` keyword is used, then all captures are by move or, for `Copy`
types, by copy, regardless of whether a borrow would work. The `move` keyword is
usually used to allow the closure to outlive the captured values, such as if the
closure is being returned or used to spawn a new thread.
## Capture Precision
Composite types such as structs, tuples, and enums are always captured entirely,
not by individual fields. It may be necessary to borrow into a local variable in
order to capture a single field:
The precise path that gets captured is typically the full path that is used in the closure, but there are cases where we will only capture a prefix of the path.
### Shared prefix
In the case where a path and one of the ancestor’s of that path are both captured by a closure, the ancestor path is captured with the highest capture mode among the two captures,`CaptureMode = max(AncestorCaptureMode, DescendantCaptureMode)`, using the strict weak ordering
Note that this might need to be applied recursively.
```rust
# use std::collections::HashSet;
#
struct SetVec {
set: HashSet<u32>,
vec: Vec<u32>
}
# fn move_value<T>(_: T){}
let s = String::from("S");
let t = (s, String::from("T"));
let mut u = (t, String::from("U"));
impl SetVec {
fn populate(&mut self) {
let vec = &mut self.vec;
self.set.iter().for_each(|&n| {
vec.push(n);
})
}
}
let c = || {
println!("{:?}", u); // u captured by ImmBorrow
u.1.truncate(0); // u.0 captured by MutBorrow
move_value(u.0.0); // u.0.0 captured by ByValue
};
```
If, instead, the closure were to use `self.vec` directly, then it would attempt
to capture `self` by mutable reference. But since `self.set` is already
borrowed to iterate over, the code would not compile.
Overall the closure will capture `u` by `ByValue`.
### Wild Card Patterns
Closures only capture data that needs to be read, which means the following closures will not capture `x`
```rust
let x = 10;
let c = || {
let _ = x;
};
let c = || match x {
_ => println!("Hello World!")
};
```
### Capturing references in move contexts
Moving fields out of references is not allowed. As a result, in the case of move closures, when values accessed through a shared references are moved into the closure body, the compiler will truncate right before a dereference.
```rust
struct T(String, String);
let mut t = T(String::from("foo"), String::from("bar"));
let t = &mut t;
let c = move || t.0.truncate(0); // closure captures `t`
```
### Raw pointer dereference
Because it is `unsafe` to dereference a raw pointer, closures will only capture the prefix of a path that runs up to, but not including, the first dereference of a raw pointer.
```rust,
struct T(String, String);
let t = T(String::from("foo"), String::from("bar"));
let t = &t as *const T;
let c = || unsafe {
println!("{}", (*t).0); // closure captures t
};
```
### Reference into unaligned `struct`s
Because it is `unsafe` to hold references to unaligned fields in a structure, closures will only capture the prefix of the path that runs up to, but not including, the first field access into an unaligned structure.
```rust
#[repr(packed)]
struct T(String, String);
let t = T(String::from("foo"), String::from("bar"));
let c = || unsafe {
println!("{}", t.0); // closure captures t
};
```
### `Box` vs other `Deref` implementations
The implementation of the [`Deref`] trait for [`Box`] is treated differently from other `Deref` implementations, as it is considered a special entity.
For example, let us look at examples involving `Rc` and `Box`. The `*rc` is desugared to a call to the trait method `deref` defined on `Rc`, but since `*box` is treated differently by the compiler, the compiler is able to do precise capture on contents of the `Box`.
However, if the contents of the `Box` are moved into the closure, then the box is entirely captured. This is done so the amount of data that needs to be moved into the closure is minimized.
```rust
struct S(i32);
let b = Box::new(S(10));
let c_box = || {
let x = (*b).0; // closure captures `b`
};
```
#### `move` closure
Similarly to moving contents of a `Box` in a non-`move` closure, reading the contents of a `Box` in a `move` closure will capture the `Box` entirely.
```rust
struct S(i32);
let b = Box::new(S(10));
let c_box = || {
println!("{}", (*b).0); // closure captures `b`
};
```
## Unique immutable borrows in captures
@ -113,6 +226,7 @@ the declaration of `y` will produce an error because it would violate the
uniqueness of the closure's borrow of `x`; the declaration of z is valid because
the closure's lifetime has expired at the end of the block, releasing the borrow.
## Call traits and coercions
Closure types all implement [`FnOnce`], indicating that they can be called once
@ -156,12 +270,13 @@ following traits if allowed to do so by the types of the captures it stores:
The rules for [`Send`] and [`Sync`] match those for normal struct types, while
[`Clone`] and [`Copy`] behave as if [derived]. For [`Clone`], the order of
cloning of the captured variables is left unspecified.
cloning of the captured values is left unspecified.
Because captures are often by reference, the following general rules arise:
* A closure is [`Sync`] if all captured variables are [`Sync`].
* A closure is [`Send`] if all variables captured by non-unique immutable
* A closure is [`Sync`] if all captured values are [`Sync`].
* A closure is [`Send`] if all values captured by non-unique immutable
reference are [`Sync`], and all values captured by unique immutable or mutable
reference, copy, or move are [`Send`].
* A closure is [`Clone`] or [`Copy`] if it does not capture any values by
@ -178,3 +293,275 @@ Because captures are often by reference, the following general rules arise:
If a closure captures a field of a composite types such as structs, tuples, and enums by value, the field's lifetime would now be tied to the closure. As a result, it is possible for disjoint fields of a composite types to be dropped at different times.
} // 'c' and 'tuple.0' dropped here ------------+ |
} // tuple.1 dropped here -----------------------------+
```
## Overall Capture analysis algorithm
* Input:
* Analyzing the closure C yields a mapping of `Place -> Mode` that are accessed
* Access mode is `ref`, `ref uniq`, `ref mut`, or `by-value` (ordered least to max)
* For a `Place` that is used in two different access modes within the same closure, the mode reported from closure analysis is the maximum access mode.
* Note: `ByValue` use of a `Copy` type is seen as a `ref` access mode.
* Closure mode is `ref` or `move`
* Output:
* Minimal `(Place, Mode)` pairs that are actually captured
* Let `(Place1, _) = truncate_place(Place, Mode, i)`
* Return (Place1, ByValue)
* Else:
* Return (Place, ByValue)
* Note that initially we had considered an approach where "Take ownership if data being accessed is owned by the variable used to access it (or if closure attempts to move data that it doesn't own). That is when taking ownership only capture data that is found on the stack otherwise reborrow the reference.". This cause a bug around lifetimes, check [rust-lang/rust#88431](https://github.com/rust-lang/rust/issues/88431).
This test shows how a `move` closure can sometimes capture values by mutable reference, if they are reached via a `&mut` reference.
```rust
struct Foo { x: i32 }
fn box_mut() {
let mut s = Foo { x: 0 } ;
let px = &mut s;
let bx = Box::new(px);
let c = move || bx.x += 10;
// Mutable reference to this place:
// (*(*bx)).x
// ^ ^
// | a Box
// a &mut
}
```
<!-- ignore: Omit error about unterminated string literal when representing c_prime -->
```ignore
Closure mode = move
C_in = {
(ref mut, (*(*bx)).x)
}
C_out = C_in
```
Output is the same: `C' = C`
### Packed-field-ref-and-move
When you have a closure that both references a packed field (which is unsafe) and moves from it (which is safe) we capture the entire struct, rather than just moving the field. This is to aid in predictability, so that removing the move doesn't make the closure become unsafe:
```rust
#[repr(packed)]
struct Packed { x: String }
# fn use_ref<T>(_: &T) {}
# fn move_value<T>(_: T) {}
fn main() {
let packed = Packed { x: String::new() };
let c = || {
use_ref(&packed.x);
move_value(packed.x);
};
c();
}
```
<!-- ignore: Omit error about unterminated string literal when representing c_prime -->
```ignore
Closure mode = ref
C_in = {
(ref mut, packed)
}
C_out = C_in
```
### Optimization-Edge-Case
This test shows an interesting edge case. Normally, when we see a borrow of something behind a shared reference (`&T`), we truncate to capture the entire reference, because that is more efficient (and we can always use that reference to reach all the data it refers to). However, in the case where we are dereferencing two shared references, we have to be sure to preserve the full path, since otherwise the resulting closure could have a shorter lifetime than is necessary.
<!-- ignore: Omit error about unterminated string literal when reprenting c_prime -->
```ignore
Closure mode = ref
C_in = {
(ref mut, *m.a)
}
C_out = C_in
```
# Edition 2018 and before
## Closure types difference
In Edition 2018 and before, a closure would capture variables in its entirety. This means that for the example used in the [Closure types](#closure-types) section, the generated closure type would instead look something like this:
<!-- ignore: simplified -->
```rust,ignore
struct Closure<'a> {
rect : &'a mut Rectangle,
}
impl<'a> FnOnce<()> for Closure<'a> {
type Output = String;
fn call_once(self) -> String {
self.rect.left_top.x += 1;
self.rect.right_bottom.x += 1;
format!("{:?}", self.rect.left_top)
}
}
```
and the call to `f` would work as follows:
<!-- ignore: continuation of above -->
```rust,ignore
f(Closure { rect: rect });
```
## Capture precision difference
Composite types such as structs, tuples, and enums are always captured in its entirety,
not by individual fields. As a result, it may be necessary to borrow into a local variable in order to capture a single field:
```rust
# use std::collections::HashSet;
#
struct SetVec {
set: HashSet<u32>,
vec: Vec<u32>
}
impl SetVec {
fn populate(&mut self) {
let vec = &mut self.vec;
self.set.iter().for_each(|&n| {
vec.push(n);
})
}
}
```
If, instead, the closure were to use `self.vec` directly, then it would attempt
to capture `self` by mutable reference. But since `self.set` is already
borrowed to iterate over, the code would not compile.
If the `move` keyword is used, then all captures are by move or, for `Copy`
types, by copy, regardless of whether a borrow would work. The `move` keyword is
usually used to allow the closure to outlive the captured values, such as if the
closure is being returned or used to spawn a new thread.
Regardless of if the data will be read by the closure, i.e. in case of wild card patterns, if a variable defined outside the closure is mentioned within the closure the variable will be captured in its entirety.
## Drop order difference
As composite types are captured in their entirety, a closure which captures one of those composite types by value would drop the entire captured variable at the same time as the closure gets dropped.
Roxane
Eric Huss
Vadim Petrochenkov
Aman Arora
Aman Arora
Roxane