5. Ownership
Every tracked value has exactly one owner: a local variable, a parameter or a field. The owner is responsible for releasing it. Everyone else holds a borrow that is valid only while the owner is.
Defaults
| Position | Default | To change it |
|---|---|---|
| Function parameter | borrowed | p: @Owned T takes over ownership |
| Function return | owning | : @Borrowed T returns a loan |
| Property parameter of a constructor, and fields | owning | @Borrowed makes a field a non-owning back reference |
Local initialized with a fresh value (Foo(...), a call with owning return) | owner | |
Local initialized from an existing owner (val b = a) | alias (a loan) | a.move() makes b an owner |
this and extension receivers | borrowed |
Lend or give
@file:MemoryMode(Mode.Strict)
import mini.memory.*
class Box(val v: Int)
fun peek(b: Box): Int = b.v // parameters are borrowed by default
fun consume(b: @Owned Box) { // @Owned: this function takes over the obligation
println("consuming ${b.v}")
b.free()
}
fun main() {
context(Heap()) {
val b = Box(7)
println(peek(b)) // lend: b is still ours afterwards
consume(b) // move: b is gone after this call
}
}peek borrows: it may read b but not free it, store it or return it as owned. consume is declared @Owned, so the call consume(b) moves b: afterwards b is gone, and consume has to free it. The checker accepts the program.
Freeing something you only borrowed is an error:
@file:MemoryMode(Mode.Strict)
import mini.memory.*
class Box(val v: Int)
fun drop(b: Box) {
b.free() // `b` is only borrowed here
}
fun main() {
context(Heap()) {
val b = Box(1)
drop(b)
b.free()
}
}M0107. The fix is fun drop(b: @Owned Box). Storing or returning a borrowed value as owned is M0109.
Ending ownership: free(), use {}, close()
x.free()is the one main notation. It callsclose()ifxisAutoCloseable, then releases all fields thatxowns (recursively), then returns the memory to the allocator it came from. It works on nullable values (nullis a no-op).alloc.free(x)is the same with the allocator named, and a mismatch is M0108.x.use { }callsclose()at the end of the block on every path (alsothrow,return,break) and ends the ownership ofx. Inside the block the value is borrowed.x.close()on an owner counts likefree().
@file:MemoryMode(Mode.Strict)
import mini.memory.*
class Resource(val name: String) : AutoCloseable {
override fun close() {
println("close $name")
}
}
context(h: Heap)
fun run() {
Resource("a").use { println("using ${it.name}") } // close() runs on every path out of the block
val b = Resource("b")
println("open ${b.name}")
b.free() // free() calls close() first
}
fun main() {
context(Heap()) { run() }
}A close() body must not free owned fields itself: the compiler releases them after close() returns. The checker accepts the program; on the JVM it prints using a, close a, open b, close b.
Moves
A plain assignment only borrows. Ownership moves implicitly only at: return a from a function with an owning return, an argument for an @Owned parameter (including constructor property parameters), assignment to an owning field, capture in a thread lambda, and use/close. Everywhere else you write a.move().
@file:MemoryMode(Mode.Strict)
import mini.memory.*
class Box(val v: Int)
context(h: Heap)
fun run() {
val a = Box(1)
val alias = a // plain assignment only borrows: `a` stays the owner
println(alias.v)
val b = a.move() // explicit move: `b` is the owner now, `a` is dead
println(b.v)
b.free()
}
fun main() {
context(Heap()) { run() }
}Using the old name after a move is an error:
@file:MemoryMode(Mode.Strict)
import mini.memory.*
class Box(val v: Int)
context(h: Heap)
fun run() {
val a = Box(1)
val b = a.move()
println(a.v) // `a` was moved into `b`
b.free()
}
fun main() {
context(Heap()) { run() }
}M0104. If no transfer was intended, write val b = a (an alias) instead. An alias used after its owner was freed or moved is reported as M0101 or M0104 at the use of the alias.
Borrowed results
fun first(h: Holder): @Borrowed Box? returns a loan that is valid until the owners it derives from (the receiver and all borrowed arguments) are freed, moved or overwritten. The checker has no lifetime variables beyond that: a loan hangs on the receiver and all borrowed arguments.
Nullable owners
T? is owning like T. null carries no obligation, and free() on null does nothing. A branch that leaves Null and another that leaves Owned join into a state in which free() is allowed and if (x != null) removes the obligation. Discarding the result of a function that returns @Owned T? is a leak even though the value might be null at run time.
Next: Fields and containers.