Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-base

Source of release 0.46.0

0.46.0 / src / std / interop / worker.lucb

#==============================================================================================
#
#   worker - A managed worker thread
#
#   DESCRIPTION:
#       A worker runs a factory-built handler on its own thread; messages are posted with
#       `send` and their replies delivered through the entry's callback.
#
#==============================================================================================

## The worker has been closed.
pub let worker_closed: ErrorCode = ErrorCode.package(104)
## The worker's queue is full.
pub let worker_busy: ErrorCode = ErrorCode.package(105)

struct WorkerState[C, M, R]:
    var mutex: sync.Mutex
    var changed: sync.Condition
    var cancellation: sync.Cancellation
    var ready: bool
    var done: bool
    var startup_error: Reply[unit]?
    var input: WorkerQueue[Packet[M]]
    var output: WorkerQueue[Reply[R]]
    let configuration: Packet[C]
    let entry: WorkerEntry[C, M, R]
    let message_transfer: Transfer[M]
    let result_transfer: Transfer[R]
    var thread: thread.Handle

    static func start(entry: WorkerEntry[C, M, R], configuration: C,
                      config_transfer: Transfer[C], message_transfer: Transfer[M], result_transfer: Transfer[R],
                      capacity: usize, stack: usize) -> WorkerState[C, M, R]*!:
        if capacity == 0:
            error(invalid, "a worker queue needs positive capacity")
        let config = try config_transfer.copy(configuration)
        errdefer config.release()
        let input = try new (Packet[M]?)[capacity] --- in memory.heap
        errdefer free(input) in memory.heap
        let output = try new (Reply[R]?)[capacity] --- in memory.heap
        errdefer free(output) in memory.heap
        let block = try new WorkerState[C, M, R][1] --- in memory.heap
        errdefer free(block) in memory.heap
        let state = &block[0]
        var mutex: sync.Mutex
        var changed: sync.Condition
        var cancellation: sync.Cancellation
        var worker_thread: thread.Handle
        *state = WorkerState[C, M, R](mutex, changed, cancellation, false, false, none,
                                      WorkerQueue[Packet[M]](input), WorkerQueue[Reply[R]](output), config,
                                      entry, message_transfer, result_transfer, worker_thread)
        state.thread = try thread.spawn(WorkerState[C, M, R].run, (void*)state, stack)
        return state

    static func run(raw: void*?):
        let state = (WorkerState[C, M, R]*)(raw else trap("a worker has no state"))
        state.entry.enter()
        active_worker_cancellation = &state.cancellation
        let opened = state.entry.open(state.entry.context, state.configuration.value)
        let handler = opened.get() catch failure:
            let saved = Reply[unit].failure(failure.code, failure.message)
            opened.release()
            state.configuration.release()
            state.mutex.lock()
            state.startup_error = saved
            state.ready = true
            state.changed.broadcast()
            state.mutex.unlock()
            WorkerState[C, M, R].finish(state)
            return
        # The Outcome owns the handler until this thread has finished delivery.
        state.configuration.release()
        state.mutex.lock()
        state.ready = true
        state.changed.broadcast()
        state.mutex.unlock()
        WorkerState[C, M, R].deliver(state, handler)
        opened.release()
        WorkerState[C, M, R].finish(state)

    static func finish(state: WorkerState[C, M, R]*):
        active_worker_cancellation = none
        state.entry.leave()
        state.mutex.lock()
        state.done = true
        state.changed.broadcast()
        state.mutex.unlock()

    static func deliver(state: WorkerState[C, M, R]*, handler: Callback[M, R]):
        while true:
            state.mutex.lock()
            while state.input.count == 0 and not state.cancellation.is_requested():
                state.changed.wait(&state.mutex)
            if state.cancellation.is_requested():
                state.mutex.unlock()
                return
            let message = state.input.pop()
            state.changed.broadcast()
            state.mutex.unlock()
            let result = handler.invoke(message.value)
            let reply = WorkerState[C, M, R].copy_reply(state, result)
            result.release()
            message.release()
            state.mutex.lock()
            while state.output.full() and not state.cancellation.is_requested():
                state.changed.wait(&state.mutex)
            if state.cancellation.is_requested():
                state.mutex.unlock()
                reply.release()
                return
            state.output.push(reply)
            state.changed.broadcast()
            state.mutex.unlock()

    ## Under the mutex: the queued reply first, or worker_closed once the worker has
    ## stopped; none while it runs with nothing queued.
    static func take_reply(state: WorkerState[C, M, R]*) -> Reply[R]?!:
        if state.cancellation.is_requested() or state.done:
            error(worker_closed, "the worker no longer produces replies")
        if state.output.count == 0:
            return none
        let result = state.output.pop()
        state.changed.broadcast()
        return result

    static func copy_reply(state: WorkerState[C, M, R]*, outcome: Outcome[R]) -> Reply[R]:
        let value = outcome.get() catch failure:
            return Reply[R].failure(failure.code, failure.message)
        let copy = state.result_transfer.copy(value) catch failure:
            return Reply[R].failure(failure.code, failure.message)
        return Reply[R].success(copy)

## A bounded persistent worker. This carrier is uniquely owned; Base copies borrow.
## send/receive/cancel may be called concurrently while the owner keeps it alive.
## close must run after those callers return; it cancels and joins before freeing.
## Luce libraries expose their own owned application-specific wrapper around it.
# mark: The worker handle ======================================================================

## A bounded persistent worker: a uniquely-owned handle over a thread, its queues and cancellation.
pub struct Worker[C, M, R]:
    var state: WorkerState[C, M, R]*?

    ## Start `entry` on a new worker thread with `configuration`, waiting until it is ready.
    pub func init(entry: WorkerEntry[C, M, R], configuration: C,
                  config_transfer: Transfer[C], message_transfer: Transfer[M], result_transfer: Transfer[R],
                  capacity: usize = 16, stack: usize = 0) -> !:
        let state = try WorkerState[C, M, R].start(entry, configuration, config_transfer,
                                                   message_transfer, result_transfer, capacity, stack)
        self.state = state
        state.mutex.lock()
        while not state.ready:
            state.changed.wait(&state.mutex)
        state.mutex.unlock()
        if let failure = state.startup_error:
            # Copy into the creator's temporary pool before joining/freeing state.
            # Native callers scope ownership.mark/drain around error consumption.
            let message = (failure.message else trap("a startup failure has no message")).value
            let saved = copy_text(message) catch exhausted:
                self.close()
                error(memory.exhausted, "out of memory copying a worker startup failure")
            let code = failure.code
            _ = ownership.pool_object(saved.owner else trap("copied text has no owner"))
            self.close()
            error(code, saved.value)

    ## Post `message` to the worker, blocking while its input queue is full.
    pub func send(message: M) -> !:
        try self.dispatch(message, true)

    ## Nonblocking backpressure: a full input queue returns worker_busy.
    pub func try_send(message: M) -> !:
        try self.dispatch(message, false)

    func dispatch(message: M, wait: bool) -> !:
        let state = self.state else error(worker_closed, "the worker is closed")
        let packet = try state.message_transfer.copy(message)
        errdefer packet.release()
        state.mutex.lock()
        defer state.mutex.unlock()
        while state.input.full() and not state.cancellation.is_requested() and not state.done:
            if not wait:
                error(worker_busy, "the worker input queue is full")
            state.changed.wait(&state.mutex)
        if state.cancellation.is_requested() or state.done:
            error(worker_closed, "the worker no longer accepts messages")
        state.input.push(packet)
        state.changed.broadcast()

    ## The next reply, waiting for it. Replies preserve accepted-message order.
    ## Cancellation is terminal: queued replies are discarded by close, and blocked
    ## receivers wake with worker_closed.
    pub func receive() -> Reply[R]!:
        let state = self.state else error(worker_closed, "the worker is closed")
        state.mutex.lock()
        defer state.mutex.unlock()
        while state.output.count == 0 and not state.cancellation.is_requested() and not state.done:
            state.changed.wait(&state.mutex)
        return try WorkerState[C, M, R].take_reply(state) else trap("a worker woke with no reply")

    ## The next reply if one is ready, none if not: a receive that never waits, for a
    ## caller that polls, as a UI frame does.
    pub func try_receive() -> Reply[R]?!:
        return try self.receive_within(0)

    ## The next reply, waiting at most about `milliseconds` for it; none when none came.
    pub func receive_within(milliseconds: u64) -> Reply[R]?!:
        let state = self.state else error(worker_closed, "the worker is closed")
        let deadline = time.now() + milliseconds * 1000000
        state.mutex.lock()
        defer state.mutex.unlock()
        while state.output.count == 0 and not state.cancellation.is_requested() and not state.done:
            let now = time.now()
            if now >= deadline:
                return none
            state.changed.wait_for(&state.mutex, (deadline - now + 999999) // 1000000)
        return try WorkerState[C, M, R].take_reply(state)

    ## Ask the worker to stop; cancellation is terminal and wakes blocked callers.
    pub func cancel():
        let state = self.state else return
        state.mutex.lock()
        state.cancellation.request()
        state.changed.broadcast()
        state.mutex.unlock()

    ## Cancel the worker, join its thread, drain its queues, and free it.
    pub func close():
        let state = self.state else return
        self.cancel()
        state.thread.join() catch failure:
            trap("a worker could not join its thread")
        self.state = none
        while state.input.count > 0:
            state.input.pop().release()
        while state.output.count > 0:
            state.output.pop().release()
        if let failure = state.startup_error:
            failure.release()
        free(state.input.slots) in memory.heap
        free(state.output.slots) in memory.heap
        free(u8[]((u8*)state, memory.size_of(WorkerState[C, M, R]))) in memory.heap