love-threadpool is an abstraction over LÖVE threads.
It implements a way to distribute and synchronize operations, from the main thread to secondary threads.
In this case, a thread pool is a collection of threads (or workers, a fixed amount) where each of them load the same interface to process operations. This interface can then be used from the main thread synchronously inside a coroutine.
Operations flow: main thread -> split workload -> worker threads -> gather results -> main thread.
Note: Because LÖVE's game loop is not an event loop that can be waken up,
the communication between threads is implemented through a tick method
(polling) and will commonly have a minimum latency dependent of the frame rate;
Work load can be bottlenecked by that latency and CPUs will be underloaded.
Tip: CMT might be of interest in conjunction with this module.
See examples/ (copy the module into the directory).
Install
See src/ and rockspecs/.
API
Note: Coroutine resume errors are propagated using debug.traceback, which
may result in multiple stack tracebacks.
Warning: Thread errors outside interface calls are not propagated by the module; look at love.threaderror for that purpose.
M.new(thread_count, interface_loader, ...)
Create a thread pool.
- thread_count: number of threads in the pool
- interface_loader: Lua function or code, plain or bytecode, which returns a map of functions (called from worker threads)
- ...: interface loader arguments
If the interface has an __exit function, it will be called before the end of
the thread, after the exit of the work loop. It can be used to clean up
interface resources.
threadpool:call(op, callback, ...)
Call an operation on the thread pool interface.
The callback can be a coroutine (will call coroutine.resume with the same
parameters).
- op: key to an operation of the interface
- callback(ok, ...): Called on operation return, common soft error handling interface: returns ok status followed by an error message or the function return values.
- ...: call arguments
threadpool.interface[op](...)
Same as threadpool:call, but synchronously from the current coroutine. Errors
are propagated.
pool.interface.test(42)
threadpool:tick()
Handle the inter-thread communications (result of operations).
threadpool:close()
Close the thread pool (send exit signal and wait/join all threads). Idempotent.
threadpool.tasks
Table/map of id => callback.
Can be used to check if the pool is busy (waiting on tasks to return).