nupp.suspension

Waiting without blocking the thread.

A suspension-aware call parks the frame it is in rather than stopping the process, and whoever installed a handler decides what runs meanwhile -- an event loop, a poll, the next frame.

local suspension = require("nupp.suspension")

local function readLine(reader: Reader): string
    return suspension.suspend("example.readLine", function(
        resume: function(string),
        context: suspension.Context
    ): function()
        const subscription = reader:onLine(resume)

        return function(): nil
            subscription:release()
        end
    end)
end

suspend parks on something that will be ready later, source registers the pump that makes it ready, and poll drives every registered pump once. handled says whether a handler is listening; without one a park drives those pumps on this thread and blocks after all. canSuspend returns whether a park would be permitted here at all, and create makes a coroutine that inherits the handler.

Installing a handler, and driving the parks it accepts, is the other side of this: nupp.suspension.host. A library needs none of it.

This is the layer underneath. Somewhere to put children discovered over time, with one answer for failure and cancellation, is nupp.tasks; real parallelism is nupp.workers. Come here directly to make a library waitable, or to write a combinator neither of those has.

An arbitrary blocking Lua or C call still blocks the thread. A library opts in by parking through this module; nothing intercepts calls that do not.

See Suspension.

record Context ...

source: function(
    self: Context,
    name: string,
    order: integer,
    poll: function(): integer,
    wait: (function(integer): integer)?,
    active: (function(source: Source): boolean)?
): Source

uses: function(self: Context, source: Source): nil

record Source ...

release: @nosuspend function(self: Source): nil

name: string

order: integer

wait: (function(integer): integer)?

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