Landin library reference source

core/region

Shared: available on every enabled target.

An allocator scope that records allocations through a borrowed parent and releases them together.

Choose a dynamically grown ledger with new or a fixed caller ledger with over. Individual frees do nothing; every allocation consumes a ledger entry until region release. Release frees payloads in reverse order. End all payload uses before releasing the region.

Items

Executable example

This complete program is maintained in the repository runtime tests. View source.

import core/mem
import core/region

exercise: () -> (ok: bool) ! mem.out_of_memory =
    ok = false
    mut backing: [64]u8 = zeroed
    mut inner := mem.arena_over_unchecked(addr backing[0], 64)
    mut records: [1]region.allocation = zeroed
    mut state := region.over(addr inner, records[0..<1])
    address := try mem.allocate(state, usize(4), usize(1))
    address.val = 42
    return when address.val <> 42
    _ = mem.allocate(state, usize(4), usize(1)) else (problem)
        _ = problem
        mem.free(state, address, usize(4))
        ok = true
        return
    end
end exercise

public main: () -> (code: i32) =
    code = 1
    ok := exercise() else false
    if ok then
        code = 42
    end if
end main

allocation type

public allocation: type = struct
    address: usize
    extent: usize
end allocation

core/region/region.ldn:6

Ledger entry storing an allocated address and its byte extent. Used by bounded regions in caller-supplied initialized storage.

region type

public region: type (provider: type) = region_value(provider)

core/region/region.ldn:28

Allocator that records payload allocations through a borrowed parent. Releasing the region frees all recorded payloads; the parent must outlive the region.

new function

public new: (provider: type is mem.allocator, parent: ptr mut provider)
            -> (value: region(provider) from parent)

core/region/region.ldn:32

Create a region whose ledger grows through its parent allocator. Ledger allocation failure rolls back the just-allocated payload.

over function

public over: (provider: type is mem.allocator,
              parent: ptr mut provider, records: []mut allocation)
             -> (value: region(provider) from parent, records)

core/region/region.ldn:43

Create a region with a bounded caller-owned ledger. Each live payload needs one entry; an exhausted ledger reports mem.out_of_memory and returns the new payload to the parent.

The caller reserves one initialized record per simultaneously live payload. No ledger request is sent to the parent in this form.

release function

public release: (provider: type is mem.allocator,
                 inout state: region(provider)) -> none

core/region/region.ldn:113

Free recorded payloads in reverse order and release any dynamic ledger backing. End every payload use first; a bounded caller ledger remains available for reuse.

End every alias before this call. Every payload and ledger allocation is returned to the parent, including failed-construction payloads. A monotonic parent keeps consumed backing until its own explicit reset.