RFC: Capture upvars by value unless the ref keyword is used

[pcwalton]

• Start Date: 2014-07-02
• RFC PR #: (leave this empty)
• Rust Issue #: 12831

Summary

Closures should capture their upvars by value unless the ref keyword is used.

Motivation

For unboxed closures, we will need to syntactically distinguish between captures by value and captures by reference.

Detailed design

This is a small part of #114, split off to separate it from the rest of the discussion going on in that RFC.

Closures should capture their upvars (closed-over variables) by value unless the ref keyword precedes the opening | of the argument list. Thus |x| x + 2 will capture x by value (and thus, if x is not Copy, it will move x into the closure), but ref |x| x + 2 will capture x by reference.

In an unboxed-closures world, the immutability/mutability of the borrow (as the case may be) is inferred from the type of the closure: Fn captures by immutable reference, while FnMut captures by mutable reference. In a boxed-closures world, the borrows are always mutable.

Drawbacks

It may be that ref is unwanted complexity; it only changes the semantics of 10%-20% of closures, after all. This does not add any core functionality to the language, as a reference can always be made explicitly and then captured. However, there are a lot of closures, and the workaround to capture a reference by value is painful.

Alternatives

As above, the impact of not doing this is that reference semantics would have to be achieved. However, the diff against current Rust was thousands of lines of pretty ugly code.

Another alternative would be to annotate each individual upvar with its capture semantics, like capture clauses in C++11. This proposal does not preclude adding that functionality should it be deemed useful in the future. Note that C++11 provides a syntax for capturing all upvars by reference, exactly as this proposal does.

Unresolved questions

None.

[lilyball]

I am confused. |x| is the argument list. How does ref |x| capture x by-ref? It's not being captured at all.

Also, having ref before the argument list suggests that either all captures must be by-reference or all captures must be by-value. And what about mutable captures? If ref mut is allowed, that means that all captures must be by-mutable-reference, even if only one capture needs to be mutable and the rest shouldn't (or quite possibly even can't).

[huonw]

You can always use the explicit form of capturing either & or &mut references by value (this RFC is essentially sugar around that).

[pcwalton]

Yes, sorry, I should have worded that as "Thus |x| x + y will capture y by value (and thus, if y is not Copy, it will move y into the closure), but ref |x| x + y will capture y by reference."

Also, having ref before the argument list suggests that either all captures must be by-reference or all captures must be by-value.

Yes. I believe that wanting individual captures to be different is sufficiently rare that it doesn't need syntax.

And what about mutable captures? If ref mut is allowed, that means that all captures must be by-mutable-reference, even if only one capture needs to be mutable and the rest shouldn't (or quite possibly even can't).

ref mut will not be allowed; rather the mutability of the borrows is implied by the kind of closure it is (in an unboxed closures world, the trait that it implements; in a boxed closures world, always mutable).

[bstrie]

In the worst-case, what would a maximally-explicit closure look like, with lifetimes, by-ref captures, full type signatures, and so on? Just want to make sure this doesn't add in some ambiguity somewhere.

[brson]

Discussed in https://github.com/rust-lang/meeting-minutes/blob/master/weekly-meetings/2014-07-08.md. Accepted as RFC 38.