`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.

Module contents

Types

Type	Kind	Description
`Context`	record	Subscription context used to register or associate readiness sources.
`Create`	type	Coroutine construction preserving arbitrary argument and result packs.
`Handler`	record	Scheduler integration operations with explicit Handler receivers.
`Installed`	record	Handler restoration state owned by one installation.
`Provider`	interface
`Source`	record	Readiness registration shared with callers and handlers.
`Suspend`	type	Typed subscription operation preserving the result type T.
`Waiting`	record	A single pending operation observed by a suspension handler.

Functions

Function	Kind	Description
`destroyInstalled`	function	Canonical affine cleanup for a handler installation.

Values

Value	Kind	Description
`service`	variable	Canonical suspension API 1 handle; setup selects before the public facade loads.

Types#

`Context`record#

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`#

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`#

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`#

canPark: function(Context): boolean

Reports whether the current handler can park this subscription.

Arguments

Name	Type	Description
`?`	`Context`

Returns

Type	Description
`boolean`

Fields

`handler`#

handler: any

Provider-owned active handler state.

`associated`#

associated: {Source}?

Sources associated with this subscription, when explicitly tracked.

`Create`type#

type Create = function<A..., R...>(body: function(A...): R...): thread

Coroutine construction preserving arbitrary argument and result packs.

`Handler`record#

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`#

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`#

canPark: function(Handler): boolean

Reports whether this handler can park the current execution.

Arguments

Name	Type	Description
`?`	`Handler`

Returns

Type	Description
`boolean`

`shutdown`#

shutdown: function(Handler): nil

Releases scheduling state owned by this handler.

Arguments

Name	Type	Description
`?`	`Handler`

Returns

Type	Description
`nil`

`Installed`record#

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`#

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`#

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`#

co: any

Coroutine whose handler is installed, or the provider's main-state key.

`previous`#

previous: any

Captured outer handler state restored by release.

`handler`#

handler: Handler

Handler supplied by the caller.

`transparent`#

transparent: boolean

Whether operations may delegate through to the outer context.

`restored`#

restored: boolean

Whether the outer handler has been restored.

`released`#

released: boolean

Whether installation cleanup has completed.

`parks`#

parks: any

Provider bookkeeping for waits owned by this installation.

`Provider`interface#

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`#

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`#

poll: function(): integer

Polls registered sources and returns the amount of progress reported.

Returns

Type	Description
`integer`

`install`#

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`#

handled: function(): boolean

Reports whether an installed handler owns the current suspension context.

Returns

Type	Description
`boolean`

`delegatedCanPark`#

delegatedCanPark: function(): function(): boolean

Captures the outer handler's park-availability query.

Returns

Type	Description
`function(): boolean`

`delegatedPark`#

delegatedPark: function(): function(Waiting, function(): nil): nil

Captures the outer handler's parking operation.

Returns

Type	Description
`function(Waiting, function(): nil): nil`

`canSuspend`#

canSuspend: function(): boolean

Reports whether this execution context can perform a suspension.

Returns

Type	Description
`boolean`

Fields

`suspend`#

suspend: Suspend

Subscribes once, then waits for one typed result through the active handler.

`create`#

create: Create

Creates a coroutine preserving the active suspension context and result pack.

`Source`record#

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`#

release: nosuspend function(Source): nil

Unregisters this source without suspending; repeated calls are harmless.

Arguments

Name	Type	Description
`?`	`Source`

Returns

Type	Description
`nil`

`releaseImpl`#

releaseImpl: function(Source): nil

Provider callback used by the canonical release method.

Arguments

Name	Type	Description
`?`	`Source`

Returns

Type	Description
`nil`

Fields

`name`#

name: string

Diagnostic identity of the readiness source.

`priority`#

priority: integer

Readiness ordering key; smaller priorities are polled first.

`wait`#

wait: (function(integer): integer)?

Optional bounded blocking waiter receiving milliseconds and returning progress.

`active`#

active: (function(Source): boolean)?

Optional predicate deciding whether the source has outstanding work.

`sequence`#

sequence: integer

Stable registration-order tie breaker used by the provider.

`poller`#

poller: (function(): integer)?

Provider-owned nonblocking readiness callback.

`waiter`#

waiter: (function(integer): integer)?

Provider-owned blocking readiness callback.

`released`#

released: boolean

Whether the registration has already been released.

`Suspend`type#

type Suspend = function<T>(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#

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`#

ready: function(Waiting): boolean

Reports whether the subscription has settled.

Arguments

Name	Type	Description
`?`	`Waiting`

Returns

Type	Description
`boolean`

`onResume`#

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`#

operation: string

Diagnostic operation name supplied to suspend.

`state`#

state: any

Provider-owned settlement and subscription state.

Functions#

`destroyInstalled`function#

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#

const service: services.Service<Provider>

Canonical suspension API 1 handle; setup selects before the public facade loads.

nupp.runtime.services.suspension

Module contents

Types

Functions

Values

Types#

Contextrecord#

Methods

source#

Arguments

Returns

uses#

Arguments

Returns

canPark#

Arguments

Returns

Fields

handler#

associated#

Createtype#

Handlerrecord#

Methods

park#

Arguments

Returns

canPark#

Arguments

Returns

shutdown#

Arguments

Returns

Installedrecord#

Methods

drop#

Arguments

Returns

release#

Arguments

Returns

Fields

co#

previous#

handler#

transparent#

restored#

released#

parks#

Providerinterface#

Methods

source#

Arguments

Returns

poll#

Returns

install#

Arguments

Returns

handled#

Returns

delegatedCanPark#

Returns

delegatedPark#

Returns

canSuspend#

Returns

Fields

suspend#

create#

Sourcerecord#

Methods

release#

Arguments

Returns

releaseImpl#

Arguments

Returns

Fields

name#

priority#

`nupp.runtime.services.suspension`

`Context`record#

`source`#

`uses`#

`canPark`#

`handler`#

`associated`#

`Create`type#

`Handler`record#

`park`#

`canPark`#

`shutdown`#

`Installed`record#

`drop`#

`release`#

`co`#

`previous`#

`handler`#

`transparent`#

`restored`#

`released`#

`parks`#

`Provider`interface#

`source`#

`poll`#

`install`#

`handled`#

`delegatedCanPark`#

`delegatedPark`#

`canSuspend`#

`suspend`#

`create`#

`Source`record#

`release`#

`releaseImpl`#

`name`#

`priority`#

`wait`#

`active`#

`sequence`#

`poller`#

`waiter`#

`released`#

`Suspend`type#

`Waiting`record#

`ready`#

`onResume`#

`operation`#

`state`#

`destroyInstalled`function#

`service`variable#