Tern

9. Values, mut, and &

This is the chapter that explains what makes Tern different. In Tern every value behaves like a copy: there are no references, so two variables never share data. A function can change a variable of yours only when its parameter says mut and you pass the variable with &. You will learn how this works, why it is cheap, what take is for, and how these rules turn aliasing bugs into compile errors.

Assignment copies

In Python, JavaScript, Java, or Go, assigning a list or an object gives you a second name for the same data. Change it through one name and the other sees the change. In Tern, assignment always gives you an independent value:

struct Point:
    x, y: int

fn main():
    a = [1, 2, 3]
    b = a
    b.push(4)
    print(a, b)
    p = Point(1, 1)
    q = p
    q.x = 99
    print(p, q)
    m = {"red": 1}
    n = m
    n["blue"] = 2
    print(m, n)
Output
[1, 2, 3] [1, 2, 3, 4]
Point{x: 1, y: 1} Point{x: 99, y: 1}
{"red": 1} {"red": 1, "blue": 2}

This holds everywhere a value moves: passing an argument, storing a value in a struct or an array, taking a value out of a map, returning from a function. Here is the classic bug that this prevents. A team is built from a list, and later the list is changed for another purpose:

struct Team:
    name: str
    members: [str]

fn main():
    roster = ["ada", "bob"]
    core = Team("core", roster)
    roster.push("cy")                 # in Python, core.members would change too
    print(core.members, roster)
Output
["ada", "bob"] ["ada", "bob", "cy"]

In a language with references, core.members and roster would be the same list, and adding cy to one would silently add him to the other. In Tern that can't happen: once a value is stored, only code that names that storage can change it.

Copies are cheap: copy-on-write

Copying a million-element array on every assignment would be slow, so Tern doesn't. Arrays, maps, and strings share their storage until one side is written, and only then is the data copied. Reading never copies:

fn main():
    big = [0] * 1_000_000
    a = big
    b = big
    c = big                          # no copies yet: all four share storage
    print(len(a) + len(b) + len(c))
    c[0] = 1                         # now c gets its own copy
    print(big[0], c[0])
Output
3000000
0 1

Running this with TERN_STATS=1 tern run prog.tn prints a summary line to stderr that includes 1 copy-on-write copies: the only copy happened when c was written. And when the compiler can prove a value is never shared, it skips even the check.

So you can write code as if everything is copied, and pay only for copies you actually need. The memory guide explains how this works under the hood.

Parameters are read-only

You met this rule in chapter 4. A parameter can't be assigned, and a collection parameter can't be changed with push, pop, or element assignment:

Does not compile
fn add_bonus(scores: [int], bonus: int):
    for i in 0..len(scores):
        scores[i] += bonus

fn main():
    s = [70, 80]
    add_bonus(s, 5)
    print(s)
Compiler output
3: error: can't modify parameter `scores`: parameters are read-only unless declared `mut`
3: hint: to change only a local copy, copy it first (`scores2 = scores`) and change `scores2`; to change the caller's value, declare `scores: mut T` and call with `f(&x)` or `x.f()`

Why not just let the function change its own copy, as Python does with numbers? Because the reader of add_bonus(s, 5) would then have to guess: does this change s or not? In Tern there are two clear options, and both are visible in the code:

  1. Return a new value. The caller decides what to do with it: s = with_bonus(s, 5).
  2. Declare the parameter mut, and have the caller pass &s.

mut and &

A mut parameter lets the function change the caller's variable. The caller must write & before the argument, so every argument a call might change is marked (the one exception, method syntax on a mut first parameter, is below):

fn add_bonus(scores: mut [int], bonus: int):
    for i in 0..len(scores):
        scores[i] += bonus

fn with_bonus(scores: [int], bonus: int) [int]:
    return scores.map(fn(s) s + bonus)

fn main():
    s = [70, 80]
    add_bonus(&s, 5)                  # changes s
    print(s)
    t = with_bonus(s, 10)             # s is untouched
    print(s, t)
Output
[75, 85]
[75, 85] [85, 95]

Forgetting the & is an error, not a silent copy:

Does not compile
fn add_bonus(scores: mut [int], bonus: int):
    for i in 0..len(scores):
        scores[i] += bonus

fn main():
    s = [70, 80]
    add_bonus(s, 5)
    print(s)
Compiler output
7: error: argument 1 of `add_bonus` is `mut`: write `&s` so the change is visible here

& can be put before a variable, a field (&game.player), or an element (&accounts[2]), and only as an argument to a mut parameter. It is not a pointer; you can't store it or return it. It means "this call may change this, right now".

With method syntax, the dot plays the role of the &: when the first parameter is mut, s.add_bonus(5) is the same as add_bonus(&s, 5).

Elements are values too

Taking an element out of an array gives you a copy. To change the element itself, write through the array, or pass the element with &:

struct Account:
    owner: str
    balance: int

fn deposit(a: mut Account, amount: int):
    a.balance += amount

fn main():
    accts = [Account("ada", 10), Account("bob", 0)]
    first = accts[0]                  # a copy
    first.balance = 999               # changes only the copy
    accts[0].balance += 1             # changes the element
    deposit(&accts[1], 5)             # so does this
    print(accts)
    print(first.balance)
Output
[Account{owner: "ada", balance: 11}, Account{owner: "bob", balance: 5}]
999

The same goes for for a in accts:. The loop variable is a (read-only) copy of each element; to change elements, loop over indexes and write accts[i].

Aliasing is a compile error

If a function could receive the same value twice, once as mut and once more, a change through one parameter would show up in the other in the middle of the function. This is called aliasing, and it causes some of the hardest bugs to find in C, C++, and Go. Tern refuses such calls:

Does not compile
fn append_all(dst: mut [str], src: [str]):
    for s in src:
        dst.push(s)

fn main():
    names = ["ada", "bob"]
    append_all(&names, names)
    print(names)
Compiler output
7: error: `append_all` would see the same value twice: `&names` can be changed, but `names` is also passed (argument 2)

In a language with references, append_all(names, names) would loop over src while the same list grows through dst, and never finish. The fix is to say what you mean: pass a copy, which is a separate value.

fn append_all(dst: mut [str], src: [str]):
    for s in src:
        dst.push(s)

fn main():
    names = ["ada", "bob"]
    snapshot = names
    append_all(&names, snapshot)
    print(names)
Output
["ada", "bob", "ada", "bob"]

The check is conservative for array elements. The compiler can't always prove that two indexes differ, so transfer(&accts[0], &accts[1], 30) is refused too:

Does not compile
struct Account:
    owner: str
    balance: int

fn transfer(src: mut Account, dst: mut Account, amount: int):
    src.balance -= amount
    dst.balance += amount

fn main():
    accts = [Account("ada", 100), Account("bob", 50)]
    transfer(&accts[0], &accts[1], 30)
    print(accts)
Compiler output
11: error: `transfer` would see the same value twice: `&accts[..]` can be changed, but `accts[..]` is also passed (argument 2)

When a function works on several elements of one array, pass the array once, with indexes:

struct Account:
    owner: str
    balance: int

fn transfer(accts: mut [Account], src: int, dst: int, amount: int):
    accts[src].balance -= amount
    accts[dst].balance += amount

fn main():
    accts = [Account("ada", 100), Account("bob", 50)]
    transfer(&accts, 0, 1, 30)
    print(accts)
Output
[Account{owner: "ada", balance: 70}, Account{owner: "bob", balance: 80}]

take: handing a value over

There is a third parameter mode. A take parameter receives the value itself: the function owns it and may change it freely, and the caller can no longer use it. Use it when a function consumes a large value and returns a modified version, to avoid a copy:

fn normalized(names: take [str]) [str]:
    for i in 0..len(names):
        names[i] = names[i].trim().lower()
    return names

fn main():
    raw = ["  Ada ", "GRACE", " Linus"]
    clean = normalized(raw)
    print(clean)
Output
["ada", "grace", "linus"]

normalized changes the array it was given and returns it, so no copy is ever made. The price is that after normalized(raw), raw is gone. Using it again is an error:

Does not compile
fn total(xs: take [int]) int:
    t = 0
    for x in xs:
        t += x
    return t

fn main():
    data = [1, 2, 3]
    print(total(data))
    print(len(data))
Compiler output
10: error: `data` was handed to a `take` parameter earlier and is gone (pass `copy(data)` to keep it)

If you still need the value, pass copy(data), an explicit copy. You will rarely need take at all: plain parameters and copy-on-write already avoid copies in almost all code. Reach for it when profiling shows a copy you want to avoid.

Why it's worth it

These rules can feel strict for the first few programs. Here is what they buy:

  • Local reasoning. To know what a call can change, read the call: only & arguments (and the value before the dot for a mut method). Nothing else in your program can change.
  • No aliasing bugs. Two names never refer to the same data, so a change here never shows up unexpectedly over there.
  • Safe parallelism. Because nothing is shared implicitly, the compiler can check that parallel tasks don't write the same data, which is the subject of chapter 11.
  • No garbage collector and no lifetimes. Every value has exactly one owner, so memory is freed as soon as it is no longer used, without annotations.

Try it

Write a small bank: struct Bank with an accounts: {str: int} map from owner to balance. Write fn open_account(b: mut Bank, owner: str), fn deposit(b: mut Bank, owner: str, amount: int), and a read-only fn total(b: Bank) int. Take a snapshot before = bank, make some deposits, and print both totals to see that the snapshot didn't change.

Solution

struct Bank:
    accounts: {str: int}

fn open_account(b: mut Bank, owner: str):
    b.accounts[owner] = 0

fn deposit(b: mut Bank, owner: str, amount: int):
    b.accounts[owner] += amount

fn total(b: Bank) int:
    t = 0
    for owner, bal in b.accounts:
        t += bal
    return t

fn main():
    bank = Bank({})
    bank.open_account("ada")
    bank.open_account("bob")
    deposit(&bank, "ada", 100)
    before = bank
    bank.deposit("bob", 40)
    bank.deposit("ada", 5)
    print(before.total(), bank.total())
    print(before.accounts, bank.accounts)
Output
100 145
{"ada": 100, "bob": 0} {"ada": 105, "bob": 40}

Next: 10. Functions as values. Reference: §14 Values, mut, and the safety rules. Guide: How memory works.

Source: docs/tour/09-values-and-mut.md. Every example on this page is compiled and run by tern x test docs.