Skip to content
LEARN MINIDesign Mini lifetimes 22 of 26About 40 min

22. Choose memory boundaries deliberately ​

Knowing the syntax of Heap or Arena is not yet enough to design a lifetime boundary. Start with the work your program performs and the data that must remain valid afterward. Then select a memory policy that expresses that lifetime.

This chapter combines the rules, including closures, threads and the limits of the current checker.

Separate allocation strategy from checking mode ​

An allocator answers where storage comes from and how it can be released. A memory mode answers which obligations the compiler enforces and whether ordinary reference-counted behavior is available.

Arena is not another spelling of Strict. Strict is not another allocator. A context parameter makes an allocator available to a function; a file annotation changes how that file's tracked allocations are checked.

SituationUseful starting pointQuestion that remains
Small application with ordinary acyclic objectsManagedAre long-lived references retaining unnecessary data?
Many temporary objects die after one phaseArenaDoes anything escape the phase?
Individual objects must be released or transferredHeap with an explicit contractWho owns each allocation on every path?
Many objects of one size are repeatedly reusedPoolAre capacity and lifetime constraints suitable?
A function must avoid direct allocating operations@NoAlloc where supportedWhat does the current checker actually analyze?

The table is a starting point, not an automatic optimization rule. First establish correct behavior and a meaningful measurement.

Design an arena around a phase ​

Imagine a parser creating many temporary nodes. It produces a compact report of counts and messages. The parser's working nodes are needed while parsing, but callers only need the report afterward.

A clean boundary separates temporary graph data from the durable result. Values copied out must be independent of the arena. A reference to a node, a view into its storage or a callback capturing it is still dependent on that region.

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

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

context(a: Arena)
fun diagonal(n: Int): Point = Point(n, n)

fun main() {
    // The Int leaves the arena scope; the Points do not. That is allowed.
    val total = Arena().use { arena ->
        context(arena) {
            var t = 0
            for (i in 1..3) t += diagonal(i).x + diagonal(i).y
            t
        }
    }
    println(total)
}

The sample returns an Int derived from points, rather than returning a point itself. Follow the regions: the caller owns the arena scope; the context function allocates in that arena; the computed scalar no longer depends on it.

An arena function can return region objects when its allocator is supplied by the caller and the returned objects remain inside that caller's lifetime. It cannot create a short-lived internal arena, close it and hand those objects to an unrelated caller.

A transformation can change the lifetime contract ​

Suppose an API initially returns an integer total. Later someone changes it to return a lambda computing the total on demand. The return type has changed from a copied result to an operation that may retain the original data.

kotlin
class MutableScore(var points: Int)

fun immediate(score: MutableScore): Int = score.points * 2
fun delayed(score: MutableScore): () -> Int = { score.points * 2 }

fun main() {
    val score = MutableScore(4)
    val now = immediate(score)
    val later = delayed(score)
    score.points = 7
    println(now)
    println(later())
}

The difference is visible even in Managed mode. Across an arena or borrow boundary it can become a lifetime violation. An API review should ask whether a new return value contains references or code that can access region-dependent objects later.

Inline and escaping lambdas have different obligations ​

A lambda body passed to an eligible inline operation can be checked as part of the surrounding control flow. A stored or returned lambda can outlive that flow.

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Box(val v: Int)

context(h: Heap)
fun run() {
    repeat(2) { i ->           // inline lambda: the checker reads the body like ordinary code
        val b = Box(i)
        println(b.v)
        b.free()
    }
    val c = Box(9)
    run {
        println(c.v)
        c.free()               // freeing an outer owner inside an inline lambda is fine
    }
}

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

The checker can see the release within repeat and run. Moving the same body into a returned closure is a different program:

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Box(val v: Int)

context(h: Heap)
fun later(): () -> Int {
    val b = Box(3)
    return { b.v }             // the lambda escapes and would have to own `b`
}

fun main() {
    context(Heap()) { println(later()()) }
}

The second sample is expected to report M0112. A closure that captures a tracked value only borrows it, so it must not outlive the owner. A borrowed capture can also outlive its lender, and an arena capture can outlive its region.

Possible redesigns include computing a scalar result before creating the callback, passing an object as a parameter when the callback is invoked, or keeping the callback inside the region. Choose based on the intended behavior; copying a scalar snapshot is wrong if the callback is supposed to observe live state.

Thread safety is a separate contract ​

A value having an owner does not automatically make every allocator or operation thread-safe. Mini's checker recognizes annotated thread boundaries. Captured owners move into a thread lambda, which becomes responsible for them. Arena and Pool allocators are not ThreadSafe and cannot simply cross that boundary.

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

class Box(val v: Int)

context(h: Heap)
fun run() {
    val b = Box(41)
    val t = spawn {            // b is moved into the thread
        println(b.v + 1)
        b.free()               // ... which must free it
    }
    t.join()
}

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

This is a checker example, not a browser threading tutorial. The current spawn/thread support and runtime limits are documented in Threads and ThreadSafe; a complete native concurrency and async layer is still planned.

Using Heap for a transferable object answers an allocator restriction. It does not prove that concurrently mutating an arbitrary object is safe. Shared-state protocols and data races remain separate questions from ownership transfer and atomic reference counts.

Understand the scope of @NoAlloc ​

kotlin
@file:MemoryMode(Mode.Strict)

import mini.memory.*

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

@NoAlloc
fun dist2(a: Int, b: Int): Int {
    val v = Vec(a, b)          // does not escape: lives on the stack, allowed
    return v.x * v.x + v.y * v.y
}

fun main() {
    println(dist2(1, 2))
}

The local vector does not escape, so the sample is accepted and runs. The annotation is not a promise that every transitive call in the entire application has been proven allocation-free. Currently the checker analyzes the annotated body without complete interprocedural allocation summaries.

When a requirement is strict, such as “no allocation during this operation,” inspect those limits before treating an annotation as a whole-program guarantee. Also consider library calls, collection transformations and captured lambdas. A function name or a short expression is not evidence about allocation.

Exercise: leave only independent data outside ​

Read this API design and propose a boundary before changing code:

  • A phase builds a temporary graph of Node objects.
  • The next phase needs only the number of nodes and a list of user-visible diagnostic strings.
  • A callback currently captures the graph so that diagnostics can be formatted later.

Should the callback leave the arena? Which results could be copied before closing it? Who should own the durable diagnostic list?

One defensible design

Format or copy the durable diagnostic content before closing the temporary region, and return an independently owned result containing only that content and scalar statistics. Keep all graph references and graph-dependent callbacks inside the region. The caller owns the durable result under its selected memory policy.

That describes a design target, not a claim that ownership-aware standard collection APIs are already implemented. The current Strict collection boundary may require a Managed result boundary or an explicit owning container. Check the supported boundary rather than forcing tracked nodes into a regular list.

Review the promises together ​

Before introducing an explicit-memory API, answer all of these in a short design note:

  • What data must remain valid after the operation?
  • Which allocations share one lifetime, and which leave independently?
  • Which parameters are borrowed and which are consumed?
  • Can an error, callback or thread carry references outside the intended region?
  • Which guarantees are checked today, and which remain API responsibilities?
  • What measurement justifies the added lifetime complexity?

An arena is most useful when the region is simple to explain. Strict ownership is most useful when the transfer contract is simple to explain. Start by simplifying the graph if neither description is clear.

Released under the Apache License 2.0.