`ref` parameters, arguments, returns and `let` returns #5434

josh11b · 2025-05-06T23:26:26Z

A parameter binding can be marked ref instead of var or the default. It will bind to reference argument expressions in the caller and produces a reference expression in the callee.
- Unlike pointers, a ref binding can't be rebound to a different object.
- This replaces addr, and is not restricted to the self parameter.
- A ref binding, like a let binding, can't be used in fields of classes or structs.
- When calling functions, arguments to non-self ref parameters are also marked with ref.
The return of a function can optionally be marked ref, let, or var. These control the category of the call expression invoking the function, and how the return expression is returned.
- These may be mixed for functions returning parens or brace forms.
Any parameters whose lifetime needs to contain the lifetime of the return must be marked bound.
The address of a ref binding is nocapture and noalias.
We mark parameters of a function that may be referenced by the return value with bound.

proposals/p5434.md

danakj · 2025-05-20T20:32:26Z

proposals/p5434.md

+```carbon
+fn F(ptr: i32*) {
+  // A reference binding `x`.
+  let ref x: i32 = *ptr;


At a high level, let can be thought of as a const thing, and var as a mutable thing, though there are of course storage implications. But this breaks that mental model for developers, so maybe we could preserve that by using ref x: instead?

This is the "Top-level ref introducer" alternative. I have taken the conservative approach that we can always add this later, but I'd be interested in hearing if this is widely believed to be an issue.

That mental model breaks in a lot of places already. For example, fn F(x: i32) declares an immutable x despite the absence of let, and let (var x: i32, y: i32) = ... declares a mutable x despite the presence of let. We can't make that model coherent (without much deeper changes), so I don't think we should try to accommodate it.

I'm realizing that -> let really encourages the mental model where let means immutable (or at least by-value), but as noted elsewhere, I think that means we should choose a different syntax. If we don't, then I don't know, maybe allowing ref as a statement introducer would be desirable as well.

CJ-Johnson · 2025-05-20T20:35:04Z

proposals/p5434.md

+
+This is a "try it and see how well it works" sort of decision.
+
+### Top-level `ref` introducer


Just got finished reading! Really excited about this direction.

One question comes to mind:

Top-level ref introducer

For now, we don't believe let ref to be so common as to need a shorter way to write, unlike what we do for var.

There doesn't appear to be much written on this. Why was this decision made? I personally find it surprising that the following code is invalid:

fn F(ptr: T*) { ref t: T = *ptr; }

Is this something that we have strong consensus on? Or is it possible to reconsider before landing the proposal?

Thanks!

I don't know how strong the consensus, but I think the reason here is enough for my personal opinion to be to go forward with the approach in the proposal.

proposals/p5434.md

geoffromer · 2025-05-20T18:14:17Z

proposals/p5434.md

+-   [the address-of operator](/docs/design/expressions/pointer_operators.md)
+    `&`;
+-   [the indexing operator](/docs/design/expressions/indexing.md) `[`...`]`;
+-   [the member access operator](/docs/design/expressions/member_access.md) `.`;


As far as I can tell, this isn't modeled as a function call, so it doesn't take parameters at all, ref or otherwise.

See #3720 . Looking that over, looks like I should included an update to the BindToRef interface in this proposal.

proposals/p5434.md

chandlerc · 2025-05-20T23:34:45Z

proposals/p5434.md

+The rule is: `returned var` may only be used when there is a single component to
+the return form, and it is either `->var` or default `->`.


I wonder -- could we instead simply say that returned ... must match the structure of the return pattern, and any non-->var or non--> components must be initialized in the declaration?

(also OK deferring this if folks prefer, it just seems a clean generalization)

This was the first option in the "return var with compound return forms" alternative considered. How would you expect that example to be written?

fn F(...) -> (->ref R, ->let L, -> V) { returned (ref r: R, let l: L, var v: V) = (...); // or? returned let (ref r: R, let l: L, var v: V) = (...); // What goes here? return ???; }

I also don't see a way to avoid initializing all of them together using this approach.

We could shorten return var; to simply return; when a returned ... declaration is in scope. I'm not sure how much clarity we're getting from including the var keyword there. If we do that, we might also want to consider allowing flowing off the end of a function with a returned declaration in its outermost block scope.

chandlerc · 2025-05-21T01:50:39Z

proposals/p5434.md

+-   A call to a function declared `-> var T` is an initializing expression. The
+    caller provides the address of storage to initialize with an object of type
+    `T`, that the caller owns upon return. The object will never be returned in
+    registers.


After chatting with @zygoloid, I think I convinced him that we could fold together -> T and -> var T. I'm happy to write up more fully the idea, or discuss it / take notes on it, but leaving a quick comment here so I don't forget.

For my own memory, the most convincing thing was to start from thinking about var parameters, and how we would want those to work for an owning pointer like std::unique_ptr.

More details when I have a bit more time at a keyboard...

I've updated the proposal to remove -> var T, and added it instead to the alternatives considered.

chandlerc

(please ignore the "approve" ... misclick and high github latency...)

(misclicked the button)

Co-authored-by: Geoff Romer <[email protected]>

proposals/p5434.md

geoffromer · 2025-05-21T17:17:35Z

proposals/p5434.md

+We can revisit and expand this later if this does not handle use cases we would
+like to support.
+
+### Use case: `Deref` interface


(Sorry, I forgot to include this comment in my first batch.)

When a proposal is making changes to an already-documented design, I think we should err pretty strongly on the side of making those documentation changes as part of the proposal. Seeing the changes in context should make it substantially easier to review, and may surface important issues that should be considered as part of the proposal (plus, it eliminates the time window where the design docs no longer reflect the adopted design).

This section and the next one seem like they would particularly benefit from this, but I think it applies to this proposal as a whole.

I have updated expressions/indexing.md with the changes from the next section, but Deref is not currently in the design.

As for updating the rest of the design, I think it is important to get consensus on the proposal first, otherwise iteration will be significantly more expensive. Updating all of the design docs to reflect this change is going to be a big effort which we will need to prioritize against other work, and may need to be done only partially at first.

Co-authored-by: Geoff Romer <[email protected]>

geoffromer

I'm still reviewing, but I wanted to get a few of these comments out early in case they're worth discussing this afternoon.

proposals/p5434.md

geoffromer · 2025-05-21T23:24:03Z

proposals/p5434.md

+    optional `ref` or `let` between the `->` and `auto`. `-> auto` continues to
+    return an initializing expression, `-> let auto` returns a value expression,
+    and `-> ref auto` returns a durable reference expression.
+-   Using `=>` to specify a return continues to return an initializing


I think there's a strong case to be made for having => deduce the expression form, because that makes(fn => expr)() a drop-in replacement for expr. I'd be fine with leaving this as an open question, but I'd rather not resolve it (particularly not in this way) without considering that alternative.

There is an issue that if we return something other than an initializing expression, we probably need the parameters to be marked bound. I added some text saying that.

geoffromer · 2025-05-21T23:38:19Z

proposals/p5434.md

+```carbon
+fn F(ptr: i32*) {
+  // A reference binding `x`.
+  let ref x: i32 = *ptr;


I'm realizing that -> let really encourages the mental model where let means immutable (or at least by-value), but as noted elsewhere, I think that means we should choose a different syntax. If we don't, then I don't know, maybe allowing ref as a statement introducer would be desirable as well.

geoffromer · 2025-05-22T00:52:27Z

proposals/p5434.md

+
+### `ref`, `let`, and `var` returns
+
+The return of a function can optionally be marked `ref` or `let`. These control


I'd like to suggest an alternative:

The return of a function can optionally marked with ref or val, which causes the function call to be a reference or value expression (respectively).

A binding pattern can optionally be marked with ref or val, which causes name expressions that name the binding to be reference or value expressions (respectively). Note that this gives us a way to declare a value binding that's nested inside a var.

That way there's a clear and consistent parallel between ref and val:

Each can be used as a modifier on a binding pattern or function return declaration, and nowhere else.

Each causes uses of the declared entity to have a particular category.

Each is an abbreviation of the name of that category.

One is the implicit default for bindings inside var, and the other is the implicit default for bindings outside var.

Even the ways the parallels break down are illuminating, because they reflect the asymmetries of the underlying model of expression categories:

ref on a binding pattern constrains the category of the scrutinee, whereas val does not, but that reflects the fact that there are no conversions from other categories to durable reference.

var is a modifier on -> but acts as an independent operator rather than a binding modifier in patterns, but that reflects the fact that matching an initializing expression has side effects, and does not propagate its category to the subpattern's scrutinee.

This also preserves the current simplicity of let: it's solely a pattern introducer, with no connection to expression categories or mutability.

geoffromer · 2025-05-22T18:21:09Z

proposals/p5434.md

+Mirroring the [paren](/docs/design/pattern_matching.md#tuple-patterns) and
+[brace](/docs/design/pattern_matching.md#struct-patterns) pattern forms, we also
+support paren and brace return forms. Every element of these forms starts with


But where does that leave "tuple literal" and "tuple pattern", which are neither types nor forms? Tuple literals in particular seem easy to confuse with tuple types, and possibly also with paren forms. Also, why would "tuple forms" and "tuple types" not be sufficiently distinguished by the fact that they have different head nouns?

josh11b added proposal A proposal proposal draft Proposal in draft, not ready for review labels May 6, 2025

Filling out template with PR 5434

9648270

josh11b force-pushed the ref branch from fad02f6 to 9648270 Compare May 6, 2025 23:26

josh11b added 18 commits May 6, 2025 23:29

Checkpoint progress.

a0b90c7

Checkpoint progress.

7cc4b32

Checkpoint progress.

bf4930f

Checkpoint progress.

cc0a1f3

Checkpoint progress.

eb2ab64

Checkpoint progress.

a71ba59

Checkpoint progress.

018dda5

Checkpoint progress.

cbacede

Checkpoint progress.

2d6a7a3

Checkpoint progress.

4a87f20

Checkpoint progress.

90d250e

Checkpoint progress.

8151bed

Checkpoint progress.

7172159

Checkpoint progress.

66a6f47

Checkpoint progress.

8060cf7

Checkpoint progress.

4b1584d

Ready for review

c89d46d

Oops, missed a couple of final touches

0894f68

josh11b marked this pull request as ready for review May 20, 2025 05:47

Merge remote-tracking branch 'upstream/trunk' into ref

79d6ddb

github-actions bot requested a review from zygoloid May 20, 2025 05:48

github-actions bot added proposal rfc Proposal with request-for-comment sent out and removed proposal draft Proposal in draft, not ready for review labels May 20, 2025

josh11b requested a review from geoffromer May 20, 2025 16:12

CJ-Johnson reviewed May 20, 2025

View reviewed changes

proposals/p5434.md Show resolved Hide resolved

danakj reviewed May 20, 2025

View reviewed changes

CJ-Johnson reviewed May 20, 2025

View reviewed changes

geoffromer reviewed May 20, 2025

View reviewed changes

chandlerc previously approved these changes May 21, 2025

View reviewed changes

chandlerc reviewed May 21, 2025

View reviewed changes

chandlerc self-requested a review May 21, 2025 01:51

Apply suggestions from code review

acec7d9

Co-authored-by: Geoff Romer <[email protected]>

CarbonInfraBot reviewed May 21, 2025

View reviewed changes

josh11b added 2 commits May 21, 2025 04:48

Updates inspired by review

626c3ae

Fix incorrect statement

319f5eb

geoffromer reviewed May 21, 2025

View reviewed changes

josh11b and others added 6 commits May 21, 2025 18:54

Changes in response to review

28d8cc2

Update proposals/p5434.md

3570dc0

Co-authored-by: Geoff Romer <[email protected]>

Move indexing changes to the relevant design doc

3f654fc

Incorporate more feedback

2a76c74

typo

2915e39

Implement suggestion

cf7d94e

josh11b requested a review from geoffromer May 21, 2025 22:08

josh11b added 2 commits May 21, 2025 23:50

Add small section on completeness

4075aed

Title

3e13632

josh11b changed the title ~~ref~~ ref parameters, arguments, returns and let returns May 22, 2025

geoffromer reviewed May 22, 2025

View reviewed changes

This was referenced May 22, 2025

Immutable value semantic returns questions from #5434 #5522

Open

Semantic restrictions of immutable value (let) bindings #5524

Open

Consider alternative category for =>

0fdf298

geoffromer mentioned this pull request May 23, 2025

Orthogonality in the binding design questions prompted by #5434 #5523

Open


		This is a "try it and see how well it works" sort of decision.

		### Top-level `ref` introducer

		The rule is: `returned var` may only be used when there is a single component to
		the return form, and it is either `->var` or default `->`.


		### `ref`, `let`, and `var` returns

		The return of a function can optionally be marked `ref` or `let`. These control

ref parameters, arguments, returns and let returns #5434

Are you sure you want to change the base?

ref parameters, arguments, returns and let returns #5434

Uh oh!

Conversation

josh11b commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zygoloid May 22, 2025 • 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!

chandlerc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

geoffromer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josh11b May 22, 2025 • 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!

Uh oh!

`ref` parameters, arguments, returns and `let` returns #5434

`ref` parameters, arguments, returns and `let` returns #5434

josh11b commented May 6, 2025 •

edited

Loading

zygoloid May 22, 2025 •

edited

Loading

josh11b May 22, 2025 •

edited

Loading