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

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.

Types#

`Context`record#

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`	method	Registers a source associated with this subscription, as nupp.suspension.spi.Provider.source registers one outside any.
`uses`	method	Associates an existing source with this wait without changing its identity.
`canPark`	method	Reports whether the current handler can park this subscription.

`source`method#

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

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#

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#

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

Coroutine construction preserving arbitrary argument and result packs.

`Handler`record#

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`	method	Parks or drives this Waiting; cleanup cancels the subscription.
`canPark`	method	Reports whether this handler can park the current execution.
`shutdown`	method	Releases scheduling state owned by this handler.

`park`method#

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#

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#

shutdown: function(self: Handler): nil

Releases scheduling state owned by this handler.

Arguments

Name	Type	Description
`self`	`Handler`

Returns

Type	Description
`nil`

`Installed`record#

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`	method	Restores the outer handler and settles every park this installation accepted, without suspending.
`handler`	field	Handler supplied by the caller.
`transparent`	field	Whether operations may delegate through to the outer context.

`close`method#

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#

handler: Handler

Handler supplied by the caller.

`transparent`field#

transparent: boolean

Whether operations may delegate through to the outer context.

`Provider`interface#

interface Provider ...

Members

Name	Kind	Description
`priority`	field
`source`	method	Registers a named poll source with a poll order and optional blocking waiter.
`poll`	method	Polls registered sources and returns the amount of progress reported.
`suspend`	field	Subscribes once, then waits for one typed result through the active handler.
`install`	method	Installs a handler and returns affine restoration state.
`create`	field	Creates a coroutine preserving the active suspension context and result pack.
`handled`	method	Reports whether an installed handler owns the current suspension context.
`canSuspend`	method	Reports whether this execution context can perform a suspension.

`priority`field#

priority: integer?

@readonly

`source`method#

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#

poll: function(): integer

@readonly

Polls registered sources and returns the amount of progress reported.

Returns

Type	Description
`integer`

`suspend`field#

suspend: Suspend

@readonly

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

`install`method#

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#

create: Create

@readonly

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

`handled`method#

handled: function(): boolean

@readonly

Reports whether an installed handler owns the current suspension context.

Returns

Type	Description
`boolean`

`canSuspend`method#

canSuspend: function(): boolean

@readonly

Reports whether this execution context can perform a suspension.

Returns

Type	Description
`boolean`

`Source`record#

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`	method	Unregisters this source without suspending; repeated calls are harmless.
`name`	field	Diagnostic identity of the readiness source.
`order`	field	Where in a poll pass this source runs; smaller orders are polled first.
`wait`	field	Optional bounded blocking waiter receiving milliseconds and returning progress.
`active`	field	Optional predicate deciding whether the source has outstanding work.

`release`method#

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#

name: string

Diagnostic identity of the readiness source.

`order`field#

order: integer

Where in a poll pass this source runs; smaller orders are polled first.

`wait`field#

wait: (function(integer): integer)?

Optional bounded blocking waiter receiving milliseconds and returning progress.

`active`field#

active: (function(source: Source): boolean)?

Optional predicate deciding whether the source has outstanding work.

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

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`	method	Reports whether the subscription has settled.
`onResume`	method	Registers a wake callback for the waiting scheduler.
`operation`	field	Diagnostic operation name supplied to suspend.

`ready`method#

ready: function(self: Waiting): boolean

Reports whether the subscription has settled.

Arguments

Name	Type	Description
`self`	`Waiting`

Returns

Type	Description
`boolean`

`onResume`method#

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#

operation: string

Diagnostic operation name supplied to suspend.

nupp.suspension.spi

Module contents

Types

Types#

Contextrecord#

Members

sourcemethod#

Arguments

Returns

usesmethod#

Arguments

Returns

canParkmethod#

Arguments

Returns

Createtype#

Handlerrecord#

Members

parkmethod#

Arguments

Returns

canParkmethod#

Arguments

Returns

shutdownmethod#

Arguments

Returns

Installedrecord#

Members

closemethod#

Arguments

Returns

handlerfield#

transparentfield#

Providerinterface#

Members

priorityfield#

sourcemethod#

Arguments

Returns

pollmethod#

Returns

suspendfield#

installmethod#

Arguments

Returns

createfield#

handledmethod#

Returns

canSuspendmethod#

Returns

Sourcerecord#

Members

releasemethod#

Arguments

Returns

namefield#

orderfield#

waitfield#

activefield#

Suspendtype#

Waitingrecord#

Members

readymethod#

Arguments

Returns

onResumemethod#

Arguments

Returns

operationfield#

`nupp.suspension.spi`

`Context`record#

`source`method#

`uses`method#

`canPark`method#

`Create`type#

`Handler`record#

`park`method#

`canPark`method#

`shutdown`method#

`Installed`record#

`close`method#

`handler`field#

`transparent`field#

`Provider`interface#

`priority`field#

`source`method#

`poll`method#

`suspend`field#

`install`method#

`create`field#

`handled`method#

`canSuspend`method#

`Source`record#

`release`method#

`name`field#

`order`field#

`wait`field#

`active`field#

`Suspend`type#

`Waiting`record#

`ready`method#

`onResume`method#

`operation`field#