Skip to content

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 ​

PositionDefaultTo change it
Function parameterborrowedp: @Owned T takes over ownership
Function returnowning: @Borrowed T returns a loan
Property parameter of a constructor, and fieldsowning@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 receiversborrowed

Lend or give ​

kotlin
@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:

kotlin
@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 calls close() if x is AutoCloseable, then releases all fields that x owns (recursively), then returns the memory to the allocator it came from. It works on nullable values (null is a no-op). alloc.free(x) is the same with the allocator named, and a mismatch is M0108.
  • x.use { } calls close() at the end of the block on every path (also throw, return, break) and ends the ownership of x. Inside the block the value is borrowed.
  • x.close() on an owner counts like free().
kotlin
@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().

kotlin
@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:

kotlin
@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.

Released under the Apache License 2.0.