Sākums Izpētīt Palīdzība
Pierakstīties
tomteb
/
carbon-lang
1
0
Atdalīts 0
Faili Problēmas 0 Izmaiņu pieprasījumi 0 Vikivietne
Atzars: trunk
Atzari Tagi
carbon-lang
/
proposals
/
p5434.md

p5434.md 62 KB
Patstāvīgā saite Vēsture Neapstrādāts

ref parameters, arguments, returns and val returns

Pull request

Table of contents

Abstract

  • 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 value 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, val, 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 tuple or struct 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.

Problem

Reference bindings have come up multiple times:

  • as a better alternative to addr self: Self*;
  • for use in lambda captures;
  • to model different kinds of C++ references for interop and migration;
  • to support nested bindings within a destructured var, see issue #5250 and proposal #5164;
  • for forwarding arguments while preserving expression category;
  • to add a feature to pattern matching to modify things after they have been matched;
  • to support refactoring code without changing all the uses of a name, a problem we are already seeing with self and addr self, and would be a point of friction in local pattern matching in the future; and
  • to support breaking up an expression into pieces without altering the expression category of individual pieces.

Reference returns have also come up before, particularly to support operators such as indexing [...] and other functions that should produce a reference expression. It is desirable, though, that this not introduce new memory unsafety concerns, due to returning a reference to something with insufficient lifetime.

In addition, we have been interested in adding other return mechanisms that support returning values in registers in cases that our current convention won't.

Background

Proposal

ref bindings

We introduce a new keyword ref. This may be added to a : binding to mark it as binding to a reference expression, as in:

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

  // Use of `x` is a reference expression that
  // refers to the same object as `*ptr`.
  Assert(&x == ptr);

  // Equivalent to `*ptr += 1;`.
  x += 1;
}

fn G() {
  var y: i32 = 2;
  F(&y);
  Assert(y == 3);
}

The use of the name (x in the example) of a ref binding forms a durable reference expression. We ensure that reference expressions formed by way of reference bindings do not dangle. A ref binding may only bind to a durable reference expression or an expression that can be converted to one. The bound durable reference expression must outlive the ref binding.

The address of a ref bound name gives the address of the bound object, so &x == ptr above. The reference itself does not have an address, and unlike a pointer can't be rebound to reference a different object.

We remove addr, and use instead use ref for the self parameter when an object is required. Note that the type will change from Self* to Self in this case. In the future, we might re-add addr back if needed.

class C {
  // ❌ No longer valid.
  fn OldMethod[addr self: Self*]() {
    // Previously would dereference `self` in
    // the body of the method.
    self->x += 3;
  }

  // ✅ Now valid.
  fn NewMethod[ref self: Self]() {
    // Now `self` is a reference expression,
    // and is not dereferenced.
    self.x += 3;
  }

  // ✅ Other uses are unchanged.
  fn Get[self: Self]() -> i32 {
    return self.x;
  }

  var x: i32;
}

Potentially abbreviating the syntax further (to allow ref self as a short form of ref self: Self) is left as future work.

The ref modifier is allowed on : bindings that are not:

  • inside a var pattern,
  • a field of a class type, or

  • a field of a struct type.

    fn AddTwoToRef(ref x: i32) {
x += 1;
let ref y: i32 = x;
y += 1;
}

// Equivalent to:
fn AddTwoToRef(ref x: i32) {
x += 1;
let y_ptr: i32* = &x;
*y_ptr += 1;
}

We add support for ref and var in a struct pattern when using the shorthand a: T syntax for .a = a: T:

let {var a: i32, ref b: i32} = ...;

// Now equivalent to:
let {.a = var a: i32, .b = ref b: i32} = ...;

Note: This takes us one step closer to { ambiguity. Previously we could distinguish between a struct literal/pattern and a non-empty block with only up to two tokens of lookahead (the struct cases start with . or _ or identifier followed by :, and the block cases don't). Now we have things like:

> fn F() -> X { var a: i32 = 0; }
> ```
>
> ... where we're getting incrementally closer to ambiguity. We've got a few
> more steps before we get there, though, since we don't have an `X{...}`
> expression yet, and `var ...` is only allowed in struct patterns rather than
> struct expressions. So we're still fine, but this is cutting down our options
> for future syntactic expansion a little.

The `ref` modifier is forbidden on the bindings in `class` or struct type
fields.

var outer_size: i32 = 123;

class Invalid { // ❌ Invalid. We don't currently have runtime let bindings in classes, // or ref on vars, but the intent is to not have ref bindings as fields. let ref invalid_ref_field: i32 = outer_size; }

// ❌ Invalid. var invalid_struct_type_field:

{ref .invalid: i32} = {.invalid = outer_size};


In a function argument list, arguments to non-`self` `ref` parameters are also
marked with `ref`. Continuing the example:

carbon var z: i32 = 3; AddTwoToRef(ref z); Assert(z == 5);

// No ref though on the self argument. var c: C = {.x = 4}; c.NewMethod(); Assert(c.Get() == 7);


> **Note:** It is important that this restriction is syntactic, not just
> semantic, because it means that `ref` is never the first token of a full
> expression, and so we know without lookahead that a `ref` in a pattern context
> must be the start of a binding pattern, not the start of an expression
> pattern.

Normally an argument to a non-`ref` parameter should not be marked `ref`, but it
is allowed in a generic context where the parameter may sometimes be `ref`.

Expression operators will mostly not take `ref` parameters, with these
exceptions:

-   [the address-of operator](/docs/design/expressions/pointer_operators.md)
    `&`;
-   the first operand of
    [the indexing operator](/docs/design/expressions/indexing.md) `[`...`]`; and
-   [the member access operator](#use-case-member-binding-interfaces) introduced
    in
    [proposal #3720: "Member binding operators"](https://github.com/carbon-language/carbon-lang/pull/3720)
    `.`.

The statement operators now use `ref` instead of pointers:

-   the left-hand operand of [assignment operators](/docs/design/assignment.md)
    such as `=` and `+=`.
-   [the `++` and `--` operators](/docs/design/assignment.md).

Even in these cases, the arguments will not be marked with `ref` at the call
site. (Generally the `ref` parameter is the `self` parameter, and so wouldn't be
marked. The exception is `BindToRef`, but we don't want to mark its argument
with `ref`.)

As an _experiment_, we are saying a pointer formed by taking the address of a
`ref` bound name is LLVM-`captures(none)` and LLVM-`noalias`. This means that
while a `ref` parameter could be passed into a function by address, the
restrictions also allow a "move-in-move-out" approach (once we define the move
operation), assuming it is not [marked `bound`](#bound-parameters). The intent
here is to leave the door open to a calling convention using registers and less
indirection for small-enough objects.

This means that the following code is invalid:

carbon fn F(ref a: i32, ref b: i32) -> bool;

fn G() -> bool { var v: i32 = 1; return F(ref v, ref v); }


Enforcing this restriction will be part of the memory safety story. Until then,
doing this is erroneous behavior. This
[means](#no-optimization-on-erroneous-behavior) that the compiler won't use
those LLVM attributes unless the compiler can itself prove that the restrictions
hold.

### `ref` and `val` returns

The return of a function can optionally be marked `ref` or `val`. These control
the category of the call expression invoking the function, and how the return
expression is returned.

carbon var global: i32 = 2; fn ReturnRef() -> ref i32 { // ❌ Invalid: return 2;

// ✅ Valid: return a reference expression with // sufficient lifetime. return global; } // Call ReturnRef and use the resulting reference. ReturnRef() += 3; Assert(global == 5);

// Result of ReturnRef can be bound using a ref // binding. fn AddFive() { let ref r: i32 = ReturnRef(); r += 5; } AddFive(); Assert(global == 10);

fn ReturnVal() -> val i32 { return 2; } // ReturnVal() is a value expression. let l: i32 = ReturnVal();

// Returning an initializing expression is the // default. fn ReturnDefault() -> i32 { return 2; } // ReturnDefault() is an initializing expression. var j: i32 = ReturnDefault();

// Use var to explicitly specify returning an // initializing expression. fn ReturnVar() -> var i32 { return 2; } // ReturnVar() is the same as ReturnDefault().


-   A call to a function declared `-> ref T` is a durable reference expression.
    The generated code for that function will return the address of a `T`
    object.
-   A call to a function declared `-> val T` is a value expression. The function
    will return the value representation of `T`. Since values have no address,
    the value representation may be returned in registers.
-   The behavior of a call to a function declared `-> T` is unchanged. It is an
    initializing expression, returning in place or by copy depending on the
    initializing representation of `T`. This is the same behavior as `-> var T`.
-   The behavior of `auto` as the return type is unchanged, but now supports an
    optional `ref`, `val`, or `var` between the `->` and `auto`. `-> auto`
    continues to return an initializing expression, as does `-> var auto`.
    `-> val auto` returns a value expression, and `-> ref auto` returns a
    durable reference expression.
-   Using `=>` to specify a return continues to return an initializing
    expression, as before. See
    [this relevant alternative considered](#-infers-form-not-just-type).

A function may have multiple returns, each with their own marker, by using a
tuple or struct compound return form.

carbon fn TupleReturn() -> (val bool, ref i32, C) { return (true, global, {.x = 3}); }

fn StructReturn()

-> {.a: val bool,
    .b: ref i32,
    .c: C} {

return {.a = true,

      .b = global,
      .c = {.x = 3}};

}


If the return of a function may reference the storage of one or more parameters
to the function, those parameters must be marked `bound`. This allows the
compiler to diagnose if the function's return is used after the lifetime of the
`bound` parameter ends. The semantics of `bound` are intended to match the
[`clang::lifetimebound` attribute](https://clang.llvm.org/docs/AttributeReference.html#id8).

carbon fn Member(bound ref c: C) -> ref i32 { return c.x; }

// Lifetime of a pointer includes the lifetime // of what it points to. fn Deref(bound p: i32*) -> ref i32 { return *p; }

fn Both(bound pc: C*) -> ref i32 { return p->x; }

fn Invalid1() -> ref i32 { var x: i32 = 4; // ❌ Error: returning reference to x // whose lifetime ends when this function // returns. return x; }

fn Invalid2() -> ref i32 { var c: C = {.x = 1}; // ❌ Error: returning reference bound to c // whose lifetime ends when this function // returns. return Member(c) }


The address of a `bound ref` parameter is the
[LLVM attribute `captures(ret: address, provenance)`](#background) instead of
[`captures(none)`](#background).

## Details

The intent is that we would encourage using references instead of pointers when
possible. Their benefits are related to their limitations, so to get those
benefits we should use them when a use is restricted enough to be within those
limitations.

### Compound return forms and patterns

Mirroring the [tuple](/docs/design/pattern_matching.md#tuple-patterns) and
[struct](/docs/design/pattern_matching.md#struct-patterns) pattern forms, we
also support tuple and struct return forms.

carbon // -> begins a "return form" fn F() -> ;

// Within any return form, if the first token is // val, ref, var, (, or {, it is not // treated as type expression:

// Value return, with type as specified fn Val() -> val

// Reference return, with type as specified fn Ref() -> ref

// Initializing return, with type as specified fn Var() -> var

// Tuple compound return, with a list of // return forms. fn TupleCompound() -> ( , ... ) // Tuple return, with a list of type // expressions. Used if all members of the // list are type expressions. fn Tuple() -> ( , ... )

// Struct compound return, with a mapping from // designators to return forms. fn StructCompound()

-> { .<id>: <return-form>, ... }

// Struct return, used if all of the members // are type expressions. fn Struct() -> { .: , ... }

// Otherwise, implicit var means returns // an initializing expression. fn Other() -> 


Note that in the absence of `val`, `ref`, and `var` keywords, the implicit `var`
is placed in the outermost position, minimizing the number of primitive forms
returned. So `fn F() -> (i32, i32)` means `fn F() -> var (i32, i32)` not
`fn F() -> (var i32, var i32)`. Generally the `var` is left off if not required,
and so will be rare in return forms, to minimize confusion with `val`.

carbon fn TupleReturn(...)

-> (val bool, ref i32, C);

// Equivalent to: // -> (val bool, ref i32, var C);

let (a: bool, ref b: i32, var c: C)

= TupleReturn(...);

fn StructReturn(...)

-> {.a: val bool,
    .b: ref i32,
    .c: C};

// Equivalent to: // -> {.a: val bool, // .b: ref i32, // .c: var C};

// Binds to the names x, y, z: let {.a = x: bool,

 .b = ref y: i32,
 .c = var z: C} = StructReturn(...);

// Binds to the names a, b, c: let {a: bool,

 ref b: i32,
 var c: C} = StructReturn(...);

// Above two can be mixed, binding to // names a, y, z. let {a: bool,

 .b = ref y: i32
 .c = var z: C} = StructReturn(...);


Only types are allowed after a `-> val`, `-> ref`, or `-> var`, not a compound
return form. Examples:

carbon // Returns a tuple of type // (bool, f32, C, i32). fn OneTupleReturn(...)

-> (bool, f32, C, i32);

// Returns a compound tuple form fn CompoundReturn(...)

-> (bool, val f32);

// Equivalent to: // -> (var bool, val f32);

// ❌ Invalid, can't specify ref inside // of val. fn Invalid(...) -> val (bool, ref f32);


The compound return forms may be nested, as in:

carbon fn CompoundInParens(...)

-> ({.a: bool, .b: val f32}, C, ref i32);

// Equivalent to: // -> ({.a: var bool, .b: val f32}, var C, ref i32);

let ({.a = var x: bool, .b = val y: f32},

 var c: C, ref d: i32) = CompoundInParens(...);

// or without renaming: let ({var a: bool, b: f32},

 var c: C, ref d: i32) = CompoundInParens(...);

// Contrast with a compound tuple form containing // a struct type (not compound): fn StructInParens(...)

-> ({.a: bool, .b: f32}, C, ref i32);

// Equivalent to: // -> (var {.a: bool, .b: f32}, var C, ref i32);

fn CompoundInBraces(...)

-> {.a: bool, .b: (val f32, C), .c: ref i32};

// Equivalent to:

-> {.a: var bool, .b: (val f32, var C), .c: ref i32};

let {a: bool,

 .b = (x: f32, var y: C),
 ref c: i32} = ParensInBraces(...);

// Contrast with a compound struct form containing // a tuple type (not compound): fn TupleInBraces(...)

-> {.a: bool, .b: (f32, C), .c: ref i32};

// Equivalent to:

-> {.a: var bool, .b: var (f32, C), .c: ref i32};


This feature is intended to support cases like `enumerate` that will want to
return a value for the index but a reference to the element of the sequence
being enumerated.

### Nested binding patterns

Since a `ref` binding may only bind to a durable reference expression, it can't
be used to bind the result of a function returning an initializing expression.
However, if the initializing expression is bound to a `var`, any nested patterns
are reference binding patterns bound to the subobject, following
[proposal #5164: "Updates to pattern matching for objects"](https://github.com/carbon-language/carbon-lang/pull/5164).

For example:

carbon fn F() -> (bool, (C, i32)); let (b: bool, var (c: C, i: i32)) = F();


is equivalent to:

carbon fn F() -> (bool, (C, i32)); let (b: bool, var v: (C, i32)) = F(); let ref c: C = v.0; let ref i: i32 = v.1;


Note that `ref` is disallowed inside `var` since that would be redundant.

### Mututation restriction on objects bound to a value

Mutation of objects with a non-copy-value representation in an active value
binding ("borrowed objects") is erroneous behavior.

-   Our plan is to prevent mutation of borrowed objects in Carbon's strict safe
    dialect.
    -   We should only relax our stance here and consider making such mutation
        _allowed_ if we discover difficulty with this that we cannot overcome.
    -   But we _should_ revisit the underlying idea of mutation being erroneous
        if enforcing it in the strict mode proves fundamentally untenable due to
        ergonomic costs.
-   There will always be the potential for unchecked code, either unsafe Carbon
    code or C++ code by way of interop, to mutate a borrowed object, hence the
    need to define it as erroneous behavior.
-   There is no need to ever make it anything more than erroneous behavior, see
    below.
-   If we can prove the mutation doesn't occur, then we can use that to optimize
    under "as-if", and we don't need anything else.
-   We are deferring the decision of whether strict enforcement is enabled in
    Carbon's current C++-friendly mode, when not explicitly marking the code as
    "unsafe."

This was
[discussed 2025-05-22](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.uot97ukynlsi)
and then made the subject of
[leads issue #5524](https://github.com/carbon-language/carbon-lang/issues/5524).

### No optimization on erroneous behavior

The Carbon compiler should not optimize on erroneous behavior, ever, unless the
compiler literally proves that it does not occur, ever. In which case, we don't
need any license to start optimizing on this, as it falls under "as-if".

The fact that undefined behavior ("UB",
[cppreference](https://en.cppreference.com/w/cpp/language/ub.html),
[wikipedia](https://en.wikipedia.org/wiki/Undefined_behavior)) provides "as-if"
_without_ a proof is precisely the risk of using UB for any semantics, and why
we don't use it here and elsewhere we use erroneous behavior.

### `bound` parameters

It is erroneous behavior to return something that references a local object that
won't live once the function returns, even if it is a parameter marked `bound`.
Local objects include local variables, temporary objects, and `var` parameters.

carbon fn Invalid1() -> i32* { var x: i32 = 4; // ❌ Invalid. return &x; }

fn Invalid2(bound x: i32) -> ref i32 { var y: i32 = x; // ❌ Invalid. return y; }

// ✅ Valid fn Valid1(bound p: i32*) -> ref i32 { return *p; }

fn Invalid3(bound var x: i32) -> ref i32 { // ❌ Invalid: lifetime of var parameter // ends when function returns. return x; }

class ReturnMember { // ✅ Valid fn ValidRef[bound ref self: Self]() -> ref i32 {

return self.m;

}

// ❌ Invalid: can't return reference to value. fn InvalidVal[bound self: Self]() -> ref i32 {

return self.m;

}

// ❌ Invalid: var self lifetime ends. fn InvalidVar[bound var self: Self]()

  -> ref i32 { return self.m; }

var m: i32; }

class DerefPointerMember { // ✅ Valid fn ValidRef[bound ref self: Self]() -> ref i32 {

return *self.pm;

}

// ✅ Valid fn ValidVal[bound self: Self]() -> ref i32 {

return *self.pm;

}

// ✅ Valid fn ValidVar[bound var self: Self]()

  -> ref i32 { return *self.pm; }

var pm: i32*; }


Otherwise, `bound` parameters and global variables are the sources of storage
that can be referenced by a return, but need not be referenced, particularly not
on every code path.

carbon // Result references r if b is true, and p // otherwise. Valid as long as both are marked bound. fn Conditional(b: bool, bound ref r: C, bound p: C*)

-> ref C {

if (b) {

return r;

} else {

return *p;

} }


The parameters of functions defined in an interface may also be marked as
`bound`. The `impl` of that interface for a type can omit occurrences of `bound`
from the interface, but cannot add new ones.

carbon interface I { fn F[bound ref self: Self]

  (a: Self, bound b: Self, bound c: Self*)
  -> ref Self;

}

impl C1 as I { // ✅ Valid: matches interface fn F[bound ref self: Self]

  (a: Self, bound b: Self, bound c: Self*)
  -> ref Self;

}

impl C2 as I { // ✅ Valid: proper subset of bound params fn F[ref self: Self]

  (a: Self, bound b: Self, c: Self*)
  -> ref Self;

}

impl C2 as I { // ❌ Invalid: a is not bound in I.F. fn F[ref self: Self]

  (bound a: Self, b: Self, c: Self*)
  -> ref Self;

}


Like `[[clang::lifetimebound]]` in C++, `bound` does not affect semantics or
calling conventions, just what code is legal. This helps avoid mismatches
between typechecking against the signatures in an interface when the `impl`
functions are different. Exception: the question of whether `bound` affects the
lifetime of temporaries is [future work](#temporary-lifetimes).

Note that all combinations of a `val`/`ref`/default return can be bound to a
value/`ref`/`var` parameter. Examples:

carbon fn RefToVal(bound ref x: C) -> val D { return x.d; } fn ValToRef(bound y: C) -> ref D { return y.ptr; } fn VarToRef(bound var p: i32) -> ref i32 { return p; } fn VarToDefault(bound var p: i32) -> i32* { return p; }


For full safety, we need each bound parameter to be immutable for the duration
of the lifetime of the returned result. However, the objective for now is only
matching `[[clang::lifetimebound]]`, which has the goal of preventing some
classes of bugs, not full memory safety. We will reconsider this with the memory
safety design.

Clang's `lifetimebound` attribute also only applies to the immediately pointed
to objects (by pointers or reference parameters, or pointers or reference
subobjects of an aggregate parameter). We suggest a simpler, transitive model
here that is more restrictive but should be compatible. That said, pinning down
the exact and firm semantics of `bound`, especially in these complex cases, is
deferred to the full memory safety design as well.

### How addresses interact with `ref`

The address of a `ref` binding is `noalias` and either `captures(none)` or
`captures(ret: address, provenance)`, depending on whether the binding is marked
`bound`.

-   `noalias` means like C `restrict`; you can't observe mutations through
    aliases; mutation through a restricted pointer is not observable through
    another pointer
-   `captures(none)` means there is no transitive escape: you can pass a
    nocapture pointer to another nocapture function, but you can't store to
    memory or return
-   `captures(ret: address, provenance)`: is like `captures(none)` but may be
    referenced by a return.

The combination of `noalias` and `captures(none)` semantics are the minimum for
the "move-in-move-out" optimization. But this condition is hard to check, so
safe code will use a stricter criteria. Unsafe code will be required to adhere
to just the `noalias` restrictions, but will not be checked (except possibly by
a sanitizer at runtime). The details here will be tackled as part of the memory
safety design.

Optimizations will only be performed based on information that is enforced or
checked by the compiler, so these attributes won't be passed to LLVM unless
their requirements can be established. This avoids introducing undefined
behavior, which we particularly don't want to do in situations where C++
doesn't.

The goal of these rules it to nudge us towards function boundaries that don't
constructively create aliasing in their API boundary and don't capture pointers
unnecessarily.

These restrictions are experimental, and we should keep track of everything we
end up needing to do to work around these restrictions so any reconsideration
can be properly informed.

### Improved interop and migration with C++ references

We expect this to improve interop and migration by allowing significantly more
interface similarity between Carbon and C++. Previously, many things in C++ that
used references on interface boundaries would be forced to switch to pointers.
This adds ergonomic friction both at a basic level because of the forced change
but also a deeper level because it will make it significantly harder to see the
parallel usage across the boundary between C++ and Carbon. With reference
bindings, the vast majority of this dissonance will be removed.

This does create a migration concern, raised in
[open discussion on 2025-05-01](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.dffumsu6wzlc),
that the `nocapture` and `noalias` modifiers don't match C++ restrictions,
particularly on the `this` parameter that we are going to require migrate to
`ref self`. We may have to add back in `addr` to allow a different pointer type
for those cases.

> **Future work:** Addressing how we model the various kinds of C++ references
> that Carbon code may need to interact with is
> [something we are actively considering](https://docs.google.com/document/d/1l5TbNuwZEcwm96ejGPLn9GdoQO1fByUW0tFRLU9BqXE/edit?tab=t.0)
> and will be tackled in a future proposal.

### Part of the expression type system, not object types

Much like value/`val` and `var` bindings, `ref` binding and the new return forms
are are part of the type system, but only through expression categories,
patterns (function parameters and so on), and returns. Specifically, we don't
expect them to be part of the _object types_ in Carbon. Like value bindings, we
retain a great deal of implementation flexibility around layout, and the
specifics of how they are lowered.

This specifically means we will need to incorporate `ref` bindings into the
`Call` interface and we will be adding complexity there that will need to be
handled by overloading. The changes to the `Call` interface is future work, and
overloading, once we add support, will need to carry additional complexity to
handle `ref`.

### Interaction with `returned var`

The rule is: `returned var` may only be used when there is a single atomic
return form, and it is the default `var` category.

carbon // ✅ Allowed fn F(...) -> V { returned var v: V = ...; // ... return var; }

fn F(...) -> {var .a : T} { // ❌ Invalid: composite form returned var ret: T = ...; // ... }

fn F(...) -> val T { // ❌ Invalid: value return returned var ret: T = ...; // ... }


We can revisit and expand this later if this does not handle use cases we would
like to support.

### Use case: `Deref` interface

To support customization of the prefix-`*` dereferencing operator, we introduce
the `Deref` interface.

carbon interface Deref { let Result:! type; fn Op[bound ref self: Self]() -> ref Result; }

final impl forall [T:! type] T* as Deref { where Result = T; fn Op[bound self: Self]() -> ref T

  = "builtin.deref";

}


Then `*p` is rewritten to `p.(Deref.Op)()`, and `p->m` is rewritten to
`p.(Deref.Op)().m`. For example, this might be used by a smart pointer:

class SmartPtr(T:! type) { fn Make(p: T*) -> Self { return {.ptr = p}; } impl as Deref {

where Result = T;
fn Op[bound ref self: Self]() -> ref Result {
  return *self.ptr;
}

} private var ptr: T*; }


### Use case: indexing interfaces

[Proposal #2274: "Subscript syntax and semantics"](https://github.com/carbon-language/carbon-lang/pull/2274)
added the interfaces used to support indexing with the subscripting operator
`[`...`]`. We change these in the following ways:

-   The `addr self` parameters are changed to `bound ref self`, to allow the
    result to reference the `self` object.
-   The `At` method returns by `val`.
-   The `Addr` methods are renamed `Ref` and return a reference instead of a
    pointer that is automatically dereferenced.

[This proposal's PR](https://github.com/carbon-language/carbon-lang/pull/5434)
makes those changes to the
[indexing design](/docs/design/expressions/indexing.md).

### Use case: member binding interfaces

The member binding interface used for reference expressions from
[proposal #3720](https://github.com/carbon-language/carbon-lang/pull/3720) can
now be changed to use references instead of pointers.

Before:

carbon // For a reference expression x with type T // and an expression y of type U, x.(y) is // *y.((U as BindToRef(T)).Op)(&x) interface BindToRef(T:! type) { extend impl as Bind(T); fn Opself: Self -> Result*; }


After:

carbon // For a reference expression x with type T // and an expression y of type U, x.(y) is // y.((U as BindToRef(T)).Op)(x) interface BindToRef(T:! type) { extend impl as Bind(T); fn Opself: Self -> ref Result; }


Similarly, the `BindToValue` interface is changed to use a `val`/value return,
potentially avoiding a copy of large objects.

Before:

carbon interface BindToValue(T:! type) { extend Bind(T); fn Opself: Self -> Result; }


After:

carbon interface BindToValue(T:! type) { extend Bind(T); fn Opself: Self -> val Result; }


### Use case: class accessors

A `ref` return can be used to expose the state of an object in a way that can be
mutated:

carbon class Four { fn Getself: Self -> i32 {

Assert(i >= 0 and i < 4);
return self.m[i];

} fn GetMutbound ref self: Self -> ref i32 {

Assert(i >= 0 and i < 4);
return self.m[i];

} private var m: array(i32, 4); }

var x: HasMember = {.m = (0, 2, 4, 6)}; x.GetMut(2) += 1; fn Check(y: Four) { Assert(y.Get(2) == 5); } Check(x);


**Future work**: this will in the future often be done with an overloaded
method, as in:

carbon class Four { overload Access {

fn [bound ref self: Self](i: i32) -> ref i32 {
  Assert(i >= 0 and i < 4);
  return self.m[i];
}
fn [self: Self](i: i32) -> i32 {
  Assert(i >= 0 and i < 4);
  return self.m[i];
}

} private var m: array(i32, 4); }

var x: HasMember = {.m = (0, 2, 4, 6)}; x.Access(2) += 1; fn Check(y: Four) { Assert(y.Access(2) == 5); } Check(x);


This may be a common enough use case that we will want to introduce a dedicated
syntax:

carbon class HasMember { fn Accessbound ref? self: Self -> ref? i32 {

Assert(i >= 0 and i < 4);
return self.m[i];

} private var m: array(i32, 4); }


### Type completeness

Not a change by this proposal, but note that our existing rules will require the
type in a `ref` binding to be complete in situations where it would not need to
be if you were using a value binding with a pointer type instead. We may need to
change this in the future to match C++ which treats reference types more like
pointer types for completeness purposes.

After this change, a `ref` binding to type `T` will require `T` to be complete
in the same situations that other bindings to type `T` require `T` to be
complete.

### Pointer value representation

Purely as a change in syntax, the way to specify that
[the value representation of a class](/docs/design/values.md#value-representation-and-customization)
uses a pointer is changed from writing `const Self *` to `const ref`.

## Future work

### Temporary lifetimes

For safety, we need bindings and returns that reference storage to only be used
while that storage remains valid. When the referenced storage is owned by a
temporary, we have a choice to either control the lifetime of the temporary or
diagnose when the lifetime of the temporary is insufficient. Deciding on our
policy is future work.

Note that in many cases we can explicitly provide storage in a variable instead
of referencing a temporary. For example, using
`var x: ... = ReturnsATemporary();` instead of
`let ref x: ... = ReturnsATemporary();`. This won't apply in all situations,
though, such as temporaries that are reachable transitively through pointers.

### `ref` bindings in lambdas

We have already identified
[future work to support reference captures in lambdas as part of proposal #3848](/proposals/p3848.md#future-work-reference-captures).
This might be a reason to support `ref` bindings as fields of objects, with all
the restrictions that comes with that.

### Interaction with effects

We still need to determine how references and the other return types interact
with effects, like `Optional`, errors, co-routines, and so on. For example, we
don't want to give up the benefits of being able to directly return a reference
when a function has an error path.

It is unclear if this will mean putting references into the object type system,
but we may be able to handle this with additional types or the ability to
customize return representations. For example, we might have an alternate
version of the `Optional` type that holds a reference:

carbon class OptionalRef(T:! type) { fn Make(bound ref r: T) -> Self {

return {.p = &r};

} fn MakeEmpty() -> Self {

return {.p = Optional(T*).MakeEmpty()};

} fn HasValue[self: Self]() -> bool {

return p.HasValue();

} fn Get[bound ref self: Self]() -> ref Result {

Assert(self.HasValue());
return *self.p.Get();

}

private var p: Optional(T*); }


### More precise lifetimes

More precise lifetime tracking will be considered with the memory safety design.
For example, the `bound` approach does not distinguish different components of a
compound return, or different parts of a parameter object that might have
different lifetimes.

### Combining with compile-time

We plan to support references to compile-time state when executing a function at
compile time. That will be part of a future proposal.

### Interaction with `Call` or other interfaces

For now, `ref` is not represented in the `Call` interface introduced in
[proposal #2875: Functions, function types, and function calls](https://github.com/carbon-language/carbon-lang/pull/2875).
This will be tackled together in a future proposal with other aspects of
bindings not represented by the type, such as `var` and compile-time, along with
being generic across these aspects of bindings.

### Destructuring assignment

Having more support for multiple returns from a function opens the question of
how to do different things with the different returns. We may want a syntax for
saying some of the returns are bound to new names, and some are used in
assignments to existing variables. One possibility would be to have some pattern
syntax for re-initializing an existing object, as in:

carbon fn F() -> (-> bool, ->T); fn G() { var x: T = ...; Consume(~x); let (b: bool, init x) = F(); // Continue to use x... }


This was discussed in
[the #syntax channel on Discord on 05-19-2025](https://discord.com/channels/655572317891461132/709488742942900284/1374126123595727000).

### Restore `addr`

There are two reasons we might restore `addr` as an alternative to `ref` for the
implicit `self` parameter:

-   As a way to express uses of `self` that we want to disallow for `ref`
    bindings generally but need an escape hatch for migrated C++ code that
    relies on these patterns.
-   To allow the `self` parameter to use one of the pointer semantics we create
    as part of the upcoming memory safety design, that can't be achieved with
    `ref`.

## Rationale

This proposal tries to advance these [Carbon goals](/docs/project/goals.md):

-   [Performance-critical software](/docs/project/goals.md#performance-critical-software)
    -   Having a "move-in-move-out" option as a calling convention is a
        potential performance improvement for using `ref` parameters instead of
        pointers.
    -   Giving additional options for the return convention gives opportunities
        for improved performance. Having this set by explicit return markings is
        about giving control and predictability to the code author.
-   [Code that is easy to read, understand, and write](/docs/project/goals.md#code-that-is-easy-to-read-understand-and-write)
    -   `ref` bindings and returns avoid the ceremony of round-tripping through
        pointers.
-   [Practical safety and testing mechanisms](/docs/project/goals.md#practical-safety-and-testing-mechanisms)
    -   Checking that reference bindings are not dangling is important for
        avoiding use-after-free bugs.
    -   `bound` markings on parameters to allow safety equivalent to Clang's
        `[[clang::lifetimebound]]` when returning a reference.
-   [Interoperability with and migration from existing C++ code](/docs/project/goals.md#interoperability-with-and-migration-from-existing-c-code)
    -   Including references in Carbon allows for less mismatch for C++ code
        using references.

## Alternatives considered

These ideas were discussed in open discussion on:

-   [2025-05-01](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.dffumsu6wzlc)
-   [2025-05-06](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.s42g5iv67d3c)
-   2025-05-07
    [a](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.sfx9d7ltud5)
    [b](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.4zbo49wg5rmk)
-   [2025-05-08](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.vdognq1upsf5)
-   [2025-05-12](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.1mjh6unumnwu)
-   [2025-05-13](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.bdznj2d0by2g)
-   [2025-05-14](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.52tb7l2he343)

They were also discussed in the
[#pointers-and-references channel in Discord starting 2025-05-05](https://discord.com/channels/655572317891461132/753021843459538996/1369085231038074901),
and
[#syntax on 2025-05-14](https://discord.com/channels/655572317891461132/709488742942900284/1372285365162872943).

### No `ref`, only pointers

The rationale to add `ref` instead of staying with pointers was discussed on
[2025-05-01](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.dffumsu6wzlc).
In addition to the motivating problems given in
[the "Problem" section](#problem), that discussion included some additional
depth to the reasons to add reference bindings.

There is a tension between wanting to have mutating expressions and only having
pointers. You need some concept like a reference in order to mutate an object
with an expression. The question is how small a box the references are
restricted to, and where the line is drawn. C has lvalues, which contain
references but are restricted to a quite small box. Reference bindings
specifically are about keeping a small box around references while still adding
enough expressivity to support our use cases. We have started with a model
similar to C, but it fell down when it comes down to composition. Decomposing an
expression into pieces loses the tools the expression provided to you. The
missing tool for that was reference bindings.

We saw how much we were leaning on value bindings. The asymmetry between having
value binding but not reference bindings when have value expressions and
reference expressions was creating pressure. For example, when accessing members
of an object, we had to escape to pointers in that operator.

One downside of this change is that before indirections were more visible in the
code.

Also, this does fundamentally mean that we now have another kind of "pointer",
potentially adding complexity to any memory-safety story. However, this ship
already sailed to some extent with value bindings. Fundamentally, bindings are
allowed to have pointer-like semantics from a lifetime perspective, and so will
need to be considered as a pointer-like thing as we build out lifetime safety.

### Remove pointers after adding references

If we removed pointers after adding references, we would need something
rebindable for assignable objects. The viable path forward without separate
pointers and references is to have something rebindable like pointers but
automatically dereferenced like references, which is the approach Rust takes.
See
[this comment on issue #5261](https://github.com/carbon-language/carbon-lang/issues/5261#issuecomment-2786462775).

One of the features of a reference is what it cannot do, and we would have to
remove those restrictions to be able to satisfy the pointer use cases with
references.

### Allow `ref` bindings in the fields of classes

A type with reference binding fields would need a lot of restrictions since
reference bindings are not assignable. We did not see enough motivation to put
references into objects, given the complexity that it would introduce, so we are
keeping references out of types for now. This could change to support lambda
reference captures.

### No call-site annotation

This question was discussed on
[2025-05-07](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.sfx9d7ltud5).

We decided that the marking is not about lifetime, but ability to mutate. A
`val` may reference an object in a similar way to a `ref`, restricting
operations on the original object, but we are not going to mark `val`s since
those restrictions are enforced by the compiler. We thought the ability to
mutate, though, was something important enough to highlight to readers of the
code, even at the expense of extra work for the writer.

Swift `inout` parameters are
[marked at caller with an `&` before the argument](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/functions/#In-Out-Parameters).
Jordon Rose has published
[a regret](https://belkadan.com/blog/2021/12/Swift-Regret-inout-Syntax/) that
they didn't use `inout` to mark the argument instead of `&`.

On the other hand, not marking is not known to be a source of bugs.

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

### 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`. This was considered in
[leads issue #5523](https://github.com/carbon-language/carbon-lang/issues/5523),
which provided this rationale:

> I feel like this would often be used for non-local mutation due to it
> fundamentally deporting mutable value semantics and instead having reference
> semantics. Unlike the local mutation, that seems more worthwhile to have
> incentives around minimizing.
>
> However, this seems the easiest of all to revisit later if we discover that
> the added verbosity in practice is costing more than is worth any improvements
> from explicitly flagging mutable reference semantics, or if we find code is
> reaching for antipatterns due to the incentive.

In addition,
[this comment on leads issue #5522](https://github.com/carbon-language/carbon-lang/issues/5522#issuecomment-2972029100)
argued that it would be more consistent for `ref` and `val` to only apply to
bindings, and not introduce patterns, like `let` and `var`.

### Allow immutable value semantic bindings nested within variable patterns

This was considered in
[leads issue #5523](https://github.com/carbon-language/carbon-lang/issues/5523),
which provided this rationale:

> While it may be an obvious point of orthogonality, I think it adds choice
> without sufficient motivation, and even _having_ that choice does add some
> complexity to the language.
>
> It also seems like we could add this later if there is sufficient demand when
> we have larger usage experience body to pull from with the rest of the Carbon
> language. Currently, the affordance that feels more natural to me is what we
> have.

> I think we're happy to see motivating use cases and revisit this. At the
> moment, we've just not seen motivating use cases -- everything has seemed a
> bit too contrived.

### Remove `var` as a top-level statement introducer

This was considered in
[leads issue #5523](https://github.com/carbon-language/carbon-lang/issues/5523),
which provided this rationale:

> Locals are important, frequent, and frequently mutable. I don't think forcing
> varying locals to go through `let var` for orthogonality aids readability
> enough to offset the verbosity cost of added keywords on a reasonably common
> pattern.
>
> I'm still currently in the position that locally owned objects being mutable
> should not be "discouraged" or "disincentivized" by the language. And I think
> adding artificial incentives to try and avoid needing a mutable local variable
> would either have no effect beyond verbosity, or if it _did_ have effect, it
> wouldn't be a net positive effect due to code being written in a less
> straightforward manner in order to avoid mutation.
>
> To be clear, this is based on intuition and judgement based on my experience,
> not in any way based on data or specific motivating examples. I can imagine
> data or evidence or even a new perspective changing my position here, but so
> far the discussion we've had haven't done that.

### `ref` as a type qualifier

The big concern is that any effect that is represented by a type, like
`Optional` or `Result`, will want to compose with reference returns. This could
be done by allowing `ref` to create an object type that could be used as a
parameter to those, as in `Optional(ref T)`, but
[we are trying to avoid going down that path](https://github.com/carbon-language/carbon-lang/issues/5261#issuecomment-2790421894).
We have [future work](#interaction-with-effects) to tackle this problem
specifically.

There was also
[a concern that we might need `ref` types to represent argument lists with tuples](https://github.com/carbon-language/carbon-lang/issues/5261#issuecomment-2790506515),
but tuples already can't represent `var` or compile-time parameters. We have
other plans for this, instead of trying to stretch tuples to encompass these use
cases.

We also noted that including references in the type system led to a number of
inconsistencies in C++, such as no there not being references of references.

### `bound` would change the default return to `val`

We considered saying that `bound` would change the default return to use the
`->val` return convention. This was discussed on
[2025-05-01](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.dffumsu6wzlc)
and
[2025-05-08](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.vdognq1upsf5).
The idea is that `val` is expected to be efficient, so we should encourage using
it, but we can't always use `val`, since some types have a reference value
representation, but `bound` alleviates that concern.

Once we realized that `bound` is relevant for all return conventions, we
reconsidered that approach, since has a number of concerns:

-   Changing defaults is action at a distance, changing the behavior without
    changing the code in the relevant location.
-   We don't want to have to make changes to the return category of copy-paste
    of a function from an interface to an `impl` of it when removing `bound`.
-   Lifetimes in Rust and Clang's `[[clang::lifetimebound]]` don't change
    calling conventions, only what code is valid.

Going with an approach where less depends on `bound` makes sense for now, since
we are going to reconsider these issues as part of our upcoming memory safety
work.

### Other return conventions

We also considered other conventions for returning from functions, in
[a comment on #5434](https://github.com/carbon-language/carbon-lang/pull/5434/files#r2099145225),
on
[2025-05-08](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.vdognq1upsf5)
and on
[2025-05-12](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.1mjh6unumnwu),
most notably:

-   **in place**: This convention was like `->`, but always using the "in place"
    convention where the caller allocates storage and provides the callee with
    its address, the callee initializes the storage at that address, and the
    caller is responsible for destroying after the return.
-   **var without storage**: The callee returns a pointer to the storage of a
    subobject of a `bound var` parameter, that caller is then responsible for
    destroying. A call to this function is reference expression, but with
    additional responsibility to destroy.
-   **hybrid**: If the type has a copy value representation or trivial
    destructive move then return the object representation directly; otherwise
    caller passes a pointer and callee initializes it.

There were also some variations on what the conditions for returning in
registers using the default return convention.

We seriously considered "var without storage", but the fact that it couldn't
reliably be used to initialize a variable, particularly in the middle of an
object, meant it did not seem valuable enough to include.

It seemed more valuable to support the "in place" return convention. That return
form allows you to guarantee knowing the address of the object being
constructed, and was a good match for `returned var`. However, we realized that
`var` declarations shouldn't always be associated with in-memory storage, in
particular for types that may be trivially moved. For example, a `var` parameter
with the C++ type `std::unique_ptr<T>` should be passed in registers. A function
returning a `std::unique_ptr<T>` in place would not be as efficient as returning
it by moving it into registers.

### `return var` with compound return forms

We considered various syntax options on
[2025-05-12](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.1mjh6unumnwu),
but none of them seemed good enough to justify inclusion at this time:

carbon fn F(...) -> (ref R, val L, V) { // No longer a var being returned. Ideally these // shouldn't have to be initialized together. returned ??? (ref r: R, val l: L, var v: V) = ...? return var; }

// We could restrict to one var return component, // but this is a lot of machinery for a small increase // in expressiveness and applicability. fn F(...) -> (ref R, val L, V) { returned var v: V = ...; let l: L = ...; return (*r, l, var); }

fn F(...) -> (ref R, val L, V) { // These don't have the right category, and ideally // shouldn't have to be initialized together. returned var ret: (R, L, V) = ...? return var; }

fn F(...) -> (ref R, val L, V) { returned var (_, _, var v: V) = ; } 


There was another approach we considered for `returned var` originally:

carbon fn F(...) -> (ref R, val L, v1: V1, var v2: V2) { // ... // Must use the same names for the var (implicit or explicit) returns // with bound names. return (r, l, v1, v2); }


But this had downsides that still apply:

-   Requires `V1` and `V2` to have unformed states. Otherwise, `v1` and `v2`
    would need be initialized when they are declared.
-   This does not support only having some branches use `return var`.

Our current approach handles our main use case for `returned var`: factory
functions.

We could support an "only `var`s" approach in the future if we want:

carbon fn F(...) -> (var V1, var V2, var V3) { returned (var v1: V1, var v2: V2, var v3: V3) = ...; // ... return var; }


### Other syntax for compound return forms

We considered other options for the syntax of compound return forms on
[2025-05-13](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.bdznj2d0by2g),
[#syntax in Discord on 2025-05-14](https://discord.com/channels/655572317891461132/709488742942900284/1372285365162872943),
and
[2025-05-14](https://docs.google.com/document/d/1Yt-i5AmF76LSvD4TrWRIAE_92kii6j5yFiW-S7ahzlg/edit?tab=t.0#heading=h.52tb7l2he343).
The option of omitting the `->` in each component did not distinguish tuples
from tuple return forms sufficiently:

carbon -> (ref i32, var i32) -> (bool, ref i32)

// Is this a single return of a tuple, or a triple // return using the default return convention? -> (i32, i32, i32)


We also considered an approach where compound return forms would start with
`->?`, but this raised concerns about what the meaning of that syntax would be
and whether we want to expose users to that in cases we might be able to avoid
it.

The original proposed syntax used an arrow `->` in each component of a compound
form.

carbon fn TupleReturn(...)

-> (->val bool, ->ref i32, -> C);

fn StructReturn(...)

-> {->val .a: bool,
    ->ref .b: i32,
    -> .c: C};

```

This avoided ambiguity, but was verbose and visually noisy. An alternative was suggested in discussion on 2025-06-13. This alternative used a default of compound returns for paren (...) and brace {...} expressions, which you could opt out of by using one of the three category keywords such as var to introduce a type expression that would not be considered a compound return.

This had the downside that -> T would be interpreted as -> var T even if T was a tuple type like (i32, i64). However, textually substituting in (i32, i64) in for T to get -> (i32, i64) would instead be interpreted as -> (var i32, var i64).

To overcome this problem, in discussion on 2025-06-16, we switched to the approach from this proposal.

ref parameters allow aliasing

If requiring ref parameters to be noalias ends up being too restrictive, we could instead have the "move-in-move-out" optimization be done only when the compiler can prove it safe. One strategy would be to generate an alternate version of the function that is only used in the cases where the noalias conditions can be shown to hold statically.

let to mark value returns instead of val

This proposal initially used let instead of val to mark immutable value returns. However, let is used, in Carbon and other languages, primarily to bind names. In Carbon, the default binding is a value binding, but that was not considered a close enough to connect the let keyword to value semantics.

There was also a concern about reusing let in multiple contexts to mean different things, and having separate keywords that were only used to mark the category of the binding was deemed better separation of concerns.

We considered making a parallel change to use init instead of var, but this had some problems:

  • By making initializing returns the default, there is little expected usage, so perhaps not worth spending another keyword on.
  • The init keyword would be particularly expensive, because C++ code commonly use that word in APIs.

This question was considered in leads issue #5522.

=> infers form, not just type

There was support for the idea that the => return syntax introduced in proposal #3848 should deduce the form of the return, not just its type. This was discussed in #lambdas on 2025-05-20.

However, trying to infer the expression category from the category of the expression after the => runs into the problem of this often requiring the parameters to be marked bound. A more complicated rule, for example using whether any parameter is marked bound, could be adopted in the future, if the simple rule proves inadequate.

Alternatively, the compiler could infer which parameters should be marked bound in this case. That is something to consider with the memory safety design.