futures

Awaits all given awaitables (in order) and returns their results in a table.

Each item must implement :await() (e.g. Future/Task) — plain functions are not supported.

If any awaitable throws, the error is re-thrown and all remaining awaitables are cancelled.

Retrieves the next value from an async iterator coroutine.

Returned by futures.apairs; you probably shouldn't call it directly.

Returns first result of futures, or error.

Other awaitables will be cancelled after first result or error.

Iterates over async iterator, calling it with given arguments.

Example

---@async
---@return AsyncIterator<number>
local function count( from, to )
    for i = from, to do
        futures.yield( i )
    end
end

local function main()
    for i in futures.apairs( count, 1, 5 ) do
        print( i ) -- 1, 2, 3, 4, 5
    end
end

futures.run( main )

Cancels execution of passed coroutine.

ACTION_CANCEL will be thrown in coroutine.

NB! pcall inside coroutine can catch this error so coroutine may not be cancelled because of pcall, use futures.isCancel to detect it and rethrow.

Example

---@async
local function work()
    while true do
       print( "working" )
       sleep( 1 )
    end
end

local co = futures.run( work, function( ok, value )
    if futures.isCancel( value ) then
        -- because we cancelled coroutine
        -- ok will be false
        -- value will be `ACTION_CANCEL`
    end
end )

futures.cancel( co ) -- this will stop coroutine from executing

Collects all values from async iterator into a list.

Collects all values from async iterator into a table.

Checks whether the value is the cancellation signal thrown by futures.cancel.

Puts current coroutine to sleep until futures.wakeup is called can be used to wait for some event.

Example

---@async
local function request( url )
    local co = futures.running()

    http.Fetch( url, function( body, size, headers, code )
        futures.wakeup( co, body )
    end)

    return futures.pending() -- this will return all arguments passed to futures.wakeup
end

local function main()
    local body = request( "https://example.com" )
    print( body ) -- <!DOCTYPE html>...
end

futures.run( main )

Executes a function in a new coroutine you can use this function to call async functions even in sync code callback will be called when function returned or errored it will be called with these arguments:

• ok: boolean - whether the function returned without errors
• ... - return values of the function (or error message)

Example

---@async
local function asyncFunction( a, b )
    sleep( 1 )
    return
end

futures.run( asyncFunction, function( ok, result )
    if ok then
        print( "result:", result ) -- result: 4
    else
        print( "error:", result )
    end
end, 2, 2 ) -- 2 and 2 are arguments for asyncFunction

Puts current thread to sleep for given amount of seconds.

Transfers data between coroutines in symmetrical way used in asynchronous iterators you probably should not use it.

Used to wake up a pending coroutine.

Yields given arguments to the apairs listener.