From 9b7c7914bf6339f315358b6feeaf9b757045fc62 Mon Sep 17 00:00:00 2001 From: Joseph Cloutier Date: Sat, 17 Aug 2024 23:42:23 -0400 Subject: [PATCH] Update `ThreadPool` documentation. --- src/lime/system/ThreadPool.hx | 41 ++++++++++++++++++++++++++--------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/src/lime/system/ThreadPool.hx b/src/lime/system/ThreadPool.hx index 1f1ef98da..4eb9c3c7e 100644 --- a/src/lime/system/ThreadPool.hx +++ b/src/lime/system/ThreadPool.hx @@ -15,12 +15,18 @@ import lime._internal.backend.html5.HTML5Thread as Thread; #end /** - A simple and thread-safe way to run a one or more asynchronous jobs. It - manages a queue of jobs, starting new ones once the old ones are done. + A thread pool executes one or more functions asynchronously. - It can also keep a certain number of threads (configurable via `minThreads`) - running in the background even when no jobs are available. This avoids the - not-insignificant overhead of stopping and restarting threads. + 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: @@ -33,11 +39,26 @@ import lime._internal.backend.html5.HTML5Thread as Thread; threadPool.run(processFile, url); } - For thread safety, the worker function should only give output through the - `WorkOutput` object it receives. Calling `output.sendComplete()` will - trigger an `onComplete` event on the main thread. - - @see `lime.system.WorkOutput.WorkFunction` for important information about `doWork`. + If upgrading from `BackgroundWorker`, you can use `ThreadPool` as a drop-in + replacement. It will then display some deprecation warnings indicating which + steps to take next. + + --- + + 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 `WorkOutput` object it receives. + - For web worker compatibility, you should only send data to your work + function via the `State` object. 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 `State` object 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, and `ThreadPool` will keep + running the function until enough time passes. **/ #if !lime_debug @:fileXml('tags="haxe,release"')