Skip to content

4. Strict mode ​

Put this at the top of a file:

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

In Strict mode there is no reference-counting fallback. Every allocation needs a proven owner, and every owner must release it exactly once on every path, or hand it on. If the compiler cannot prove that, the build fails. @MemoryMode(Mode.Managed) on a single class overrides the file for that class.

What is tracked ​

The checker follows references to instances of classes declared in a Strict file or class, plus AutoCloseable allocators (Arena, Pool). Primitives, String, objects of Managed classes, function values without tracked captures, and Heap/Rc/DebugAllocator are not tracked and carry no obligations.

A tracked reference is in one state at each program point: owned, null, freed, moved, or a union of those at a merge point. Each function is checked from its own body and the signatures of its callees; nothing is inferred across function boundaries.

The leak from the front page ​

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Buffer(val size: Int) : AutoCloseable {
    override fun close() = println("close $size")
}

fun fill(b: Buffer): Boolean = b.size > 100

context(h: Heap)
fun load(n: Int): @Owned Buffer? {
    val buf = Buffer(n)
    if (!fill(buf)) return null    // leaks `buf`
    return buf
}

fun main() {
    context(Heap()) { load(8).free() }
}

M0102: buf is still owned when load returns null. The diagnostic names the path (early return). The fix is to release on that path as well:

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Buffer(val size: Int) : AutoCloseable {
    override fun close() = println("close $size")
}

fun fill(b: Buffer): Boolean = b.size > 100

context(h: Heap)
fun load(n: Int): @Owned Buffer? {
    val buf = Buffer(n)
    if (!fill(buf)) {
        buf.free()                 // release on this path too
        return null
    }
    return buf                     // ownership moves to the caller
}

fun main() {
    context(Heap()) { load(8).free() }
}

The checker accepts this version. The checker also stops one cause from producing a cascade: after it reports a problem about a variable, it assumes the variable is in the state that makes the next step consistent, so you get one message per mistake.

Using a value after it is freed ​

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Box(val v: Int)

fun main() {
    context(Heap()) {
        val b = Box(1)
        b.free()
        println(b.v)           // use after free
    }
}

Rejected with M0101. Freeing twice is M0103.

Control flow is followed ​

The checker builds a control-flow graph per function. At a merge point (if, when) the states are joined, so a value freed in one branch only is still a leak, or a possible use after free, afterwards. Loops are handled as a fixed point: an owner created per iteration must be released in every iteration, and an owner from outside the loop must not be moved or freed in the body unless the body restores it. finally bodies are copied into every exit path, so a release in finally covers return, break and exceptions.

Exception edges are an approximation: they only come from throw, from error/require/check/requireNotNull/checkNotNull/TODO, and from calls of functions in the same Strict module that contain a throw. An ordinary call, a division or an array access does not create an exception edge, otherwise all code would count as leaking.

Strict and Managed code ​

The two modes mix in one program. Managed objects seen from Strict code are borrowed with external lifetime: you never free them. The rules at the boundary:

DirectionRule
Strict passes an untracked value (Int, String, Managed object) to Managed codeallowed
Strict passes a tracked value to a Managed function or a library functionallowed when the callee only borrows it: the compiler infers this from the callee's body (println, toString, StringBuilder.append, scope functions, your own Managed helpers) and stores the result in precompiled libraries. If the callee keeps the value (stores it in a field or collection, returns it), M0110 names the reason. @Borrowed on the parameter is still an explicit promise
Strict stores a tracked value in a field of a Managed classM0110
Strict puts a tracked value in a Kotlin collectionM0110
Managed calls a Strict function with @Owned parameters or an owning returnM0110: Managed code cannot keep the promise. Write a Strict wrapper that frees internally

A mixed program, which is built and run natively in CI:

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(","))
}
text
len2=5 count=2
a,b

Counter is Managed, so it has no obligations; Vec is a Strict class, but it never escapes and is only passed to a borrowed parameter, so no allocator is needed.

Putting tracked values into collections is rejected today:

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Box(val v: Int)

context(h: Heap)
fun run() {
    val list = ArrayList<Box>()    // a Managed collection
    val b = Box(1)
    list.add(b)                    // collections of owned values are not supported yet
    b.free()
}

fun main() {
    context(Heap()) { run() }
}

This is M0110. Collections of owned values are not supported yet; see Fields and containers.

Strict code that is not allocator-heavy ​

In Strict mode a function that never needs a heap allocation is just Kotlin. Allocation sites that do not escape need no allocator at all, which is why the Vec above compiles without a context.

Next: Ownership.

Released under the Apache License 2.0.