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

Each record declares what its holder may read and nothing else. Whatever state an implementation needs beside that is its own, kept where callers cannot reach it, so two implementations may represent a source or an installation differently and neither has to reproduce the other's layout.

A subscription may resume synchronously or later. It must settle a Waiting only once and run returned cleanup when the wait ends, including cancellation. Waiting.onResume is settle-safe: registering a waker on a wait that has already settled runs it immediately. Source release and Installed close must not suspend. Nested installation restores the captured handler, and a driver installation preserves delegation to the outer scheduler. create propagates the suspension context into a new coroutine.

Sources report readiness in order, lowest first. Context.uses identifies sources needed by a wait. Whether a park is permitted here is canSuspend, which returns for the handler in force. Cancellation values must come from nupp.suspension.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 an 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.

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

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

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

`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 a typed result through the active handler.
`install`	method	Installs a host's handler and returns affine restoration state.
`installDriver`	method	Installs a driver's handler, which stands in front of a host rather than being one: a task scope opened in a frame...
`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.
`delegatedCanPark`	method	Captures the barrier in force here, for a driver about to displace it.
`delegatedPark`	method	Captures how a wait is parked here, for a driver about to displace it.
`derive`	method	Builds a Waiting that settles when base does or when ready returns true.
`turnAvailable`	field	Whether the aggregate running here may spend another coroutine activation before it owes its host a turn.
`consumeTurn`	field	Records one coroutine activation against the current turn.
`deferTurn`	field	Parks until the host has had its turn.

`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 a typed result through the active handler.

`install`method#

install: function(handler: Handler): affine(Installed)

@readonly

Installs a host's handler and returns affine restoration state.

Arguments

Name	Type	Description
`handler`	`Handler`

Returns

Type	Description
`affine(Installed)`

`installDriver`method#

installDriver: function(handler: Handler): affine(Installed)

@readonly

Installs a driver's handler, which stands in front of a host rather than being one: a task scope opened in a frame installs one so the frame's own waits keep its children running, and it does not bound a host turn where no host is beneath it.

Arguments

Name	Type	Description
`handler`	`Handler`

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`

`delegatedCanPark`method#

delegatedCanPark: function(): function(): boolean

@readonly

Captures the barrier in force here, for a driver about to displace it.

A driver's handler changes where a branch yields and must not quietly grant permission the handler it displaced refused, so a driver takes this before it installs and delegates canPark to it. Resolved when called rather than where captured, because a host enters and leaves barriers while a driver is live.

Returns

Type	Description
`function(): boolean`

`delegatedPark`method#

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

@readonly

Captures how a wait is parked here, for a driver about to displace it.

A driver runs its own work while a frame waits and hands what it cannot satisfy to the handler it displaced, or to the blocking park where there is none. Captured like delegatedCanPark, and resolved when called.

Returns

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

`derive`method#

derive: function(
    base: Waiting,
    ready: function(): boolean,
    arm: function(wake: function(): nil): nil
): Waiting

@readonly

Builds a Waiting that settles when base does or when ready returns true.

A driver parks outward on the result, so the park it hands to its host is woken both by the wait it was given and by its own work becoming runnable. arm registers the driver's own wakers and receives the same callback base is armed with, which runs at most once per registration. Whatever routing state base carries travels with the derived wait, so a blocking park on it reaches the readiness sources the original named.

Arguments

Name	Type	Description
`base`	`Waiting`
`ready`	`function(): boolean`
`arm`	`function(wake: function(): nil): nil`

Returns

Type	Description
`Waiting`

`turnAvailable`field#

turnAvailable: (function(): boolean)?

@readonly

Whether the aggregate running here may spend another coroutine activation before it owes its host a turn.

Turn budgeting is an implementation's to offer: absent, the three leave the aggregate turn unbounded, and the facade supplies that reading. An implementation publishes all three or none.

`consumeTurn`field#

consumeTurn: (function(): nil)?

@readonly

Records one coroutine activation against the current turn.

`deferTurn`field#

deferTurn: (function(): nil)?

@readonly

Parks until the host has had its turn.

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

Settle-safe: where the wait has already settled, wake is called before this returns rather than stored. A handler may therefore arm once and then yield until ready returns true, without a recheck loop around the arming.

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

Createtype#

Handlerrecord#

Members

parkmethod#

Arguments

Returns

canParkmethod#

Arguments

Returns

shutdownmethod#

Arguments

Returns

Installedrecord#

Members

closemethod#

Arguments

Returns

handlerfield#

Providerinterface#

Members

priorityfield#

sourcemethod#

Arguments

Returns

pollmethod#

Returns

suspendfield#

installmethod#

Arguments

Returns

installDrivermethod#

Arguments

Returns

createfield#

handledmethod#

Returns

canSuspendmethod#

Returns

delegatedCanParkmethod#

Returns

delegatedParkmethod#

Returns

derivemethod#

Arguments

Returns

turnAvailablefield#

consumeTurnfield#

deferTurnfield#

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#

`Create`type#

`Handler`record#

`park`method#

`canPark`method#

`shutdown`method#

`Installed`record#

`close`method#

`handler`field#

`Provider`interface#

`priority`field#

`source`method#

`poll`method#

`suspend`field#

`install`method#

`installDriver`method#

`create`field#

`handled`method#

`canSuspend`method#

`delegatedCanPark`method#

`delegatedPark`method#

`derive`method#

`turnAvailable`field#

`consumeTurn`field#

`deferTurn`field#

`Source`record#

`release`method#

`name`field#

`order`field#

`wait`field#

`active`field#

`Suspend`type#

`Waiting`record#

`ready`method#

`onResume`method#

`operation`field#