classDocs / Future

Future

classsharedsource

Object → Future

Futures are objects that hold the result that can be assigned asynchronously they can be awaited to get the result or add callback with :addCallback(...) method.

lua

local fut = futures.Future()

fut:addCallback( function( fut )
    print( fut:result() ) -- "hello world"
end )

fut:setResult( "hello world" )

-- or you can await it

---@async
local function main()
    print( fut:await() ) -- "hello world"
end

futures.run( main )

-- also you can set error or cancel it
fut:setError( "something went wrong" )
fut:cancel()

Constructor

Future(): Future

Methods

`addCallback`	Adds callback that will be called when future is done if future is already done, callback will be called immediately.
`await`	Await until future will be finished if it contains an error, then it will be thrown.
`cancel`	Tries to cancel future, if it's already done, returns false otherwise marks it as cancelled, runs all callbacks and ret…
`error`	Returns the future's error, if any: * if cancelled, returns RuntimeError "future was cancelled" * if still pending, ret…
`isCancelled`	Returns true if Future was cancelled.
`isFinished`	Returns true if Future is finished (or cancelled).
`isPending`	Returns true if Future is pending.
`removeCallback`	Removes callback that was previously added with :addCallback.
`result`	Returns result if future is finished otherwise throws an error.
`setError`	Sets error of the Future, marks it as finished, and runs all callbacks if future is already finished, error will be thr…
`setResult`	Sets result of the Future, marks it as finished, and runs all callbacks if future is already finished, error will be th…

#Future:addCallback

sharedsource

function Future:addCallback(fn: fun( fut: Future<T> ))

Adds callback that will be called when future is done if future is already done, callback will be called immediately.

Parameters

Name	Type	Description
`fn`	`fun( fut: Future<T> )`	The callback to invoke with the future once it's done.

See also

Future.removeCallback for removing callback

#Future:await

sharedasyncsource

async function Future:await(): T

Await until future will be finished if it contains an error, then it will be thrown.

Returns

Type	Name	Description
`T`

#Future:cancel

sharedsource

function Future:cancel(): boolean

Tries to cancel future, if it's already done, returns false otherwise marks it as cancelled, runs all callbacks and returns true.

Returns

Type	Name	Description
`boolean`	`cancelled`

#Future:error

sharednodiscardsource

function Future:error(): Error | nil

Returns the future's error, if any:

if cancelled, returns RuntimeError "future was cancelled"
if still pending, returns RuntimeError "future is not finished"
if finished successfully, returns nil
if finished with an error, returns that error

Returns

Type	Name	Description
`Error \| nil`

See also

Future.setError

#Future:isCancelled

sharednodiscardsource

function Future:isCancelled(): boolean

Returns true if Future was cancelled.

Returns

Type	Name	Description
`boolean`

#Future:isFinished

sharednodiscardsource

function Future:isFinished(): boolean

Returns true if Future is finished (or cancelled).

Returns

Type	Name	Description
`boolean`

#Future:isPending

sharednodiscardsource

function Future:isPending(): boolean

Returns true if Future is pending.

Returns

Type	Name	Description
`boolean`

#Future:removeCallback

sharedsource

function Future:removeCallback(fn: function)

Removes callback that was previously added with :addCallback.

Parameters

Name	Type	Description
`fn`	`function`	The callback previously passed to `:addCallback`.

See also

Future.addCallback for adding callback

#Future:result

sharednodiscardsource

function Future:result(): T

Returns result if future is finished otherwise throws an error.

Returns

Type	Name	Description
`T`

See also

Future.setResult

#Future:setError

sharedsource

function Future:setError(err: string | Error, error_class?: ErrorClass)

Sets error of the Future, marks it as finished, and runs all callbacks if future is already finished, error will be thrown.

Strings and other values are wrapped into error_class, an Error without a call stack captures the stack of the caller, an Error with one is kept as is.

Parameters

Name	Type	Description
`err`	`string \| Error`	The error to fail the future with.
`error_class`optional	`ErrorClass`	The class used to wrap `err` if it is not an `Error`, defaults to `RuntimeError`.

See also

Future.error to retrieve error

#Future:setResult

sharedsource

function Future:setResult(result: T)

Sets result of the Future, marks it as finished, and runs all callbacks if future is already finished, error will be thrown.

Parameters

Name	Type	Description
`result`	`T`	The value to resolve the future with.

See also

Future.result to retrieve result
Future.await to asynchronously retrieve result

Subclasses

futures.Task