Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.45.0

0.45.0 / src / std / interop / callback.lucb

#==============================================================================================
#
#   callback - A retained callable carrier
#
#   DESCRIPTION:
#       Copying the carrier borrows; cloning acquires an edge. Managed closures use their
#       existing owner, so captures remain visible to ARC.
#
#==============================================================================================

## A retained callable. Copying this carrier borrows; cloning acquires an edge.
## Managed closures use their existing owner, so captures remain visible to ARC.
pub struct Callback[A, R]:
    ## The retained object the callable belongs to.
    pub let owner: ownership.Object*
    ## Adapter identity. Call through invoke to retain the owner and check affinity.
    pub let entry: func(ownership.Object*, A) -> Outcome[R]
    let context: u64

    ## A callback over `owner`, called through `entry`.
    pub func init(owner: ownership.Object*, entry: func(ownership.Object*, A) -> Outcome[R]):
        ownership.check_alive(owner)
        self.owner = owner
        self.entry = entry
        self.context = ownership.context_id()

    func require_thread():
        if self.context != ownership.context_id():
            trap("a callback belongs to another runtime thread")

    ## Another edge to the same callable.
    pub func clone() -> Callback[A, R]:
        self.require_thread()
        _ = ownership.retain(self.owner)
        return self

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

    ## Call the callable with `argument`, retaining the owner across the call.
    pub func invoke(argument: A) -> Outcome[R]:
        self.require_thread()
        _ = ownership.retain(self.owner)
        defer ownership.release_held(self.owner)
        return self.entry(self.owner, argument)

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

    ## Native methods receive stable storage under the source owner's call guard.
    pub static func bind[T](source: Reference[T], method: func(const T*, A) -> Outcome[R]) -> Callback[A, R]!:
        return try BoundCallback[T, A, R].make(source, none, method)

    ## A callback bound to a method of a native `source` that changes it.
    pub static func bind_mutating[T](source: Reference[T], method: func(T*, A) -> Outcome[R]) -> Callback[A, R]!:
        return try BoundCallback[T, A, R].make(source, method, none)

struct BoundCallback[T, A, R]:
    var header: ownership.Object
    var information: ownership.Info
    var source: Reference[T]
    var method: (func(T*, A) -> Outcome[R])?
    var read: (func(const T*, A) -> Outcome[R])?

    static func make(source: Reference[T], method: (func(T*, A) -> Outcome[R])?,
                     read: (func(const T*, A) -> Outcome[R])?) -> Callback[A, R]!:
        _ = try source.get()
        var information = ownership.Info(name = "bound native callback", size = memory.size_of(BoundCallback[T, A, R]),
                                         finish = none, drop = BoundCallback[T, A, R].drop, trace = BoundCallback[T, A, R].trace)
        let bound = (BoundCallback[T, A, R]*)try ownership.reserve(&information, memory.size_of(BoundCallback[T, A, R]))
        bound.information = information
        bound.header.info = &bound.information
        bound.source = source.clone()
        bound.method = method
        bound.read = read
        return Callback[A, R](&bound.header, BoundCallback[T, A, R].invoke)

    static func invoke(object: ownership.Object*, argument: A) -> Outcome[R]:
        let bound = (BoundCallback[T, A, R]*)object
        let native = bound.source.get() catch failure:
            return failed_outcome[R](failure.code, failure.message)
        bound.source.enter()
        defer bound.source.leave()
        if let method = bound.method:
            return method(native, argument)
        return (bound.read else trap("a callback binding has no method"))(native, argument)

    static func drop(object: ownership.Object*):
        ((BoundCallback[T, A, R]*)object).source.release()

    static func trace(object: ownership.Object*, visit: func(ownership.Object*, void*) -> unit, context: void*):
        ((BoundCallback[T, A, R]*)object).source.trace(visit, context)

## Error views may borrow a closing source. Copy before releasing that source;
## allocation failure itself has a static message and needs no further allocation.
func failed_outcome[T](code: ErrorCode, message: str) -> Outcome[T]:
    let owned = copy_text(message) catch failure:
        return Outcome[T].failure(memory.exhausted, Owned[str]("out of memory copying a callback failure"))
    return Outcome[T].failure(code, owned)