Proposal: 'readonly' for Locals and Parameters

[stephentoub]

(Note: this proposal was briefly discussed in #98, the C# design notes for Jan 21, 2015. It has not been updated based on the discussion that's already occurred on that thread.)

Background

Today, the ‘readonly’ keyword can be applied to fields; this has the effect of ensuring that a field can only be written to during construction (static construction in the case of a static field, or instance construction in the case of an instance field), which helps developers avoid mistakes by accidentally overwriting state which should not be modified. Optimizations are also possible in a compiler based on the knowledge that the field is immutable after construction.

Here’s an example of a class defined with a readonly field. The ‘m_birthDay’ field is explicitly declared by the developer to be readonly, which means any attempt to set it after construction will cause a compile-time error. The ‘FirstName’ and ‘LastName’ properties, which are defined with getter-only auto-props (introduced in C# 6), also result in readonly fields generated implicitly by the compiler, since there’s no need for a field to be writable if there’s no way for code to set it.

public class Person
{
    readonly DateTimeOffset m_birthDay; // readonly field, assigned in constructor

    public Person(string firstName, string lastName, DateTimeOffset birthDay)
    {
        FirstName = firstName;
        LastName = lastName;
        m_birthDay = birthDay;
    }

    public string FirstName { get; }  // getter-only auto-prop, backed by readonly field
    public string LastName { get; }

    public TimeSpan Age => DateTime.UtcNow – BirthDay;
    public string FullName => "\{FirstName} \{LastName}";

    public DateTime BirthDay
    {
        get => m_birthDay;
        set => m_birthDay = value; // Error: can’t assign to readonly field outside of ctor
    }
}

Problem

Fields aren’t the only places developers want to ensure that values aren’t mutated. In particular, it’s common to create a local variable to store temporary state, and accidentally updating that temporary state can result in erroneous calculations and other such bugs, especially when such "locals" are captured in lambdas.

Solution: readonly locals

Locals should be annotatable as ‘readonly’ as well, with the compiler ensuring that they’re only set at the time of declaration (certain locals in C# are already implicitly readonly, such as the iteration variable in a ‘foreach’ loop or the used variable in a ‘using’ block, but currently a developer has no ability to mark other locals as ‘readonly’).

readonly long maxBytesToDelete = (stream.LimitBytes - stream.MaxBytes) / 10;
...
maxBytesToDelete = 0; // Error: can’t assign to readonly locals outside of declaration

This is particularly valuable when working with lambdas and closures. When an anonymous method or lambda accesses local state from the enclosing scope, that state is captured into a closure by the compiler, which is represented by a “display class.” Each “local” that’s captured is a field in this class, yet because the compiler is generating this field on your behalf, you have no opportunity to annotate it as ‘readonly’ in order to prevent the lambda from erroneously writing to the “local” (in quotes because it’s really not a local, at least not in the resulting MSIL). With 'readonly' locals, the compiler can prevent the lambda from writing to local, which is particularly valuable in scenarios involving multithreading where an erroneous write could result in a dangerous but rare and hard-to-find concurrency bug.

readonly long index = …;
Parallel.ForEach(data, item => {
    T element = item[index];
    index = 0; // Error: can’t assign to readonly locals outside of declaration
});

Solution: readonly parameters

As a special form of local, parameters should also be annotatable as 'readonly'. This would have no effect on what the caller of the method is able to pass to the parameter (just as there’s no constraint on what values may be stored into a ‘readonly’ field), but as with any ‘readonly’ local, the compiler would prohibit code from writing to the parameter after declaration, which means the body of the method is prohibited from writing to the parameter.

public void Update(readonly int index = 0) // Default values are ok though not required
{
    …
    index = 0; // Error: can’t assign to readonly parameters
    …    
}

This support for ‘readonly’ parameters would be particularly helpful for a very specific usage of parameters: passing structs by reference. When a reference type is passed to a method, the state that’s actually passed into the method is a copy of the reference to the object (the reference is passed by value), effectively a pointer-sized piece of data. In contrast, when a struct is passed into a method, a copy of the struct is passed in (the struct’s state is passed by value). If the struct is small, such as is an Int32, this is perfectly fine and there’s little better that could be done by the developer. However, when the struct is large (for example, the System.Windows.Media.Media3D.Matrix3D struct contains 16 doubles, making it 128 bytes in size), it can become quite expensive to continually pass around copies of the data. In these cases, developers often resort to passing structs by ref, passing a pointer to the original data rather than making a copy. This avoids the performance overhead, but it now inadvertenly enables the called method to update the original struct’s value:

public void Use(ref Matrix3D matrix)
{
    …
    matrix.M31 = 0; // Oops! We wanted performance, not more bugs.
    …
}

By enabling marking parameters ‘readonly’, the struct could be passed by reference but still prevent the callee from mutating the original value:

public void Use(readonly ref Matrix3D matrix)
{
    …
    matrix.M31 = 0; // Error: can’t assign to readonly parameters
    …
}

This would also enable readonly struct fields to be passed by ref (to a readonly ref parameter), whereas in C# today passing a readonly struct field by ref is never allowed.
As with ‘readonly’ on fields, ‘readonly’ as it applies to locals and parameters would be shallow rather than deep, meaning that it would prohibit writing to the readonly field, but it wouldn't prevent mutation of any state contained in objects referenced from the ‘readonly’ value.

Additional Considerations

In many situations, in particular when "var" is used to declare a local with type inference, the developer often would like 'readonly' behavior for that local. This is possible if 'readonly' is allowed on locals, e.g.

readonly int foo = ...;
readonly var bar = ...;

but it makes the desired immutability harder to express than mutability. To combat that, as shorthand for 'readonly var', we could also introduce a new 'let' or 'val' syntax, with the same meaning as 'readonly var':

val foo = ...;
val bar = ...;

[ryancerium]

I'd like to allow the readonly modifier on classes to allow immutability by default, and methods also to correlate with C++ const functions.

readonly class Point
{
  public int x; // Implicit readonly
  public int y; // Implicit readonly
  Point(int x, int y)
  {
    this.x = x;
    this.y = y;
  }
}

Point origin = new Point(0, 0);
origin.x = 1; // Error:  can't reassign a readonly class member

[drewnoakes]

readonly always felt a little bit of a short sell for instances of types with mutable internals. The readonly-ness is much more valuable when transitive, as happens with (well behaved) C++ const values.

class C
{
  private int _i;
  public int Read() readonly { return _i; } // method has 'readonly' modifier
  public void Write() { _i++; }
}

readonly C c = new C();
c.Read();
c.Write(); // compile error: method is not readonly

The readonly modifier restricts the method's ability to modify its own members. Any members are also treated as readonly too, and only their readonly methods may be invoked. The entire graph of references from this point outwards becomes immutable.

---

As functional programming paradigms become more commonplace, function purity becomes an comforting property to have, and an appealing property to enforce. Today we have [Pure], but there is no guarantee made by the compiler that this attribute is used factually. A strict purity constraint would extend the above readonly guarantee to the method's arguments any any static values/references. Such a function could have no observable side effects and would be truly idempotent. A pure method modifier could exist that extends this immutability not only to this but to all parameters.

void PureFunction(C c) pure // method has the 'pure' modifier
{
  c.Read();
  c.Write(); // compile error: a pure function's parameters are implicitly readonly
}

Framework code could optimise for or even require pure functions. The compiler could automatically hoist loop invariant code.

[Porges]

Re parameters, I don't like the way that readonly on reference parameters pollutes the (in-source) signature with information that is irrelevant to the caller.

For structs, it would be nice to have those semantics - I've often wished for in as an addition to ref and out, as readonly ref is not very symmetrical 😁 It wasn't mentioned in the proposal, but the call site should not require annotation with in/ref.

[ryancerium]

@drewnoakes I completely agree, but backwards compatibility means we're screwed.

readonly var list = new ArrayList<int>();
readonly var size = list.size(); // Error, calling non-readonly method on readonly reference.

[fubar-coder]

@stephentoub The following example is ambigous:

public void Use(readonly ref Matrix3D matrix)
{
    …
    matrix.M31 = 0; // Error: can’t assign to readonly parameters
    …
}

This would also enable readonly struct fields to be passed by ref (to a readonly ref parameter), whereas in C# today passing a readonly struct field by ref is never allowed.
As with ‘readonly’ on fields, ‘readonly’ as it applies to locals and parameters would be shallow rather than deep, meaning that it would prohibit writing to the readonly field, but it wouldn't prevent mutation of any state contained in objects referenced from the ‘readonly’ value.

The first thing that I thought, when I saw readonly ref was, that ref was used to avoid a copy and readonly was given, to avoid that the Use method changes it. Then I realized, that readonly was used to declare the underling structure as const.

My proposal to resolve this ambiguity is:

public void Use(readonly ref const Matrix3D matrix)
{
    …
    matrix = new Matrix3D(); // Error: can't assign to readonly reference
    matrix.M31 = 0; // Error: can’t change immutable value
    …
}

The variable is readonly and the Matrix3D value is immutable. It should also be possible to use the following syntax:

public void Use(ref const Matrix3D matrix)
{
    …
    matrix = new Matrix3D(); // OK
    matrix.M31 = 0; // Error: can’t change immutable value
    …
}

Calling methods on const objects

Calling methods on const objects should only be allowed when those methods don't make changes to the underlying object.

Examples

The following shouldn't work:

class TestObject {
    public int i;
    public void SetValueOfI(int v) {
        i = v;
    }
}

public void Use(ref readonly TestObject o)
{
    …
    o.SetValueOfI(0); // Error: can’t call non-const method on const object
    …
}

Instead we have to be able to make methods and properties (setter/getter) readonly too:

class TestObject {
    public int i;
    public int AddWithI(int v) const {
        return i + v;
    }
}

public void Test()
{
    var o = new TestObject { i = 1 };
    Use(ref o);
}

public void Use(ref readonly TestObject o)
{
    …
    Assert.AreEqual(124, o.AddWithI(123)); // OK: Can call AddWithI, because it doesn't change the underlying object
    …
}

I personally prefer const over readonly, because IMHO readonly means, that the variable can only be read, but this doesn't necessarily apply to the object it points to (similar to C's T const * const) and - to me - immutable variables and immutable values are different things.

[drewnoakes]

@ryancerium, I suppose this feature would require new metadata in the type system, therefore a new CLR and at the same time a new BCL. ArrayList<T> and friends would be annotated accordingly.

[drewnoakes]

@ryancerium can you further explore why the readonly modifier should apply to the type rather than the instance? The latter seems more flexible. You could still have:

readonly Point origin = new Point(0, 0);
origin.x = 1; // compile error: can't modify a readonly instance's fields

[ryancerium]

@drewnoakes readonly isn't transitive for fields, or for arrays for that matter. It was a mistake committed long ago to not have transitive readonly like C++ const, but it's where we are. Don't get me wrong, I much prefer it, but I think that ship has sailed.

I want to co-opt readonly to make it easier to make immutable data types. Right now I have to put readonly on all the data members, and that's annoying as hell :-)

Here's a different Point class that has mutable x and y values.

class Point
{
  public int x, y;
}

class C
{
  readonly Point origin = new Point(0, 0);
  public void M(readonly Point p)
  {
    origin.x = 100; // Totally fine in C# as-is today.

    p.x = 100; // Error per your suggestion, seems weird when I can modify origin

    readonly Point d = new Point(p.x - origin.x, p.y - origin.y);
    d.y = 100; // Error per your suggestion, seems weird when I can modify origin
    // d = new Point(-1, -1); // Illegal today, reassigning the reference
  }
}

[louthy]

Agreed on the desire for readonly classes, it would be very much appreciated.

I think the syntax for local readonly values should take a leaf out of the F# book and use let. The reason for that is I think val looks too close to var and would make it slightly less easy to scan code quickly. And I think trying to avoid a readonly prefix would be wise to reduce the amount of effort required to 'do the right thing' in choosing the immutable option when coding. As somebody who likes to make as much of my code as pure and as immutable as possible, I would much prefer not to have to litter my code with readonly.

    val foo = 123;
    var bar = 123;

Compared to:

    let foo = 123;
    var bar = 123;

I think the second version is much more 'scannable'.

[stephentoub]

The devil is always in the details on these kinds of proposals around immutability, const, etc. (i.e. when you start working through the intricacies, there are a variety of interesting gotchas and corner cases that need to be handled and increase complexity or at least acknowledged that there are holes.) I have several more proposals to post in this area, I just didn't get a chance to do so yesterday; I'll ensure they're linked to from here when I put them up, hopefully later today.