nupp.runtime.services.workers

Typed structured-worker contract for host.workers API 1.

Import service to select an implementation before requiring nupp.workers. A provider owns its lane scheduler, but uses the canonical Scope, PublicScope, ScopeToken, Task, and submitted-signature types declared here. Generic spawn must preserve the exact argument and result packs of the sendable function.

Arguments and results cross isolated Lua states as copies. Only explicitly supported engine-backed affine owners move; arbitrary closures, pointers, coroutines, and Lua-owned affine resources cannot be copied as task arguments. Runtime validation must also reject unsupported value graphs that static types cannot exclude. A task's result count preserves embedded and trailing nil values. await returns that exact pack or raises failure/cancellation; isDone reports terminal settlement, status reports scheduler state, and cancel reports whether it made the first cancellation request.

Scope cleanup settles all children, including those never awaited, before propagating unobserved failure. Cancellation uses nupp.runtime.services.cancellation. Blocking waits cooperate with the selected suspension implementation and must not acquire a new service during settlement.

Before loading child consumers, initialize each lane from the artifact catalog, replay catalog-backed named selections, and require setup modules registered with nupp.services.setupWorkers. Capture that configuration before workers become active. Instances and Lua closures are never transferred; runtime-only registrations require explicit setup in the destination state.

interface workers.Provider
    readonly scope: function(): affine(workers.PublicScope)
    readonly openScope: function(deadline: number?, observer: any): workers.Scope
    readonly settle: function(task: any): (string, {any}?, integer, any)
    readonly parallelism: function(): integer
    readonly runScheduler: function(): nil
    readonly defineSendable: function(moduleName: string, member: string, fn: any): nil
    readonly describeSendable: function(fn: any, moduleName: string, member: string, ...: any): any
end

scope: function(): affine(workers.PublicScope)

openScope: function(deadline: number?, observer: any): workers.Scope

settle: function(task: any): (string, {any}?, integer, any)

parallelism: function(): integer

runScheduler: function(): nil

defineSendable: function(moduleName: string, member: string, fn: any): nil

describeSendable: function(fn: any, moduleName: string, member: string, ...: any): any

interface workers.PublicScope is workers.ScopeToken
    readonly spawn: function<F is workers.Submittable>(
        borrows self: workers.PublicScope,
        F,
        ...: unpackof workers.Submitted(F)
    ): workers.Task<F>
    readonly close: function(borrows self: workers.PublicScope): nil
    readonly drop: function(takes self: workers.PublicScope): nil
end

spawn: function<F is workers.Submittable>(
    borrows self: workers.PublicScope,
    F,
    ...: unpackof workers.Submitted(F)
): workers.Task<F>

close: function(borrows self: workers.PublicScope): nil

drop: function(takes self: workers.PublicScope): nil

record workers.Scope is workers.ScopeToken
    spawn: function<F is workers.Submittable>(
        borrows self: workers.Scope,
        F,
        ...: unpackof workers.Submitted(F)
    ): workers.Task<F>
    close: function(borrows self: workers.Scope): nil
    drop: function(takes self: workers.Scope): nil
end

spawn: function<F is workers.Submittable>(
    borrows self: workers.Scope,
    F,
    ...: unpackof workers.Submitted(F)
): workers.Task<F>

close: function(borrows self: workers.Scope): nil

drop: function(takes self: workers.Scope): nil

affine interface workers.ScopeToken
    terminal readonly drop: function(takes self: workers.ScopeToken): nil
end

drop: function(takes self: workers.ScopeToken): nil

type workers.Submittable = sendable function(...: any): any

type workers.Task<F is Callable> = TaskType(F)

comptime function workers.Submitted(F: type): typepack