# `nupp.runtime.services.suspension` Scheduler integration contract for `suspension` API 1. Setup imports `service` here before any consumer requires `nupp.suspension`. 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.drop 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. Sources report readiness in priority order. 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.services.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 source: function(Context, string, integer, function(): integer, (function(integer): integer)?): Source uses: function(Context, Source): nil canPark: function(Context): boolean handler: any associated: {Source}? end ``` Subscription context used to register or associate readiness sources. A subscription may use an existing Source or create a scoped one. #### Methods ##### `source` ```nupp source: function(Context, string, integer, function(): integer, (function(integer): integer)?): Source ``` Registers a source associated with this subscription. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Context` | | | `?` | `string` | | | `?` | `integer` | | | `?` | `function(): integer` | | | `?` | `(function(integer): integer)?` | | ###### Returns | Type | Description | | --- | --- | | `Source` | | ##### `uses` ```nupp uses: function(Context, Source): nil ``` Associates an existing source with this wait without changing its identity. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Context` | | | `?` | `Source` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `canPark` ```nupp canPark: function(Context): boolean ``` Reports whether the current handler can park this subscription. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Context` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | #### Fields ##### `handler` ```nupp handler: any ``` Provider-owned active handler state. ##### `associated` ```nupp associated: {Source}? ``` Sources associated with this subscription, when explicitly tracked. ### `Create` _type_ ```nupp type Create = function(body: function(A...): R...): thread ``` Coroutine construction preserving arbitrary argument and result packs. ### `Handler` _record_ ```nupp record Handler park: function(Handler, Waiting, function(): nil): nil canPark: function(Handler): boolean shutdown: function(Handler): nil end ``` Scheduler integration operations with explicit Handler receivers. park drives or yields a wait; shutdown releases handler-owned scheduling state. #### Methods ##### `park` ```nupp park: function(Handler, Waiting, function(): nil): nil ``` Parks or drives this Waiting; the callback performs subscription cleanup. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Handler` | | | `?` | `Waiting` | | | `?` | `function(): nil` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `canPark` ```nupp canPark: function(Handler): boolean ``` Reports whether this handler can park the current execution. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Handler` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `shutdown` ```nupp shutdown: function(Handler): nil ``` Releases scheduling state owned by this handler. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Handler` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ### `Installed` _record_ ```nupp record Installed drop: nosuspend function(takes self: Installed): nil release: function(self: Installed): nil co: any previous: any handler: Handler transparent: boolean restored: boolean = false released: boolean = false parks: any end ``` Handler restoration state owned by one installation. Its affine drop restores the outer context and releases registration state. #### Methods ##### `drop` ```nupp drop: nosuspend function(takes self: Installed): nil ``` Canonical non-suspending affine cleanup for the installation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `takes self` | `Installed` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `release` ```nupp release: function(self: Installed): nil ``` Restores the outer handler and releases this installation. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Installed` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields ##### `co` ```nupp co: any ``` Coroutine whose handler is installed, or the provider's main-state key. ##### `previous` ```nupp previous: any ``` Captured outer handler state restored by release. ##### `handler` ```nupp handler: Handler ``` Handler supplied by the caller. ##### `transparent` ```nupp transparent: boolean ``` Whether operations may delegate through to the outer context. ##### `restored` ```nupp restored: boolean ``` Whether the outer handler has been restored. ##### `released` ```nupp released: boolean ``` Whether installation cleanup has completed. ##### `parks` ```nupp parks: any ``` Provider bookkeeping for waits owned by this installation. ### `Provider` _interface_ ```nupp interface Provider readonly source: function( name: string, priority: integer, poll: function(): integer, wait: (function(integer): integer)?, active: (function(Source): boolean)? ): Source readonly poll: function(): integer readonly suspend: Suspend readonly install: function(handler: Handler, transparent: boolean?): affine(Installed, destroyInstalled) readonly create: Create readonly handled: function(): boolean readonly delegatedCanPark: function(): function(): boolean readonly delegatedPark: function(): function(Waiting, function(): nil): nil readonly canSuspend: function(): boolean end ``` #### Methods ##### `source` ```nupp source: function( name: string, priority: integer, poll: function(): integer, wait: (function(integer): integer)?, active: (function(Source): boolean)? ): Source ``` Registers a named poll source with a priority and optional blocking waiter. The optional active predicate controls whether the source can make progress. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | | | `priority` | `integer` | | | `poll` | `function(): integer` | | | `wait` | `(function(integer): integer)?` | | | `active` | `(function(Source): boolean)?` | | ###### Returns | Type | Description | | --- | --- | | `Source` | | ##### `poll` ```nupp poll: function(): integer ``` Polls registered sources and returns the amount of progress reported. ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `install` ```nupp install: function(handler: Handler, transparent: boolean?): affine(Installed, destroyInstalled) ``` Installs a handler and returns affine restoration state. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `handler` | `Handler` | | | `transparent` | `boolean?` | | ###### Returns | Type | Description | | --- | --- | | `affine(Installed, destroyInstalled)` | | ##### `handled` ```nupp handled: function(): boolean ``` Reports whether an installed handler owns the current suspension context. ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `delegatedCanPark` ```nupp delegatedCanPark: function(): function(): boolean ``` Captures the outer handler's park-availability query. ###### Returns | Type | Description | | --- | --- | | `function(): boolean` | | ##### `delegatedPark` ```nupp delegatedPark: function(): function(Waiting, function(): nil): nil ``` Captures the outer handler's parking operation. ###### Returns | Type | Description | | --- | --- | | `function(Waiting, function(): nil): nil` | | ##### `canSuspend` ```nupp canSuspend: function(): boolean ``` Reports whether this execution context can perform a suspension. ###### Returns | Type | Description | | --- | --- | | `boolean` | | #### Fields ##### `suspend` ```nupp suspend: Suspend ``` Subscribes once, then waits for one typed result through the active handler. ##### `create` ```nupp create: Create ``` Creates a coroutine preserving the active suspension context and result pack. ### `Source` _record_ ```nupp record Source release: nosuspend function(Source): nil releaseImpl: function(Source): nil name: string priority: integer wait: (function(integer): integer)? active: (function(Source): boolean)? sequence: integer = 0 poller: (function(): integer)? waiter: (function(integer): integer)? released: boolean = false end ``` Readiness registration shared with callers and handlers. release must be idempotent and non-suspending; provider state tracks its lifetime. #### Methods ##### `release` ```nupp release: nosuspend function(Source): nil ``` Unregisters this source without suspending; repeated calls are harmless. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Source` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `releaseImpl` ```nupp releaseImpl: function(Source): nil ``` Provider callback used by the canonical release method. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Source` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields ##### `name` ```nupp name: string ``` Diagnostic identity of the readiness source. ##### `priority` ```nupp priority: integer ``` Readiness ordering key; smaller priorities are polled first. ##### `wait` ```nupp wait: (function(integer): integer)? ``` Optional bounded blocking waiter receiving milliseconds and returning progress. ##### `active` ```nupp active: (function(Source): boolean)? ``` Optional predicate deciding whether the source has outstanding work. ##### `sequence` ```nupp sequence: integer ``` Stable registration-order tie breaker used by the provider. ##### `poller` ```nupp poller: (function(): integer)? ``` Provider-owned nonblocking readiness callback. ##### `waiter` ```nupp waiter: (function(integer): integer)? ``` Provider-owned blocking readiness callback. ##### `released` ```nupp released: boolean ``` Whether the registration has already been released. ### `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 ready: function(Waiting): boolean onResume: function(Waiting, function(): nil): nil operation: string state: any end ``` A single pending operation observed by a suspension handler. ready is monotonic once resumed; onResume installs the handler's wake callback. #### Methods ##### `ready` ```nupp ready: function(Waiting): boolean ``` Reports whether the subscription has settled. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Waiting` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `onResume` ```nupp onResume: function(Waiting, function(): nil): nil ``` Registers a wake callback for the waiting scheduler. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `Waiting` | | | `?` | `function(): nil` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields ##### `operation` ```nupp operation: string ``` Diagnostic operation name supplied to suspend. ##### `state` ```nupp state: any ``` Provider-owned settlement and subscription state. ## Functions ### `destroyInstalled` _function_ ```nupp function destroyInstalled(takes value: Installed): nil ``` Canonical affine cleanup for a handler installation. #### Arguments | Name | Type | Description | | --- | --- | --- | | `takes value` | `Installed` | | #### Returns | Type | Description | | --- | --- | | `nil` | | ## Values ### `service` _variable_ ```nupp const service: services.Service ``` Canonical suspension API 1 handle; setup selects before the public facade loads.