Async

Async

Async is a library for LÖVE that uses a pool of worker threads do complete tasks asynchronously.
Note that at the moment every thread using this library has its own worker thread pool, this is not shared.

Functions

async.load(numthreads = 1)

Starts the library with numthreads initial worker threads.

async.shutdown()

Stops all workers (when they have finished their current tasks), and releases all resources associated to them.
NOTE: This function waits until all threads have finished, so this can take some time!

async.update()

Updates the status of all worker threads, and calls callbacks when needed. This also makes sure threads are cleaned up when they’re done (see Worker management). Only call this in the thread you’ll be doing requests from.

Worker Management

It is recommended you use the “ensure” interface for worker management, because it is easier to work with.
Note that the “ensure” interface supports chaining, that is, any function in the async.ensure table returns that table.

async.ensure.exactly(n)

Make sure there are exactly n workers.

async.ensure.atLeast(n)

Make sure there are at least n workers.

async.ensure.atMost(n)

Make sure there are at most n workers.

workerCount = async.getWorkerCount()

Get the amount of workers currently running.

async.addWorker()

Add a new worker to the thread pool.

async.stopWorkers(amount)

Stop amount workers.

Calling and definition

Before a function can be called asynchronously, it needs to be defined on the worker thread. The way this is done is by calling async.define, specifying a name and a function that will be called on one of the worker threads.

Due to the way lua works, and the restrictions it poses on “disassembling” functions, only functions without upvalues, or with trivial upvalues can be passed. It is, however, undefined what counts as “trivial”. Async uses string.dump under the hood, and the same caveats apply.

Asynchronous functions can be called with any argument that can be sent over LÖVE’s Channels, with the exception of flat tables, and the same limitation applies to return values.

asyncFunc = async.define(name, func)

“Uploads” a function definition to all worker threads, making it available for calling asynchronously. The function returned (asyncFunc) is a shorthand for async.call with the name parameter already supplied.

async.call(callback, name, …)

Queues a call to the function identified by name, with the supplied arguments (restrictions above apply). The callback is called with the return values the next call to async.update after it has completed successfully. See Callbacks for what these callbacks can be.

async.undefine(name)

Remove a function definition from all threads, and prevent it from being sent to new threads. Note that this should only be called when all calls to this functions have finished, if any are pending the definition may be removed before it is started, causing an error.

Callbacks

Callbacks in Async can be one of two things:

  • A function, to be called with the return values on success
  • A table, with a functions named success and error in it. success is called as above, and error is called with the return values of the associated pcall call, without the first, in case of error.