Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.5

0.7.5 / src / owned.lucb

#==============================================================================================
#
#   owned - Results that carry the owner of their storage
#
#   DESCRIPTION:
#       Allocations handed to a caller as interop.Owned results, together with the object that
#       frees them. Luce copies the value into its own and releases the owner; a Base caller
#       reads `.value` and calls `release()` when done with it.
#
#==============================================================================================

import interop
import memory
import ownership
import strings

## What a result's storage holds.
enum Held:
    bytes
    numbers
    text
    texts

## The storage behind one result, allocated from `allocator`, which frees it.
struct Storage:
    var header: ownership.Object
    var allocator: memory.Allocator
    var held: Held
    var data: u8[]
    var numbers: f64[]
    var text: str
    var texts: str[]

func drop_storage(object: ownership.Object*):
    let storage = (Storage*)object
    with storage.allocator:
        match storage.held:
            .bytes:
                if storage.data.length > 0:
                    free(storage.data)
            .numbers:
                if storage.numbers.length > 0:
                    free(storage.numbers)
            .text:
                strings.release(storage.text)
            .texts:
                for text in storage.texts:
                    strings.release(text)
                if storage.texts.length > 0:
                    free(storage.texts)

func trace_storage(object: ownership.Object*, visit: func(ownership.Object*, void*) -> unit, context: void*):
    _ = object

var storage_info: ownership.Info = ownership.Info(name = "owned result", size = memory.size_of(Storage),
                                                  finish = none, drop = drop_storage,
                                                  trace = trace_storage, acyclic = true)

## Storage for a result whose allocations came from the current allocator.
func new_storage(held: Held) -> Storage*!:
    let storage = (Storage*)(try ownership.reserve(&storage_info, memory.size_of(Storage)))
    storage.allocator = memory.allocator
    storage.held = held
    return storage

## Own `data`, an allocation of the current allocator (or empty), as a byte result. The
## span belongs to the result from the call on, also when making the owner fails.
pub func adopt_bytes(data: u8[]) -> interop.Owned[const u8[]]!:
    let owner = new_storage(Held.bytes) catch failure:
        if data.length > 0:
            free(data)
        error(failure.code, failure.message)
    owner.data = data
    return interop.Owned[const u8[]](data, &owner.header)

## Own `values`, an allocation of the current allocator (or empty), as a list of numbers.
## The span belongs to the result from the call on, also when making the owner fails.
pub func adopt_numbers(values: f64[]) -> interop.Owned[const f64[]]!:
    let owner = new_storage(Held.numbers) catch failure:
        if values.length > 0:
            free(values)
        error(failure.code, failure.message)
    owner.numbers = values
    return interop.Owned[const f64[]](values, &owner.header)

## Own `value`, a NUL-terminated text of the current allocator such as `strings.copy`
## answers, as a text result a Base caller may also pass on as a `c.str`. It belongs to
## the result from the call on, also when making the owner fails.
pub func adopt_text(value: str) -> interop.Owned[str]!:
    let owner = new_storage(Held.text) catch failure:
        strings.release(value)
        error(failure.code, failure.message)
    owner.text = value
    return interop.Owned[str](value, &owner.header)

## Own `values`, an array of the current allocator (or empty) of NUL-terminated texts of it,
## as a list result. Array and texts belong to the result from the call on.
pub func adopt_texts(values: str[]) -> interop.Owned[const str[]]!:
    let owner = new_storage(Held.texts) catch failure:
        release_texts(values, values.length)
        error(failure.code, failure.message)
    owner.texts = values
    return interop.Owned[const str[]](values, &owner.header)

## A copy of `value` as an owned text, NUL-terminated for Base callers.
pub func copy_text(value: str) -> interop.Owned[str]!:
    return try adopt_text(try strings.copy(value))

## Give back an array of texts that never became a result: its first `count` texts, then
## the array.
pub func release_texts(values: str[], count: usize):
    for value in values[..<count]:
        strings.release(value)
    if values.length > 0:
        free(values)

## Texts gathered into a growing array of the current allocator, then handed to an owned
## result exactly as long as they are.
pub struct Gathered:
    var texts: str[]
    var count: usize

    ## Add a copy of `text`.
    pub func add(text: str) -> !:
        if self.count == self.texts.length:
            let capacity = self.texts.length *? 2 else error(memory.exhausted, "too many texts")
            try self.resize(capacity if capacity > 0 else 16)
        self.texts[self.count] = try strings.copy(text)
        self.count += 1

    ## The texts gathered so far.
    pub func view() -> str[]:
        return self.texts[..<self.count]

    func resize(capacity: usize) -> !:
        var resized: str[]
        if capacity > 0:
            resized = try new str[capacity] ---
            memory.copy(resized, self.texts, self.count)
        if self.texts.length > 0:
            free(self.texts)
        self.texts = resized

    ## The texts as an owned result; the gathering is empty afterwards.
    pub func finish() -> interop.Owned[const str[]]!:
        try self.resize(self.count)
        let texts = self.texts
        var empty: str[]
        self.texts = empty
        self.count = 0
        return try adopt_texts(texts)

    ## Give back whatever was gathered.
    pub func release():
        release_texts(self.texts, self.count)
        var empty: str[]
        self.texts = empty
        self.count = 0

test "an owned result frees its storage when released":
    let before = ownership.live_count()
    var names: Gathered
    errdefer names.release()
    try names.add("ada")
    try names.add("grace")
    let list = try names.finish()
    assert(list.value.length == 2 and list.value[1] == "grace")
    let data = try adopt_bytes(try new u8[3] ---)
    let path = try copy_text("/tmp")
    assert(path.value == "/tmp" and path.value.bytes.data[4] == 0)
    let numbers = try adopt_numbers(try new f64[2] ---)
    assert(numbers.value.length == 2)
    assert(ownership.live_count() == before + 4)
    list.release()
    data.release()
    numbers.release()
    path.release()
    assert(ownership.live_count() == before)

test "an empty gathering is an empty result":
    var none_yet: Gathered
    let empty = try none_yet.finish()
    assert(empty.value.length == 0)
    empty.release()