Go - Immutability

This document describes a language feature proposal to immutability for the Go programming language. The proposed feature targets the current Go 1.x (> 1.11) language specification and doesn't violate the Go 1 compatibility promise. It also describes an even better approach to immutability for a hypothetical, backward-incompatible Go 2 language specification.

Author	Roman Sharkov ([email protected])
Status	Public (#27975)
Version	1.0.1

Table of Contents

Go - Immutability

1. Introduction

Immutability is a technique used to prevent mutable shared state, which is a very common source of bugs, especially in concurrent environments, and can be achieved through the concept of immutable types.

Bugs caused by mutable shared state are not only hard to find and fix, but they're also hard to even identify. Such kind of problems can be avoided by systematically limiting the mutability of certain objects in the code. But a Go 1.x developer's current approach to immutability is manual copying, which lowers runtime performance, code readability, and safety. Copying-based immutability makes code verbose, imprecise and ambiguous because the intentions of the code author are never clear.

Immutable types can help achieve this goal more elegantly improving the safety, readability, and expressiveness of the code. They're based on 5 fundamental rules:

I. Each and every type has an immutable counterpart.
II. Assignments to objects of an immutable type are illegal.
III. Calls to mutating methods (methods with a mutable receiver type) on objects of an immutable type are illegal.
IV. Mutable types can be cast to their immutable counterparts, but not the other way around.
V. Immutable interface methods must be implemented by a method with an immutable receiver type.

These rules can be enforced by making the compiler scan all objects of immutable types for illegal modification attempts, such as assignments and calls to mutating methods and fail the compilation. The compiler would also need to check, whether types correctly implement immutable interface methods.

Ideally, a safe programming language should enforce immutability by default where all types are immutable unless they're explicitly qualified as mutable because forgetting to make an object immutable is easier, then accidentally making it mutable. But this concept would require significant, backward-incompatible language changes breaking existing Go 1.x code. Thus such an approach to immutability would only be possible in a new backward-incompatible Go 2.x language specification.

To prevent breaking Go 1.x compatibility this document describes a backward-compatible approach to adding support for immutable types by overloading the const keyword (see here for more details) to act as an immutable type qualifier.

1.1. Current Problems

The current approach to immutability (namely copying) has a number of disadvantages listed below and sorted by importance in descending order.

1.1.1. Ambiguous Code and Dangerous Bugs

The absence of immutable types can lead to ambiguous code that results in dangerous, hard to find bugs. Consider the following method definition:

// Method ...
func (r *T) Method(
	a *T,
	b *T,
	v []*T,
) (rv *T) {/*...*/}

The above code is ambiguous, it doesn't represent the intentions of its original author:

Will it produce any side-effects on r?
Will it mutate the Ts referenced by a and b?
Will it mutate v?
Will it mutate any T referenced by any item of v?
Is the T referenced by rv allowed to be mutated?

All those questions can lead to bugs if they're not properly answered, and documentation never answers them reliably.

If the above function is exported from a 3-rd party package xyz that's imported to a project P as an external dependency and the documentation promises (or "claims") to not mutate any of the symbols, the code in P will be written with this assumption in mind.

At any time the vendor of xyz might change its behavior, either intentionally or unintentionally, which will introduce bugs and data corruption:

a, b, v or any items of v might get aliased and mutated either directly (in the scope of xyz.T.Method) or indirectly (at an unspecified point in time).
New side-effects could be introduced to r.
rv might get aliased and introduce unwanted side-effects when mutated by the xyz.T.Method caller.

In the worst case, the maintainers of P won't even be informed about the mutations that were unintentionally introduced to a newer version of xyz.T.Method through a bug in its implementation. But even if the vendors of xyz correctly update the changelog and the documentation introducing new intentional side-effects, chances are high that the maintainers of P miss the changes in the documentation and fail to react accordingly. P will continue to compile, but its outputs will become corrupted which can't always be easily detected even in the presence of extensive automated testing.

1.1.2. Vague and Bloated Documentation

Documentation never represents actual intentions, it represents claimed intentions. Claimed intentions can't be relied on, because claims are not guaranteed to remain in sync with actual code behavior.

To avoid ambiguous code developers often describe mutability recommendations of variables, fields, arguments, methods and return values. Not only does this unnecessarily complicate and bloat up the documentation, but it also makes it error-prone and redundant. Documentation can easily get out of sync with the actual code because it can't be verified algorithmically.

1.1.3. The - Slow but Safe vs Dangerous but Fast - Dilemma

Copies are the only way to achieve immutability in Go 1.x, but copies inevitably degrade runtime performance. This dilemma encourages Go 1.x developers to either write unsafe mutable APIs when targeting optimal runtime performance or safe but slow and copy-code bloated ones.

Unfortunatelly, optimal performance and code safety are currently mutually exclusive, even though having both would be possible with compiler-enforced immutable types at the cost of a slightly decreased compilation time.

1.1.4. Inconsistent Concept of Constants

Currently, Go 1.x won't allow non-scalar constants such as constant slices:

const each2 = []byte{'e', 'a', 'c', 'h'} // Compile-time error

Robert Griesemer stated in his comment to proposal #6386 that this is by language design, quote:

This is neither a defect of the language nor the design. The language was deliberately designed to only permit constant of basic types.

But many developers still claim it to be a major design flaw because exclusive immutability for scalar types only leads to inconsistency in the language design. What most developers really need is not constants of arbitrary types but rather immutable package-scope variables, which can be implemented consistently with the help of immutable types:

var each2 const []byte = []byte{'e', 'a', 'c', 'h'}

Even though technically each2 is not a constant but an immutable package-scope variable - it solves the mutability problem.

1.2. Benefits

Support for immutable types would provide the benefits listed below and sorted by importance in descending order.

1.2.1. Safe and Precise Code

Immutable types make APIs less ambiguous.

With immutable types the situations described in the previous section wouldn't even be possible, because the author of the function of the external package would need to explicitly qualify immutable types as such to make the compiler enforce the guarantee:

// Method ...
func (r * const T) Method(
	a * const T,
	b * T,
	v const [] * const T,
) (
	rv * const T,
	rv2 * T,
) {
	/*...*/
}

The above code is unambiguous and precise. It clearly represent the intentions of its original author and answers all critical questions reliably:

Will it produce any side-effects on r?
- No, it can't. Its receiver is immutable
Will it mutate the T referenced by a?
- No, it can't. The T referenced by a is immutable
Will it mutate v?
- No, it can't. v is immutable
Will it mutate any T referenced by any item of v?
- No, it can't. The Ts referenced by any item of v are immutable
Is the T referenced by rv allowed to be mutated?
- No, it's not. The T referenced by rv is immutable
Will it mutate the T referenced by b?
- Yes, it potentially will!
Is the T referenced by rv2 allowed to be mutated?
- Yes, it won't lead to unwanted side-effects

Whenever a mutable type is taken, returned or provided it's assumed that its state will potentially be mutated.

The user of this function would make decisions based on the actual function definition in the code instead of relying on the potentially inconsistent documentation.

If the vendors of this function decide to change the mutability of either an input or output type or the mutability of the object the method operates on - they will have to change the type introducing breaking API changes causing compiler errors and making the user pay attention to whether or not everything's right.

The vendors won't be able to just silently introduce mutations causing bugs! The compiler will prevent this from happening either before the vendors release the update (assuming that the code is compiled by a CI/CD system before publication) or during the user's local build in the worst case.

1.2.2. Self-Explaining Code

With immutable types, there's no need to explicitly describe mutability recommendations in the documentation. When immutable types are declared as such then the code becomes self-explaining:

An argument or a variable of an immutable type can be relied on not being changed neither inside the scope it's declared in, nor in the scopes it's passed to.
An immutable method (or a "function with a receiver of an immutable type" if you will) - can be relied on not changing the object it operates on.
A return value of an immutable type can be relied on not being changed by the function caller.
A field of an immutable type can be relied on not being changed as soon as the object is initialized, even inside the scope of its origin package.

1.2.3. Increased Runtime Performance

Immutability provides a way to safely avoid unnecessary copying as well as unnecessary indirections through mutable and immutable interfaces (because interfaces do have a cost).

Immutability also makes specific compiler optimizations possible. Whether or not those optimization opportunities are exploited later on is rather irrelevant to this particular proposal.

2. Proposed Language Changes

The language must be adjusted to support the const qualifier inside type definitions to qualify certain types as immutable.

The compiler must enforce the following rules:

Immutable types are declared with the const qualifier prepended.
Assignments to objects of an immutable type are illegal.
Calls to mutating methods (methods with a mutable receiver type) on objects of an immutable type are illegal.
Calls to mutating interface methods on immutable interface references are illegal.
Immutable types cannot be cast to their mutable counterparts.
Types must implement immutable interface methods using an immutable receiver type.
Mutable types are implicitly cast to their immutable counterparts.
During method calls - pointer receivers must be implicitly cast in both directions (allowing immutable to mutable cast) if the types of the objects they're pointing to are equal.

It is to be noted, that all proposed changes are fully backward-compatible and don't require any breaking changes to be introduced to the Go 1.x language specification. Code written in previous versions of Go 1.x will continue to compile and work as usual.

2.1. Immutable Fields

Struct fields of an immutable type can only be set during the object initialization and are then immutable for the entire lifetime of the object within any context.

type Object struct {
	ImmutableField const * const Object // Immutable
	MutableField   *Object              // Mutable
}

// MutatingMethod is a non-const method
func (o *Object) MutatingMethod() {
	o.MutableField = &Object{}
	o.ImmutableField = &Object{} // Compile-time error
}

func main() {
	// Immutable fields are immutable once the object is initialized
	obj := Object{
		ImmutableField: &Object{
			ImmutableField: nil,
		},
	}

	obj.MutableField = &Object{}
	obj.ImmutableField = nil                      // Compile-time error
	obj.ImmutableField.ImmutableField = &Object{} // Compile-time error
}