nupp.host.spi

The interface a nupp.host implementation provides.

The facade selects one implementation when it loads: a provider discovered through nupp.spi, otherwise the embedding host natively and the page in a browser. Every function is receiver-free and takes its arguments as a flat list, so an argument list is never wrapped in a table on its way through.

The facade has already checked the kind's spelling. A provider checks the values themselves against the channel's value model -- nil, booleans, finite numbers, UTF-8 strings and byte spans -- because only the provider knows what it is about to encode, and it reports a refusal with the argument's position.

call suspends through nupp.suspension until the host answers. Should the waiting task be cancelled after the request reached the host, a later answer is handed to late rather than dropped, so a result naming a host resource is always released by someone. post never suspends and discards the answer.

Module contents

Types

TypeKindDescription
LatetypeCalled with the results of a call whose caller stopped waiting.
PolicytypeWhat a full stream does with one more message: suspend the sender until the stream ships (block, outbound only),...
Providerinterface

Types#

Latetype#

type Late = function(...: any): nil

Called with the results of a call whose caller stopped waiting.

Policytype#

type Policy = "block" | "latest" | "dropOldest"

What a full stream does with one more message: suspend the sender until the stream ships (block, outbound only), keep only the newest (latest), or drop the oldest past the limit (dropOldest).

Providerinterface#

interface Provider ...

Members

NameKindDescription
priorityfieldRanks a discovered implementation; the highest unique priority wins.
attachedmethodReports whether something is attached to answer requests at all.
callmethodSends a request and suspends until the host answers it.
postmethodQueues a request for the host without waiting for its answer.
sendmethodAppends a message to the kind's outbound stream, applying policy with limit when the stream already holds that many...
routemethodDelivers the kind's inbound messages to deliver at each turn boundary, keeping at most limit per turn as policy says.

priorityfield#

priority: integer?
@readonly

Ranks a discovered implementation; the highest unique priority wins.

attachedmethod#

attached: function(): boolean
@readonly

Reports whether something is attached to answer requests at all.

Returns
TypeDescription
boolean

callmethod#

call: function(kind: string, late: Late?, ...: any): ...any
@readonly

Sends a request and suspends until the host answers it. Raises the host's failure as an error in the caller.

Arguments
NameTypeDescription
kindstring
lateLate?
...any
Returns
TypeDescription
...any

postmethod#

post: function(kind: string, ...: any): nil
@readonly

Queues a request for the host without waiting for its answer.

Arguments
NameTypeDescription
kindstring
...any
Returns
TypeDescription
nil

sendmethod#

send: function(kind: string, policy: Policy, limit: integer, ...: any): nil
@readonly

Appends a message to the kind's outbound stream, applying policy with limit when the stream already holds that many unshipped messages.

Arguments
NameTypeDescription
kindstring
policyPolicy
limitinteger
...any
Returns
TypeDescription
nil

routemethod#

route: function(
    kind: string,
    policy: Policy,
    limit: integer,
    deliver: function(...: any): nil
): (function(): nil, function(): integer)
@readonly

Delivers the kind's inbound messages to deliver at each turn boundary, keeping at most limit per turn as policy says. Returns two functions: one stops the route when called; the other returns how many messages it has dropped.

Arguments
NameTypeDescription
kindstring
policyPolicy
limitinteger
deliverfunction(...: any): nil
Returns
TypeDescription
function(): nil
function(): integer