Skip to content
LEARN MINIUnderstand Mini memory 14 of 26About 30 min

14. Memory: managed by default ​

From here on Mini differs from Kotlin. Kotlin on the JVM has a garbage collector. Mini has none: it has a memory model with three tiers and you choose the tier per file.

TierWho frees memoryWhat the compiler checks
Managed (default)reference counting, automaticnothing, it is plain Kotlin
Arena / Heap / Poolan allocator you pass in as a context parameterlifetimes of arena objects
Strictyou, with free() and use {}every allocation has exactly one owner and is released exactly once

This chapter is the first tier, the one you have been using since chapter 1.

By the end: draw a small reference graph, explain why sharing is different from copying, and recognize a cycle that ordinary reference counting cannot release. You do not need to introduce explicit allocators to write useful Mini programs.

Reference counting ​

Every object has a counter in its header. Storing a reference increments it, dropping one decrements it, and at zero the object releases what it holds and returns its memory. There is no tracing collection cycle. Releasing a large object graph still takes time, so automatic reference counting is not a promise of pause-free execution.

This program has two references to every Account. Clearing the list does not free them, because the map still holds them:

kotlin
// No @file:MemoryMode: this is Managed code, plain Kotlin. Objects are reference counted and
// released automatically; collections, lambdas and shared references just work.

class Account(val owner: String, var balance: Int)

fun main() {
    val accounts = mutableListOf(Account("ann", 10), Account("bo", 20))
    accounts.forEach { it.balance += 5 }
    println(accounts.map { it.balance })

    val byOwner = HashMap<String, Account>()
    for (a in accounts) byOwner[a.owner] = a      // two references to every Account
    println(byOwner["bo"]?.balance)

    accounts.clear()                              // still alive: byOwner holds them
    println(byOwner.size)
}

Press Run: the output matches what the project's CI prints after building and running the same file natively. The cell is a complete program (it has its own main), so it does not share declarations with the cells around it.

References behave as in Kotlin: two names, one object.

kotlin
class Box(var value: Int)

val a = Box(1)
val b = a            // a second reference, not a copy
b.value = 42
println(a.value)

What you do not have to think about ​

Naive reference counting would update counters all the time. Mini's RcOpt pass removes most of that: reads of fields become borrows, the last use of a local moves the reference instead of retaining it again, and a loop variable that walks a list does not retain each node. On the project's benchmarks 60 to 100 percent of the retains disappear. Instrumented native builds can expose those counters; the current native driver does not accept the legacy --stats flag (see Performance).

The one thing to know: cycles ​

A reference counter cannot see a cycle. If two objects point at each other, neither count reaches zero:

kotlin
class Node(val name: String) {
    var other: Node? = null
}

val x = Node("x")
val y = Node("y")
x.other = y
y.other = x          // x -> y -> x: both objects leak when main ends
println("${x.other?.name} ${y.other?.name}")

The visible output is correct, but the cycle is a memory leak. There is no cycle collector yet. Redesign the graph to avoid a strong cycle, break a link when its logical lifetime ends, or investigate an arena for objects with one shared lifetime. The explicit ownership model also has borrowed references; they need a lifetime contract rather than an annotation pasted onto an arbitrary Managed graph. Both are in the next chapters.

Choosing a tier per file ​

A file opts into a tier with an annotation on its first line:

kotlin
@file:MemoryMode(Mode.Strict)

Without it the file is Managed. Tiers mix: a Strict file can call Managed code and the other way around, with rules at the boundary. You can also opt a single class back out of Strict:

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Vec(val x: Int, val y: Int)

fun len2(v: Vec): Int = v.x * v.x + v.y * v.y

@MemoryMode(Mode.Managed)      // this one class opts back out of Strict
class Counter {
    var count = 0
    fun inc() {
        count++
    }

    fun report(v: @Borrowed Vec) {
        println("len2=" + len2(v) + " count=" + count)
    }
}

fun main() {
    val counter = Counter()
    val names = ArrayList<String>()
    names.add("a")
    names.add("b")
    for (n in names) counter.inc()
    counter.report(Vec(1, 2))
    println(names.joinToString(","))
}

Checkpoint ​

Why can clearing a list leave its elements alive? Can a two-object cycle remain allocated after both local names disappear? Does Managed mode mean your program cannot leak?

Reasoning

Other references, such as a map, may keep the elements alive. A cycle keeps its own counts above zero even after outside references vanish. Managed code handles ordinary release automatically, but reference cycles and unintentionally retained objects can still leak.

Exercise ​

Exercise: shared state

In the starter b is a second reference to the same counter, so both lines print 6. Change main so that b is its own Counter and the program prints 1 and 5.

kotlin
class Counter(var n: Int)

fun main() {
    val a = Counter(0)
    val b = a
    a.n += 1
    b.n += 5
    println(a.n)
    println(b.n)
}
Show solution
kotlin
class Counter(var n: Int)

fun main() {
    val a = Counter(0)
    val b = Counter(a.n)     // a new object instead of a second reference
    a.n += 1
    b.n += 5
    println(a.n)
    println(b.n)
}

Released under the Apache License 2.0.