nupp.suspension

Module contents

Types

TypeKindDescription
ContextrecordSubscription context used to register or associate readiness sources.
HandlerrecordScheduler integration operations with explicit Handler receivers.
InstalledrecordHandler restoration state owned by one installation.
SourcerecordReadiness registration shared with callers and handlers.
WaitingrecordA single pending operation observed by a suspension handler.

Types#

Contextrecord#

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
NameTypeDescription
?Context
?string
?integer
?function(): integer
?(function(integer): integer)?
Returns
TypeDescription
Source
uses#
uses: function(Context, Source): nil

Associates an existing source with this wait without changing its identity.

Arguments
NameTypeDescription
?Context
?Source
Returns
TypeDescription
nil
canPark#
canPark: function(Context): boolean

Reports whether the current handler can park this subscription.

Arguments
NameTypeDescription
?Context
Returns
TypeDescription
boolean

Fields

handler#
handler: any

Provider-owned active handler state.

associated#
associated: {Source}?

Sources associated with this subscription, when explicitly tracked.

Handlerrecord#

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
NameTypeDescription
?Handler
?Waiting
?function(): nil
Returns
TypeDescription
nil
canPark#
canPark: function(Handler): boolean

Reports whether this handler can park the current execution.

Arguments
NameTypeDescription
?Handler
Returns
TypeDescription
boolean
shutdown#
shutdown: function(Handler): nil

Releases scheduling state owned by this handler.

Arguments
NameTypeDescription
?Handler
Returns
TypeDescription
nil

Installedrecord#

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
NameTypeDescription
takes selfInstalled
Returns
TypeDescription
nil
release#
release: function(self: Installed): nil

Restores the outer handler and releases this installation.

Arguments
NameTypeDescription
selfInstalled
Returns
TypeDescription
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.

Sourcerecord#

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
NameTypeDescription
?Source
Returns
TypeDescription
nil
releaseImpl#
releaseImpl: function(Source): nil

Provider callback used by the canonical release method.

Arguments
NameTypeDescription
?Source
Returns
TypeDescription
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.

Waitingrecord#

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
NameTypeDescription
?Waiting
Returns
TypeDescription
boolean
onResume#
onResume: function(Waiting, function(): nil): nil

Registers a wake callback for the waiting scheduler.

Arguments
NameTypeDescription
?Waiting
?function(): nil
Returns
TypeDescription
nil

Fields

operation#
operation: string

Diagnostic operation name supplied to suspend.

state#
state: any

Provider-owned settlement and subscription state.