dymokomi/luce-base
Source of release 0.46.0
0.46.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)