dymokomi/luce-base
Source of release 0.45.0
0.45.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