Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.43.0

0.43.0 / src / std / interop / reference.lucb

#==============================================================================================
#
#   reference - A typed reference carrier
#
#   DESCRIPTION:
#       Parameters borrow the carrier; clone acquires an additional strong reference.
#       Publish/adopt return one owning reference whose Base caller releases explicitly.
#
#==============================================================================================

## A typed reference carrier. Parameters borrow the carrier; clone acquires an
## additional strong reference. Publish/adopt return one owning reference, whose
## Base caller releases explicitly. Copying the struct does not acquire ownership.
pub struct Reference[T]:
    ## The owner shell this reference keeps alive.
    pub let owner: Owner[T]*

    ## A reference over `owner`, which is already alive.
    pub func init(owner: Owner[T]*):
        ownership.check_alive(&owner.header)
        self.owner = owner

    ## Adopt `native` into a new owned reference of `declaration`.
    pub static func adopt(native: T*, declaration: Type[T], allocator: memory.Allocator? = none) -> Reference[T]!:
        let selected = allocator else memory.allocator
        var reservation = Reservation[T](declaration) catch failure:
            release_native(native, declaration, selected)
            error(failure)
        return reservation.publish(native, selected)

    ## Another strong reference to the same value.
    pub func clone() -> Reference[T]:
        _ = ownership.retain(&self.owner.header)
        return Reference[T](self.owner)

    ## Drop this reference's edge.
    pub func release():
        ownership.release_held(&self.owner.header)

    ## The native value, or a closed/uninitialized error.
    pub func get() -> T*!:
        ownership.check_alive(&self.owner.header)
        if self.owner.closed:
            error(invalid, "a native object is closed")
        return self.owner.native else trap("a native object has not been initialized")

    ## Infallible access traps; fallible adapters use get to preserve a closed error.
    pub func value() -> T*:
        return self.get() catch failure:
            ownership.stop_at_site(failure.message)
            trap(failure.message)

    ## A stable identity for the value that never repeats.
    pub func identity() -> u64:
        ownership.check_alive(&self.owner.header)
        return self.owner.header.generation

    ## Whether the value has been closed.
    pub func is_closed() -> bool:
        ownership.check_alive(&self.owner.header)
        return self.owner.closed

    ## Close the value, if its type is closeable.
    pub func close():
        ownership.check_alive(&self.owner.header)
        if not self.owner.declaration.closeable:
            trap("this native type does not support explicit close")
        close_owner[T](self.owner)

    ## A validity lease over the value.
    pub func lease() -> Lease!:
        _ = try self.get()
        return try Lease(&self.owner.header, Owner[T].is_open, Owner[T].enter, Owner[T].leave)

    ## Validate that `object` is a live reference of this type.
    pub static func validate_interface(object: ownership.Object*) -> !:
        _ = try Reference[T]((Owner[T]*)object).get()

    ## The supplied witness must point into this owner's stable native storage.
    pub func as_interface[I](native: I) -> Interface[I]:
        return Interface[I](&self.owner.header, native, Reference[T].validate_interface,
                            Owner[T].enter, Owner[T].leave).clone()

    ## Guards are balanced by generated Luce calls or explicitly by Base callers.
    pub func enter():
        Owner[T].enter(&self.owner.header)

    ## End a native call guard on the value.
    pub func leave():
        Owner[T].leave(&self.owner.header)

    ## Every retained native edge must be visited by the package's trace callback.
    pub func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        # Trial deletion temporarily subtracts internal strong references.
        ownership.check_thread(&self.owner.header)
        visit(&self.owner.header, context)

## Dispose of `native`, a value no reference took, and free it from `allocator`.
func release_native[T](native: T*, declaration: Type[T], allocator: memory.Allocator):
    declaration.dispose(native)
    free(native) in allocator