Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.4

0.7.4 / src / parallel / jobs.lucb

#==============================================================================================
#
#   jobs - Items started in the background, to poll or wait on later
#
#   DESCRIPTION:
#       `start(count, context, work)` hands `count` items to the pool and returns at once
#       with a `Job`; the starting thread goes on with its own work, asks `completed()` or
#       `progress()` now and then, and calls `wait()` once, which helps with any items
#       still waiting for a thread, returns the first error, and frees the job.
#
#==============================================================================================

## Items running in the background, from `start`. The starting thread owns it and uses it
## from one thread at a time: `completed` and `progress` poll, and `wait` must be called
## exactly once, whatever happens, since it is what frees the job; a copy of a `Job` names
## the same job, so only one copy is waited on. A job dropped without `wait` keeps running
## to its end; its few hundred bytes are never freed and its error is never seen. Either
## way the context and everything the items touch must stay valid until `wait` returns.
pub struct Job:
    var batch: Batch*?
    var count: usize

    ## Whether every item has returned, or a failure has stopped the job and its running
    ## items have returned: `wait` then returns at once. It does not block.
    pub func completed() -> bool:
        let batch = self.batch else return true
        waits.lock.lock()
        let stopped = batch.failed.load(.relaxed) or batch.next.load(.relaxed) >= batch.count
        let done = stopped and batch.working.load(.relaxed) == 0
        waits.lock.unlock()
        return done

    ## How many items have returned so far, failed ones included, out of `count`: for
    ## reporting progress.
    pub func progress() -> usize:
        let batch = self.batch else return self.count
        return batch.finished.load(.acquire)

    ## Wait for the job's items and free the job: the first error an item returned, if
    ## any. Items no pool thread has taken yet run here, so a job finishes even when every
    ## pool thread is busy. Waiting again does nothing.
    pub func wait() -> !:
        let batch = self.batch else return
        self.batch = none
        defer free(batch) in memory.heap
        # help with what is left, under the next worker number if there is one
        waits.lock.lock()
        var helping = false
        let worker = batch.taken
        if batch.queued and batch.taken < batch.slots:
            batch.taken += 1
            _ = places.sub(1, .relaxed)
            helping = true
        waits.lock.unlock()
        if helping:
            work_on(batch, worker)
        finish(batch)
        if let code = batch.code:
            error(code, batch.message)

## Start calling `work(context, index, worker)` for every index below `count` on the pool's
## threads, at most `workers(count, threads)` of them, and return at once with the `Job`
## that tracks them; `wait` collects them. Items run as `for_each`'s do on pool threads,
## each thread's in a runtime context of its own, under worker numbers below
## `workers(count, threads)`, and the first error stops the rest. Pool threads take
## `for_each` calls' items before a job's, so a job uses the threads the calls leave idle;
## a job of long items still holds the threads it has until they return, so leave room
## with `threads`. On a pool thread, inside another call's or job's item, and when the pool
## has no thread to give, the items run here before `start` returns: a job never waits on
## a pool that is busy with its own starter. The only error is running out of memory.
pub func start(count: usize, context: void*, work: func(void*, usize, usize) -> unit!, threads: usize = 0) -> Job!:
    if count == 0:
        return Job(batch = none, count = 0)
    let batch = try new Batch(context = context, work = work, count = count, background = true, slots = workers(count, threads)) in memory.heap
    if on_pool or not post(batch):
        work_on(batch, 0)
    return Job(batch = batch, count = count)