Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.45.0

0.45.0 / src / std / interop / interface.lucb

#==============================================================================================
#
#   interface - An owned interface witness
#
#   DESCRIPTION:
#       Pairs an interface witness with explicit ownership and validity; a bare Base interface is
#       only a pointer/table view, so this carrier makes retention deliberate.
#
#==============================================================================================

## An interface witness paired with explicit ownership and validity. A bare Base
## interface is only a pointer/table view; this carrier makes retention deliberate.
pub struct Interface[I]:
    ## The retained object the witness belongs to.
    pub let owner: ownership.Object*
    let native: I
    let validate: (func(ownership.Object*) -> unit!)?
    let begin: (func(ownership.Object*) -> unit)?
    let end: (func(ownership.Object*) -> unit)?

    ## Construction borrows. A returned carrier transfers one retained reference;
    ## use clone when the caller already owns the original reference.
    pub func init(owner: ownership.Object*, native: I,
                  validate: (func(ownership.Object*) -> unit!)? = none,
                  begin: (func(ownership.Object*) -> unit)? = none,
                  end: (func(ownership.Object*) -> unit)? = none):
        ownership.check_alive(owner)
        if (begin == none) != (end == none):
            trap("an interface needs paired invocation guards")
        self.owner = owner
        self.native = native
        self.validate = validate
        self.begin = begin
        self.end = end

    ## Another edge to the same witness.
    pub func clone() -> Interface[I]:
        _ = ownership.retain(self.owner)
        return self

    ## Drop this witness's edge to the owner.
    pub func release():
        ownership.release_held(self.owner)

    ## The interface value, after checking that the owner is alive and valid.
    pub func get() -> I!:
        ownership.check_alive(self.owner)
        if let validate = self.validate:
            try validate(self.owner)
        return self.native

    ## The interface value, trapping if it is invalid.
    pub func value() -> I:
        return self.get() catch failure:
            ownership.stop_at_site(failure.message)
            trap(failure.message)

    ## Begin a guarded invocation, retaining the owner.
    pub func enter() -> !:
        _ = try self.get()
        _ = ownership.retain(self.owner)
        if let begin = self.begin:
            begin(self.owner)

    ## End a guarded invocation, releasing the owner.
    pub func leave():
        ownership.check_alive(self.owner)
        if let end = self.end:
            end(self.owner)
        ownership.release_held(self.owner)

    ## Visit the owner as a strong reference.
    pub func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
        ownership.check_thread(self.owner)
        visit(self.owner, context)