# `nupp.suspension` ## 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. ### `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. ### `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. ### `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.