nupp.tasks

Cancellationrecord#

record tasks.Cancellation
    operation: string
    reason: string?
end

What a cancelled task raises.

Nominal rather than a string, so isCancelled recognizes it without matching text, and so a program that catches everything still sees something it can ask about. tostring renders it because an uncaught one reaches a human.

Fields

operation: string

reason: string?

Scoperecord#

record tasks.Scope
    spawn: function<F>(
        borrows self: tasks.Scope,
        takes body: F,
        ...: unpackof Parameters(F)
    ): tasks.Task<F> borrows (self)
    spawnNamed: function<F>(borrows self: tasks.Scope, name: string, takes body: F): tasks.Task<F> borrows (self)
    fork: function<F is Submittable>(
        borrows self: tasks.Scope,
        F,
        ...: unpackof nupp.runtime.services.workers.Submitted(F)
    ): tasks.Task<F> borrows (self)
    cancel: function(borrows self: tasks.Scope, reason: string?): nil
end

The scope a run body is handed.

Not affine, and deliberately: run owns the extent, so there is no obligation for a body to discharge and no way for one to end the scope early. What the body can do is add children to it and reach the worker scope it owns.

Methods

spawn: function<F>(
    borrows self: tasks.Scope,
    takes body: F,
    ...: unpackof Parameters(F)
): tasks.Task<F> borrows (self)

spawnNamed: function<F>(borrows self: tasks.Scope, name: string, takes body: F): tasks.Task<F> borrows (self)

fork: function<F is Submittable>(
    borrows self: tasks.Scope,
    F,
    ...: unpackof nupp.runtime.services.workers.Submitted(F)
): tasks.Task<F> borrows (self)

cancel: function(borrows self: tasks.Scope, reason: string?): nil

Tasktype#

type tasks.Task<F> = TaskType(F)

The handle one spawn answers.

Its await result pack is the body's, which is why this is derived from the function type rather than declared once over any.

Type parameters

ForkMT.awaitfunction#

function ForkMT.await(self: any)

Arguments

ForkMT.cancelfunction#

function ForkMT.cancel(self: any, reason: string?): boolean

Arguments

Returns

ForkMT.isDonefunction#

function ForkMT.isDone(self: any): boolean

Arguments

Returns

ForkMT.statusfunction#

function ForkMT.status(self: any): string

Arguments

Returns

TaskMT.awaitfunction#

function TaskMT.await(self: any)

Arguments

TaskMT.cancelfunction#

function TaskMT.cancel(self: any, reason: string?): boolean

Arguments

Returns

TaskMT.isDonefunction#

function TaskMT.isDone(self: any): boolean

Arguments

Returns

TaskMT.statusfunction#

function TaskMT.status(self: any): string

Arguments

Returns

tasks.checkpointfunction#

function tasks.checkpoint(): nil

Raises where the current task has been cancelled or has run out of time.

The one authored cancellation point, and the only thing that reaches a body computing without parking. It never suspends, so a nosuspend region and a worker lane can both call it, and outside any task it does nothing.

for index = 1, #items do
    tasks.checkpoint()
    consume(items[index])
end

Returns

Raises

• the cancellation, where one has been requested

tasks.deadlinefunction#

function tasks.deadline(): number?

The effective deadline of the current task, or nil where there is none.

So a body can size its work rather than discover the bound by being cancelled part way through it.

Returns

tasks.gatherfunction#

function tasks.gather<T>(bodies: {function(): T}): {T?}, {any}

Runs every body concurrently and answers what each of them did, failures included.

The fail-soft family. Both arrays are indexed as bodies was, and exactly one of them holds an entry per branch, so a caller who has to see every outcome sees them beside each other. A scope is the fail-fast answer to the same question: use one where the first failure should end the rest.

const values, errors = nupp.tasks.gather({
    function(): string return fetch(primary) end,
    function(): string return fetch(mirror) end,
})

Type parameters

Arguments

Returns

Raises

• the enclosing deadline, where one passed before the family settled

tasks.isCancelledfunction#

function tasks.isCancelled(value: any): boolean

Whether a caught value is a task cancellation.

The one question a pcall around task work has to be able to ask, because cancellation is not a failure and should usually be re-raised rather than reported.

const ok, problem = pcall(work)
if not ok and not tasks.isCancelled(problem) then
    report(problem)
end

Arguments

Returns

tasks.openfunction#

function tasks.open(limit: integer?, deadline: number?): affine(tasks.Scope, tasks.settle)

Opens a scope, to be held by a with.

The block is the scope's body. Children started in it with spawn and fork are its family, and leaving the block -- normally, by break or return, or by an error -- settles them: every one has run, been cancelled, or unwound before the block is left. A child's failure is the scope's from the moment it happens, cancels its siblings, and is raised where the block is left, whether or not anything awaited that child.

With a limit, spawn and fork park while that many children are live, so a loop that fans out over a source is bounded by the loop itself: nothing is pulled from the source until there is room to run it. With a deadline, in milliseconds of the monotonic clock, expiry requests ordinary cancellation. A scope opened inside another takes the earlier of the two deadlines: a child may bound itself more tightly than its parent did, and may not extend what its parent already promised.

Both are named arguments: open(), open(limit = 8), open(deadline = 500), or open(limit = 8, deadline = 500).

const sizes: {integer} = {}
with scope = nupp.tasks.open(limit = 8) do
    for index, url in ipairs(urls) do
        scope:spawn(sizes, index, url, storeSize)
    end
end

Arguments

Returns

Raises

• where the limit is not a positive integer or the deadline is not a finite non-negative number

tasks.settlefunction#

function tasks.settle(takes scope: tasks.Scope): nil

Settles an opened scope, which is what leaving its with does.

Every child has run, been cancelled, or unwound when this returns, and the worker scope, where one was opened, has been closed through the suspension-aware path. It is a settling terminal: it parks until that is so, and so is refused inside a nosuspend region. Idempotent, so a scope settled by hand before its block ends settles once.

A failure the block itself raises does not cancel the children: they run to completion before it propagates. Call cancel first where that is not wanted.

with scope = nupp.tasks.open() do
    scope:spawn(function(): nil work() end)
end

Arguments

Returns

Raises

• the first failure a child had, or the cancellation a deadline caused