dymokomi/luce-base
Source of release 0.44.0
0.44.0 / src / std / interop / view.lucb
#==============================================================================================
#
# view - An exported borrowed native struct
#
# DESCRIPTION:
# A checked view of a borrowed native struct, never copied into ownership of the resource
# it describes; every operation checks its validity lease.
#
#==============================================================================================
## An explicit export of a borrowed native struct. Its complete native data is a
## view, never copied into ownership of the resource it describes.
pub struct ViewType[T]:
## The view type's name.
pub let name: str
## Whether the view allows mutable access.
pub let mutable: bool = false
## The owner shell backing a checked view.
pub struct ViewOwner[T]:
## The shared collector header.
pub var header: ownership.Object
var information: ownership.Info
var native: T
var declaration: ViewType[T]
var lease: Lease
## Release the view's lease when the owner is dropped.
pub static func drop_view(object: ownership.Object*):
((ViewOwner[T]*)object).lease.release()
## Visit the lease's strong references.
pub static func trace_view(object: ownership.Object*, visit: func(ownership.Object*, void*) -> unit, context: void*):
((ViewOwner[T]*)object).lease.trace(visit, context)
## Manual Base carrier for a checked view. The Luce adapter shares this owner and
## retains it in aliases/bound methods; every operation checks its lease again.
pub struct View[T]:
## The owner shell this view shares.
pub let owner: ViewOwner[T]*
## A view over `owner`, which is already alive.
pub func init(owner: ViewOwner[T]*):
ownership.check_alive(&owner.header)
self.owner = owner
## A view of `native`, valid while `lease` is.
pub static func make(native: T, declaration: ViewType[T], lease: Lease) -> View[T]!:
try lease.check()
var information = ownership.Info(name = declaration.name, size = memory.size_of(ViewOwner[T]),
finish = none, drop = ViewOwner[T].drop_view, trace = ViewOwner[T].trace_view)
let owner = (ViewOwner[T]*)try ownership.reserve(&information, memory.size_of(ViewOwner[T]))
owner.information = information
owner.header.info = &owner.information
owner.native = native
owner.declaration = declaration
owner.lease = lease.clone()
return View[T](owner)
## Another strong reference to the same view.
pub func clone() -> View[T]:
_ = ownership.retain(&self.owner.header)
return self
## Drop this view's edge.
pub func release():
ownership.release_held(&self.owner.header)
## A read-only pointer to the value, after checking the lease.
pub func get() -> const T*!:
ownership.check_alive(&self.owner.header)
try self.owner.lease.check()
return &self.owner.native
## A mutable pointer to the value, when the view is mutable.
pub func get_mut() -> T*!:
_ = try self.get()
if not self.owner.declaration.mutable:
error(invalid, "a native view is read-only")
return &self.owner.native
## The value, trapping if the lease has expired.
pub func value() -> const T*:
return self.get() catch failure:
ownership.stop_at_site(failure.message)
trap(failure.message)
## The mutable value, trapping when unavailable.
pub func value_mut() -> T*:
return self.get_mut() catch failure:
ownership.stop_at_site(failure.message)
trap(failure.message)
## Whether the view's lease is still valid.
pub func is_valid() -> bool:
ownership.check_alive(&self.owner.header)
return self.owner.lease.is_valid()
## Begin a guarded invocation, retaining the owner.
pub func enter() -> !:
ownership.check_alive(&self.owner.header)
try self.owner.lease.enter()
_ = ownership.retain(&self.owner.header)
## End a guarded invocation.
pub func leave():
ownership.check_alive(&self.owner.header)
self.owner.lease.leave()
ownership.release_held(&self.owner.header)
## Validate that `object` is a live view of this type.
pub static func validate_interface(object: ownership.Object*) -> !:
_ = try View[T]((ViewOwner[T]*)object).get()
## Begin a guarded invocation for an interface witness.
pub static func begin_interface(object: ownership.Object*):
View[T]((ViewOwner[T]*)object).enter() catch failure:
ownership.stop_at_site(failure.message)
trap(failure.message)
## End a guarded invocation for an interface witness.
pub static func end_interface(object: ownership.Object*):
View[T]((ViewOwner[T]*)object).leave()
## The witness borrows this view's storage and preserves its validity lease.
pub func as_interface[I](native: I) -> Interface[I]:
return Interface[I](&self.owner.header, native, View[T].validate_interface,
View[T].begin_interface, View[T].end_interface).clone()
## Visit the owner as a strong reference.
pub func trace(visit: func(ownership.Object*, void*) -> unit, context: void*):
ownership.check_thread(&self.owner.header)
visit(&self.owner.header, context)