# `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. ## Types ### `Provider` _interface_ ```nupp 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 ``` Complete worker implementation protocol, including structured-task integration. Implement generic spawn and ownership guarantees through the shared scope types. #### Methods ##### `scope` ```nupp scope: function(): affine(workers.PublicScope) ``` Creates an affine structured scope that settles children during cleanup. ###### Returns | Type | Description | | --- | --- | | `affine(workers.PublicScope)` | | ##### `openScope` ```nupp openScope: function(deadline: number?, observer: any): workers.Scope ``` 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 | | --- | --- | | `workers.Scope` | | ##### `settle` ```nupp 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` | | ##### `parallelism` ```nupp parallelism: function(): integer ``` Reports the scheduler's available worker parallelism. ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `runScheduler` ```nupp runScheduler: function(): nil ``` Runs provider scheduler progress using its retained lane state. ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `defineSendable` ```nupp defineSendable: function(moduleName: string, member: string, fn: any): nil ``` Associates an executable function with its module/member identity. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `moduleName` | `string` | | | `member` | `string` | | | `fn` | `any` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `describeSendable` ```nupp describeSendable: function(fn: any, moduleName: string, member: string, ...: any): any ``` Describes a submitted function and captures for destination-lane execution. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `fn` | `any` | | | `moduleName` | `string` | | | `member` | `string` | | | `...` | `any` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ### `PublicScope` _interface_ ```nupp interface workers.PublicScope is workers.ScopeToken readonly spawn: function( borrows self: workers.PublicScope, F, ...: unpackof workers.Submitted(F) ): workers.Task readonly close: function(borrows self: workers.PublicScope): nil readonly drop: function(takes self: workers.PublicScope): nil end ``` #### Methods ##### `spawn` ```nupp spawn: function( borrows self: workers.PublicScope, F, ...: unpackof workers.Submitted(F) ): workers.Task ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `workers.PublicScope` | | | `?` | `F` | | | `...` | `unpackof workers.Submitted(F)` | | ###### Returns | Type | Description | | --- | --- | | `workers.Task\` | | ##### `close` ```nupp close: function(borrows self: workers.PublicScope): nil ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `workers.PublicScope` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `drop` ```nupp drop: function(takes self: workers.PublicScope): nil ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `workers.PublicScope` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `Scope` _record_ ```nupp record workers.Scope is workers.ScopeToken spawn: function( borrows self: workers.Scope, F, ...: unpackof workers.Submitted(F) ): workers.Task close: function(borrows self: workers.Scope): nil drop: function(takes self: workers.Scope): nil end ``` A lexical family of parallel child tasks. #### Methods ##### `spawn` ```nupp spawn: function( borrows self: workers.Scope, F, ...: unpackof workers.Submitted(F) ): workers.Task ``` Starts one sendable function with copied arguments. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `workers.Scope` | | | `?` | `F` | | | `...` | `unpackof workers.Submitted(F)` | | ###### Returns | Type | Description | | --- | --- | | `workers.Task\` | | ##### `close` ```nupp close: function(borrows self: workers.Scope): nil ``` Waits for every child. Idempotent. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `workers.Scope` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `drop` ```nupp drop: function(takes self: workers.Scope): nil ``` Closes the scope on every structured exit. A settling terminal: under a suspension handler it parks until every child has settled, and without one it blocks. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `workers.Scope` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `ScopeToken` _interface_ ```nupp affine interface workers.ScopeToken terminal readonly drop: function(takes self: workers.ScopeToken): nil end ``` The cleanup contract a structured worker scope carries. #### Methods ##### `drop` ```nupp drop: function(takes self: workers.ScopeToken): nil ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `workers.ScopeToken` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `Submittable` _type_ ```nupp type workers.Submittable = sendable function(...: any): any ``` What 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. ### `Task` _type_ ```nupp type workers.Task = TaskType(F) ``` The typed handle for one submitted function. #### Type parameters | Name | Description | | --- | --- | | `F` | | ## Functions ### `workers.Submitted` _comptime function_ ```nupp comptime function workers.Submitted(F: type): typepack ``` The arguments a submitted function takes, once its whole signature is known to be copyable. Reached only from `spawn`: naming `Task` 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` | |