Module async
Utilities to work with asynchronous callback-style control flow.
All callbacks must adhere to the callback signature: function(err, values...).
The first parameter is the error value. It will be nil if no error ocurred, otherwise
the error value depends on the function that the callback was passed to.
If no error ocurred, an arbitrary number of return values may be received as second parameter and onward.
Depending on the particular implementation of a function that a callback is passed to, it may be possible to
receive non-nil return values, even when an error ocurred. Using such return values should be considered undefined
behavior, unless explicitly documented by the calling function.
Table of contents
Functions
| once([fn]) | Wraps a function such that it can only ever be called once. |
| wrap_sync(fn) | Turns an asynchronous function into a blocking operation. |
| waterfall(tasks, final_callback) | Executes a list of asynchronous functions in series. |
| all(tasks, final_callback) | Runs all tasks in parallel and collects the results. |
| dag(tasks, final_callback) | Resolves a DAG (Directed Acyclic Graph) of asynchronous dependencies. |
| do_while(iteratee, test, final_callback) | Repeatedly calls test and iteratee until stopped. |
| callback([object], fn, ...) | Wrap a function with arguments for use as callback. |
Functions
If the returned function is called multiple times, only the first call will result in the wrapped function being called. Subsequent calls will be ignored. If no function is given, a noop function will be used.
Parameters:
-
fn : The function to wrap.
Returns:
-
The wrapped function or a noop.
Using coroutines, this runs a callback-style asynchronous function and blocks until it completes.
The function to be wrapped may only accept a single parameter: a callback function.
Return values passed to this callback will be returned as regular values by wrap_sync.
Panics that happened inside the asynchronous function will be captured and re-thrown.
Parameters:
-
fn : An asynchronous function:
function(cb)
Returns:
-
Any return values as passed by the wrapped function
waterfall accepts an arbitrary list of asynchronous functions (tasks) and calls them in series.
Each function waits for the previous one to finish and will be given the previous function’s return values.
If an error occurs in any task, execution is stopped immediately, and the final callback is called with the error value. If all tasks complete successfully, the final callback will be called with the return values of the last task in the list.
All tasks must adhere to the callback signature: function(err, ...).
Parameters:
-
tasks : The asynchronous tasks to execute in series.
-
final_callback : Called when all tasks have finished.
Callback parameters:
-
The error returned by a failing task.
-
Values as returned by the last task.
If any task produces an error, final_callback will be called immediately
and remaining tasks will not be tracked.
Parameters:
-
tasks : A list of asynchronous functions. They will be given a callback parameter:
function(err, ...). -
final_callback
The task list is a key-value map, where the key defines the task name and the value the is the task definition.
A task definition consists of a a list of dependencies (which may be empty) and an asynchronous
function.
Any task name may be used as dependency for any other task, as long as no loops are created.
A task’s function will be called once all of its dependencies have become available and will be passed a results
table that contains the values returned by all tasks so far.
If any tasks passes an error to its callback, execution and tracking for all other tasks stops and final_callback
is called with that error value. Otherwise, final_callback will be called once all tasks have completed, with the
results of all tasks.
The results table uses the task name as key and provides a table.packed list of task results as value.
Parameters:
-
tasks : A map of asynchronous tasks.
-
final_callback
Callback parameters:
-
Any error from a failing task.
-
Results of all resolved tasks.
Usage:
async.dag(
{
get_data = { function(cb)
local f = fs.open("/tmp/foo.txt")
f:read(cb)
end },
make_folder = { function(cb)
fs.make_folder("/tmp/bar", cb)
end },
write_data = { "get_data", "make_folder", function(results, cb)
local data = table.unpack(results.get_data)
local f = fs.open("/tmp/bar/foo.txt")
f:write(data, cb)
end },
},
function(err, results)
if err ~= nil then
error(err)
else
print("success")
end
end
)
test and iteratee until stopped.
iteratee is called repeatedly. It is passed a callback
(function(err, ...)), which should be called with either an error or any
results of the iteration.
test is called once per iteration, after iteratee. It is passed a
callback (function(err, stop)) and any non-error values from iteratee.
The callback should be called with either an error or a boolean value.
Iteration will stop when an error is passed by either callback or when
test passes a falsy value.
In either case final_callback will be called with the latest results from
iteratee.
This is, in concept, analogous to a do {} while () construct, where iteratee
is the do block and test is the while test.
Parameters:
-
iteratee : Called repeatedly. Signature:
function(cb). -
test : Called once per iteration, after
iteratee. Signature:function(..., cb). -
final_callback : Called once, when
testindicates to stop the iteration.
Callback parameters:
-
Any error from
iterateeortest. -
Values passed by the most recent execution of
iteratee.
This may be used to wrap a function or table method as a callback, providing a (partial) argument list. Arguments to this call are passed through to the provided function when it is called, arguments from the final caller are appended after those.
If the function is actually a method (i.e. it expects a self parameter or is called with :),
the self table can be passed as the first argument. Otherwise, nil should be passed.
Parameters:
-
object : The object to call the method on.
-
fn : The function to wrap.
-
... : Arbitrary arguments to pass through to the wrapped function.