nupp.workers.spi
Shared interfaces for structured worker implementations.
The workers module selects an implementation during initialization. A provider owns its lane scheduler, but uses the canonical Scope, Task, Status, and submitted-signature types declared here. A scope is reached only through a task scope's fork, which owns one privately. 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.cancellation. Blocking waits cooperate with the selected suspension implementation and must not discover implementations during settlement.
Each lane uses the artifact's immutable SPI index and loads independent module instances. Provider objects and Lua closures are never transferred between lanes.
Module contents
Types
| Type | Kind | Description |
|---|---|---|
Provider | interface | Complete worker implementation protocol, including structured-task integration. |
Scope | record | A family of parallel child tasks, owned by the task scope whose fork opened it. |
Status | type | Where a task is: waiting to start, running, or settled one of three ways. |
Submittable | type | What may actually be submitted: a module member, or an outlined literal whose effectively-final captures can be... |
Task | type | The typed handle for one started function, which nupp.tasks names Task |
Functions
| Function | Kind | Description |
|---|---|---|
Submitted | comptime function | The arguments a submitted function takes, once its whole signature is known to be copyable. |
Types#
Providerinterface#
interface Provider ...Complete worker implementation protocol, including structured-task integration. Implement generic spawn and ownership guarantees through the shared scope types.
Members
| Name | Kind | Description |
|---|---|---|
priority | field | |
openScope | method | Creates canonical scope state for task integration, with an optional monotonic deadline and observer. |
settle | method | Waits for a task and returns status, packed values, exact count, and problem. |
runScheduler | method | Runs provider scheduler progress using its retained lane state. |
defineSendable | method | Associates an executable function with its module/member identity. |
describeSendable | method | Describes a submitted function and captures for destination-lane execution. |
openScopemethod#
Creates canonical scope state for task integration, with an optional monotonic deadline and observer.
Arguments
| Name | Type | Description |
|---|---|---|
deadline | number? | |
observer | any |
Returns
| Type | Description |
|---|---|
Scope |
settlemethod#
settle: function(task: any): (string, {any}?, integer, any)Waits for a task and returns status, packed values, exact count, and problem. Status is done, failed, or cancelled; cancellation preserves its shared identity.
Arguments
| Name | Type | Description |
|---|---|---|
task | any |
Returns
| Type | Description |
|---|---|
string | |
{any}? | |
integer | |
any |
runSchedulermethod#
runScheduler: function(): nilRuns provider scheduler progress using its retained lane state.
Returns
| Type | Description |
|---|---|
nil |
Scoperecord#
record Scope ...A family of parallel child tasks, owned by the task scope whose fork opened it.
Members
| Name | Kind | Description |
|---|---|---|
spawn | method | Starts one sendable function with copied arguments. |
close | method | Waits for every child, raising the first failure nothing observed. |
Statustype#
type Status = "queued" | "running" | "done" | "failed" | "cancelled"Where a task is: waiting to start, running, or settled one of three ways.
A closed union, so a switch over it needs no else. nupp.tasks names it Status.
Submittabletype#
type Submittable = function(...: any): anyWhat may actually be submitted: a module member, or an outlined literal whose effectively-final captures can be copied to another lane. Exported so a task scope can hold its fork to the same bound without linking this module.
Tasktype#
type Task<F> = TaskType(F)The typed handle for one started function, which nupp.tasks names Task<F>.
Its await result pack is the function's, which is why this is derived from the function type rather than declared once over any. status answers a nupp.workers.spi.Status.
Type parameters
| Name | Description |
|---|---|
F |
Functions#
Submittedcomptime function#
function Submitted(F: type): typepackThe arguments a submitted function takes, once its whole signature is known to be copyable. Reached only from spawn: naming Task<F> describes a handle rather than a crossing, so a signature is held to this where it is submitted and nowhere else.
Arguments
| Name | Type | Description |
|---|---|---|
F | type |
Returns
| Type | Description |
|---|---|
typepack |