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)[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)["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])3000000
0 1Running 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:
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)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:
- Return a new value. The caller decides what to do with it:
s = with_bonus(s, 5). - 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)[75, 85]
[75, 85] [85, 95]Forgetting the & is an error, not a silent copy:
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)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)[Account{owner: "ada", balance: 11}, Account{owner: "bob", balance: 5}]
999The 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:
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)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)["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:
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)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)[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)["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:
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))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 amutmethod). 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)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.