# `nupp.suspension.spi` Shared interfaces for scheduler integration. Importing these declarations initializes no scheduler. The facade retains the selected functions. Source, Context, Waiting, Handler, and Installed are the shared types; providers initialize these declarations or satisfy their exact signatures without replacing their nominal identities. A subscription may resume synchronously or later. It must settle a Waiting only once and run returned cleanup when the wait ends, including cancellation. Source release and Installed close must not suspend. Nested installation restores the captured handler, and transparent handlers preserve delegation to the outer scheduler. `create` propagates the suspension context into a new coroutine. Beside the interface, an implementation publishes two hooks with `rawset`: `__delegatedCanPark` and `__delegatedPark` each capture, where they are called, the handler an installation is about to displace, and answer that handler's `canPark` and `park` later. A task scope's driver defers to its host through them. The facade refuses an implementation without both. Sources report readiness in `order`, lowest first. Context.uses identifies sources needed by a wait, while canPark distinguishes schedulers that can yield from ones that must drive readiness themselves. Cancellation values must come from `nupp.runtime.cancellation`, which preserves recognition by tasks and worker providers. State belongs to one Lua state; registrations and handlers are not copied into worker lanes. ## Types ### `Context` _record_ ```nupp record Context ... ``` Subscription context used to register or associate readiness sources. A subscription may use an existing Source or create a scoped one. #### Members | Name | Kind | Description | | --- | --- | --- | | [`source`](#nupp.suspension.spi.Context.source) | method | Registers a source associated with this subscription, as nupp.suspension.spi.Provider.source registers one outside any. | | [`uses`](#nupp.suspension.spi.Context.uses) | method | Associates an existing source with this wait without changing its identity. | | [`canPark`](#nupp.suspension.spi.Context.canPark) | method | Reports whether the current handler can park this subscription. | #### `source` _method_ ```nupp source: function( self: Context, name: string, order: integer, poll: function(): integer, wait: (function(integer): integer)?, active: (function(source: Source): boolean)? ): Source ``` Registers a source associated with this subscription, as [`nupp.suspension.spi.Provider.source`](#nupp.suspension.spi.Provider.source) registers one outside any. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Context` | | | `name` | `string` | | | `order` | `integer` | | | `poll` | `function(): integer` | | | `wait` | `(function(integer): integer)?` | | | `active` | `(function(source: Source): boolean)?` | | ##### Returns | Type | Description | | --- | --- | | `Source` | | #### `uses` _method_ ```nupp uses: function(self: Context, source: Source): nil ``` Associates an existing source with this wait without changing its identity. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Context` | | | `source` | `Source` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `canPark` _method_ ```nupp canPark: function(self: Context): boolean ``` Reports whether the current handler can park this subscription. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Context` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | ### `Create` _type_ ```nupp type Create = function(body: function(A...): R...): thread ``` Coroutine construction preserving arbitrary argument and result packs. ### `Handler` _record_ ```nupp record Handler ... ``` Scheduler integration operations with explicit Handler receivers. park drives or yields a wait; shutdown releases handler-owned scheduling state. #### Members | Name | Kind | Description | | --- | --- | --- | | [`park`](#nupp.suspension.spi.Handler.park) | method | Parks or drives this Waiting; cleanup cancels the subscription. | | [`canPark`](#nupp.suspension.spi.Handler.canPark) | method | Reports whether this handler can park the current execution. | | [`shutdown`](#nupp.suspension.spi.Handler.shutdown) | method | Releases scheduling state owned by this handler. | #### `park` _method_ ```nupp park: function(self: Handler, waiting: Waiting, cleanup: function(): nil): nil ``` Parks or drives this Waiting; `cleanup` cancels the subscription. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Handler` | | | `waiting` | `Waiting` | | | `cleanup` | `function(): nil` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `canPark` _method_ ```nupp canPark: function(self: Handler): boolean ``` Reports whether this handler can park the current execution. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Handler` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `shutdown` _method_ ```nupp shutdown: function(self: Handler): nil ``` Releases scheduling state owned by this handler. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Handler` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `Installed` _record_ ```nupp record Installed is nupp.Closeable ... ``` Handler restoration state owned by one installation. Closing it restores the outer context and releases registration state. #### Members | Name | Kind | Description | | --- | --- | --- | | [`close`](#nupp.suspension.spi.Installed.close) | method | Restores the outer handler and settles every park this installation accepted, without suspending. | | [`handler`](#nupp.suspension.spi.Installed.handler) | field | Handler supplied by the caller. | | [`transparent`](#nupp.suspension.spi.Installed.transparent) | field | Whether operations may delegate through to the outer context. | #### `close` _method_ ```nupp close: @nosuspend function(takes self: Installed): nil ``` Restores the outer handler and settles every park this installation accepted, without suspending. The provider supplies it with the installation; a drain that fails leaves the installation to be closed again. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Installed` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `handler` _field_ ```nupp handler: Handler ``` Handler supplied by the caller. #### `transparent` _field_ ```nupp transparent: boolean ``` Whether operations may delegate through to the outer context. ### `Provider` _interface_ ```nupp interface Provider ... ``` #### Members | Name | Kind | Description | | --- | --- | --- | | [`priority`](#nupp.suspension.spi.Provider.priority) | field | | | [`source`](#nupp.suspension.spi.Provider.source) | method | Registers a named poll source with a poll order and optional blocking waiter. | | [`poll`](#nupp.suspension.spi.Provider.poll) | method | Polls registered sources and returns the amount of progress reported. | | [`suspend`](#nupp.suspension.spi.Provider.suspend) | field | Subscribes once, then waits for one typed result through the active handler. | | [`install`](#nupp.suspension.spi.Provider.install) | method | Installs a handler and returns affine restoration state. | | [`create`](#nupp.suspension.spi.Provider.create) | field | Creates a coroutine preserving the active suspension context and result pack. | | [`handled`](#nupp.suspension.spi.Provider.handled) | method | Reports whether an installed handler owns the current suspension context. | | [`canSuspend`](#nupp.suspension.spi.Provider.canSuspend) | method | Reports whether this execution context can perform a suspension. | #### `priority` _field_ ```nupp priority: integer? ``` `@readonly` #### `source` _method_ ```nupp source: function( name: string, order: integer, poll: function(): integer, wait: (function(integer): integer)?, active: (function(Source): boolean)? ): Source ``` `@readonly` Registers a named poll source with a poll order and optional blocking waiter. The optional active predicate controls whether the source can make progress. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | | `order` | `integer` | | | `poll` | `function(): integer` | | | `wait` | `(function(integer): integer)?` | | | `active` | `(function(Source): boolean)?` | | ##### Returns | Type | Description | | --- | --- | | `Source` | | #### `poll` _method_ ```nupp poll: function(): integer ``` `@readonly` Polls registered sources and returns the amount of progress reported. ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `suspend` _field_ ```nupp suspend: Suspend ``` `@readonly` Subscribes once, then waits for one typed result through the active handler. #### `install` _method_ ```nupp install: function(handler: Handler, transparent: boolean?): affine(Installed) ``` `@readonly` Installs a handler and returns affine restoration state. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `handler` | `Handler` | | | `transparent` | `boolean?` | | ##### Returns | Type | Description | | --- | --- | | `affine(Installed)` | | #### `create` _field_ ```nupp create: Create ``` `@readonly` Creates a coroutine preserving the active suspension context and result pack. #### `handled` _method_ ```nupp handled: function(): boolean ``` `@readonly` Reports whether an installed handler owns the current suspension context. ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `canSuspend` _method_ ```nupp canSuspend: function(): boolean ``` `@readonly` Reports whether this execution context can perform a suspension. ##### Returns | Type | Description | | --- | --- | | `boolean` | | ### `Source` _record_ ```nupp record Source ... ``` Readiness registration shared with callers and handlers. release must be idempotent and non-suspending; provider state tracks its lifetime. #### Members | Name | Kind | Description | | --- | --- | --- | | [`release`](#nupp.suspension.spi.Source.release) | method | Unregisters this source without suspending; repeated calls are harmless. | | [`name`](#nupp.suspension.spi.Source.name) | field | Diagnostic identity of the readiness source. | | [`order`](#nupp.suspension.spi.Source.order) | field | Where in a poll pass this source runs; smaller orders are polled first. | | [`wait`](#nupp.suspension.spi.Source.wait) | field | Optional bounded blocking waiter receiving milliseconds and returning progress. | | [`active`](#nupp.suspension.spi.Source.active) | field | Optional predicate deciding whether the source has outstanding work. | #### `release` _method_ ```nupp release: @nosuspend function(self: Source): nil ``` Unregisters this source without suspending; repeated calls are harmless. The provider supplies it with the registration. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Source` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `name` _field_ ```nupp name: string ``` Diagnostic identity of the readiness source. #### `order` _field_ ```nupp order: integer ``` Where in a poll pass this source runs; smaller orders are polled first. #### `wait` _field_ ```nupp wait: (function(integer): integer)? ``` Optional bounded blocking waiter receiving milliseconds and returning progress. #### `active` _field_ ```nupp active: (function(source: Source): boolean)? ``` Optional predicate deciding whether the source has outstanding work. ### `Suspend` _type_ ```nupp type Suspend = function(operation: string, subscribe: function(function(T), Context): (function()?)): T ``` Typed subscription operation preserving the result type T. The subscription returns optional cleanup and may resume synchronously. ### `Waiting` _record_ ```nupp record Waiting ... ``` A single pending operation observed by a suspension handler. ready is monotonic once resumed; onResume installs the handler's wake callback. #### Members | Name | Kind | Description | | --- | --- | --- | | [`ready`](#nupp.suspension.spi.Waiting.ready) | method | Reports whether the subscription has settled. | | [`onResume`](#nupp.suspension.spi.Waiting.onResume) | method | Registers a wake callback for the waiting scheduler. | | [`operation`](#nupp.suspension.spi.Waiting.operation) | field | Diagnostic operation name supplied to suspend. | #### `ready` _method_ ```nupp ready: function(self: Waiting): boolean ``` Reports whether the subscription has settled. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Waiting` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `onResume` _method_ ```nupp onResume: function(self: Waiting, wake: function(): nil): nil ``` Registers a wake callback for the waiting scheduler. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Waiting` | | | `wake` | `function(): nil` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `operation` _field_ ```nupp operation: string ``` Diagnostic operation name supplied to suspend.