Async library

The Async library provides functions for handling asynchronous operations, such as loading a remote node database. All of these functions are contained in the “Async” Lua table found in the “async.lua” unit.

Usage example:

-- First, you need to require the “async.lua” unit
require("async.lua");

-- Now you can access the functions of the library.
Async.LIBRARY_FUNCTION(Argument1, Argument2, ...);

Async library functions

function Async.await(promise)
function await(promise)

Performs an asynchronous wait for the resolution of a Promise object, suspending the currently running coroutine until the provided Promise is resolved. While suspended, other coroutines and program execution lines can run, preventing the application from blocking or freezing. The coroutine execution is resumed once the given Promise is resolved to either success or failure

Reminder: Coroutines are computer program execution lines that can be suspended and resumed.

Arguments:

promise - A Promise object identifying the promise for which the asynchronous wait must be performed

Return:

When the wait is complete:

If the given promise resolves to success, the function returns the promise's success data.
If the given promise resolves to failure, the function raises an error with the promise's failure message.

Remarks:

Using this function can significantly simplify your code when waiting for the outcome of promises.
If the given promise has already been resolved, the await will return, or raise an error, if applicable, immediately, without suspending the execution of the current coroutine.
Keep in mind that this function works only inside coroutines. All Firecast events run inside coroutines, but you can always start a coroutine with the Async.execute function.
If you dont want automatic error raising in case the promise resolves to failure, check the similar function pawait.

function Async.execute(fn, ...)

Starts the execution of a coroutine.

Reminder: Coroutines are computer program execution lines that can be suspended and resumed.

Arguments:

fn - A function that will be executed by the coroutine.
... (variable argument list) - All given arguments will be passed to the function as arguments when it starts the execution.

Return:

A Promise object that can be used to track the execution of the coroutine. The success data of this promise will be whatever the given function returns during its execution. If an error occurs while executing the function, the promise will be resolved to failure with the failure message describing the execution error.

Remarks:

You can use the await function inside coroutines!
The coroutine starts its execution immediately. Calling Async.execute will return when the given function reaches its end, when an execution error occurs, or when it is first suspended (such as by calling `await`), whichever comes first.
If the given function returns a Promise object at the end of its execution, a delegation will occur, making the promise returned by Async.execute resolve when the mentioned Promise resolves, with the same outcome

function Async.pawait(promise)
function pawait(promise)

Similar to the await function, pawait performs an asynchronous wait for the resolution of a Promise object, suspending the currently running coroutine until the provided Promise object is resolved. However, unlike await, pawait does not automatically raise an error if the promise resolves to failure

Arguments:

promise - A Promise object identifying the promise for which the asynchronous wait must be performed

Return:

When the wait is complete, the function will return multiple values:

f the given promise resolves to success, the first returned value will be a boolean with the value true, and the second one will be the promise's success data.
If the given promise resolves to failure, the first returned value will be a boolean with the value false, and the second one will be the promise's failure message.

Remarks:

For more information, please refer to the await function documentation.

Created with the Personal Edition of HelpNDoc: Transform your help documentation into a stunning website