A thread pool executes one or more functions asynchronously.
In multi-threaded mode, jobs run on background threads. In HTML5, this means using web workers, which impose additional restrictions (see below). In single-threaded mode, jobs run between frames on the main thread. To avoid blocking, these jobs should only do a small amount of work at a time.
In multi-threaded mode, the pool spins up new threads as jobs arrive (up to
maxThreads). If too many jobs arrive at once, it places them in a queue to
run when threads open up. If you run jobs frequently but not constantly, you
can also set minThreads to keep a certain number of threads alive,
avoiding the overhead of repeatedly spinning them up.
Sample usage:
var threadPool:ThreadPool = new ThreadPool();
threadPool.onComplete.add(onFileProcessed);
threadPool.maxThreads = 3;
for(url in urls)
{
threadPool.run(processFile, url);
}
Guidelines to make your code work on all targets and configurations:
- For thread safety and web worker compatibility, your work function should
only return data through the
WorkOutputobject it receives. - For web worker compatibility, you should only send data to your work
function via the
Stateobject. But since this can be any object, you can put an arbitrary amount of data there. - For web worker compatibility, your work function must be static, and you
can't
bind()any extra arguments. - For single-threaded performance, your function should only do a small
amount of work at a time. Store progress in the
Stateobject so you can pick up where you left off. You don't have to worry about timing: just aim to take a small fraction of the frame's time, andThreadPoolwill keep running the function until enough time passes.
Static variables
staticworkLoad:Float = 1 / 2
A rough estimate of how much of the app's time should be spent on
single-threaded ThreadPools. For instance, the default value of 1/2
means they'll use about half the app's available time every frame.
The accuracy of this estimate depends on how often your work functions
return. If you find that a ThreadPool is taking longer than scheduled,
try making the work function return more often.
Static methods
staticinlineisMainThread():Bool
Returns whether the caller called this function from the main thread.
Constructor
new(minThreads:Int = 0, maxThreads:Int = 1, ?mode:ThreadMode)
Call this only from the main thread.
Parameters:
minThreads | The number of threads that will be kept alive at all
times, even if there's no work to do. The threads won't spin up
immediately; only after enough calls to |
|---|---|
maxThreads | The maximum number of threads that will run at once. |
mode | Defaults to |
Variables
read onlycurrentThreads:Int
The number of live threads in this pool, including both active and idle threads. Does not count threads that have been instructed to shut down.
In single-threaded mode, this will equal activeJobs.
read onlyidleThreads:Int
The number of live threads in this pool that aren't currently working on anything. In single-threaded mode, this will always be 0.
maxThreads:Int
Set this only from the main thread.
The maximum number of live threads this pool can have at once. If this value decreases, active jobs will still be allowed to finish.
minThreads:Int
Set this only from the main thread.
The number of threads that will be kept alive at all times, even if
there's no work to do. Setting this won't immediately spin up new
threads; you must still call run() to get them started.
read onlyonComplete:_Event_Dynamic_Void<Dynamic ‑> Void> = new Event<Dynamic>()
Dispatched on the main thread when doWork calls sendComplete().
Dispatched at most once per job.
read onlyonError:_Event_Dynamic_Void<Dynamic ‑> Void> = new Event<Dynamic>()
Dispatched on the main thread when doWork calls sendError().
Dispatched at most once per job.
read onlyonProgress:_Event_Dynamic_Void<Dynamic ‑> Void> = new Event<Dynamic>()
Dispatched on the main thread when doWork calls sendProgress(). May
be dispatched any number of times per job.
read onlyonRun:_Event_lime_system_State_Void<State ‑> Void> = new Event<State>()
Dispatched on the main thread when a new job begins. Dispatched exactly once per job.
workPriority:Float = 1
(Single-threaded mode only.) How important this pool's jobs are relative to other single-threaded pools.
For instance, if all pools use the default priority of 1, they will all run for an approximately equal amount of time each frame. If one has a value of 2, it will run approximately twice as long as the others.
Methods
cancel(?error:Dynamic):Void
Cancels all active and queued jobs. In multi-threaded mode, leaves
minThreads idle threads running.
Parameters:
error | If not null, this error will be dispatched for each active or queued job. |
|---|
cancelJob(jobID:Int):Bool
Cancels one active or queued job. Does not dispatch an error event.
Returns:
Whether a job was canceled.
run(?doWork:WorkFunction<(State, WorkOutput) ‑> Void>, ?state:Null<State>):Int
Runs the given function asynchronously, or queues it for later if all threads are busy.
Parameters:
doWork | The function to run. For best results, see the guidelines
in the |
|---|---|
state | An object to pass to |
Returns:
The job's unique ID.