From d3a39b560dd92b16b47c979e3aa5f47007c78ab4 Mon Sep 17 00:00:00 2001 From: Joseph Cloutier Date: Thu, 22 Aug 2024 01:44:39 -0400 Subject: [PATCH] One more documentation pass. Hopefully my last before 8.2.0. --- src/lime/system/ThreadPool.hx | 31 ++++++++++++++----------------- src/lime/system/WorkOutput.hx | 16 +++++++--------- 2 files changed, 21 insertions(+), 26 deletions(-) diff --git a/src/lime/system/ThreadPool.hx b/src/lime/system/ThreadPool.hx index 55efff7c79..61d60763cd 100644 --- a/src/lime/system/ThreadPool.hx +++ b/src/lime/system/ThreadPool.hx @@ -78,9 +78,11 @@ class ThreadPool extends WorkOutput /** A rough estimate of how much of the app's time should be spent on single-threaded `ThreadPool`s. For instance, the default value of 1/2 - means they will aim to take up about half the app's available time every - frame. See `workIterations` for instructions to improve the accuracy of - this estimate. + 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. **/ public static var workLoad:Float = 1 / 2; @@ -128,13 +130,6 @@ class ThreadPool extends WorkOutput The maximum number of live threads this pool can have at once. If this value decreases, active jobs will still be allowed to finish. - - You can set this in single-threaded mode, but it's rarely useful. For - instance, suppose you have six jobs, each of which takes about a second. - If you leave `maxThreads` at 1, then one will finish every second for - six seconds. If you set `maxThreads = 6`, then none will finish for five - seconds, and then they'll all finish at once. The total duration is - unchanged, but none of them finish early. **/ public var maxThreads:Int; @@ -142,10 +137,8 @@ class ThreadPool extends WorkOutput __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 add new threads, it'll just - keep existing ones running. - - Has no effect in single-threaded mode. + there's no work to do. Setting this won't immediately spin up new + threads; you must still call `run()` to get them started. **/ public var minThreads:Int; @@ -343,7 +336,13 @@ class ThreadPool extends WorkOutput } /** - Queues a new job, to be run once a thread becomes available. + Runs the given function asynchronously, or queues it for later if all + threads are busy. + @param doWork The function to run. For best results, see the guidelines + in the `ThreadPool` class overview. In brief: `doWork` should be static, + only access its arguments, and return often. + @param state An object to pass to `doWork`, ideally a mutable object so + that `doWork` can save its progress. @return The job's unique ID. **/ public function run(doWork:WorkFunctionWorkOutput->Void> = null, state:State = null):Int @@ -647,8 +646,6 @@ class ThreadPool extends WorkOutput return activeJobs + idleThreads; } - // Note the distinction between `doWork` and `__doWork`: the former is for - // backwards compatibility, while the latter is always used. private function get_doWork():PseudoEvent { return this; diff --git a/src/lime/system/WorkOutput.hx b/src/lime/system/WorkOutput.hx index 48db2a5e2d..c2673703bd 100644 --- a/src/lime/system/WorkOutput.hx +++ b/src/lime/system/WorkOutput.hx @@ -42,8 +42,9 @@ class WorkOutput the current job, including (if applicable) the ongoing call. In single-threaded mode, it only counts the number of calls this frame. - This helps you adjust `doWork`'s length: too few iterations per frame - means `workLoad` may be inaccurate, while too many may add overhead. + The lower the number, the less accurate `ThreadPool.workLoad` becomes, + but the higher the number, the more overhead there is. As a ballpark + estimate, aim for 10-100 iterations. **/ public var workIterations(default, null):Tls = new Tls(); @@ -236,21 +237,18 @@ class WorkOutput /** A function that performs asynchronous work. This can either be work on - another thread ("multi-threaded mode"), or it can represent a virtual - thread ("single-threaded mode"). + another thread ("multi-threaded mode"), or it can represent a green thread + ("single-threaded mode"). In single-threaded mode, the work function shouldn't complete the job all at once, as the main thread would lock up. Instead, it should perform a fraction of the job each time it's called. `ThreadPool` provides the - function with a persistent `State` argument that can track progress. - Alternatively, you may be able to bind your own `State` argument. + function with a persistent `State` argument for tracking progress, which can + be any object of your choice. Caution: if using multi-threaded mode in HTML5, this must be a static function and binding arguments is forbidden. Compile with `-Dlime-warn-portability` to highlight functions that won't work. - - The exact length of `doWork` can vary, but single-threaded mode will run - more smoothly if it's short enough to run several times per frame. **/ #if (lime_threads && html5) typedef WorkFunction = lime._internal.backend.html5.HTML5Thread.WorkFunction;