From cd70b804b9a26a1813af836338cf5eb6acce67af Mon Sep 17 00:00:00 2001 From: Joseph Cloutier Date: Wed, 1 Jan 2025 00:54:39 -0500 Subject: [PATCH] Update documentation. --- src/lime/system/ThreadPool.hx | 39 +++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/src/lime/system/ThreadPool.hx b/src/lime/system/ThreadPool.hx index bdc9461632..bae36742d0 100644 --- a/src/lime/system/ThreadPool.hx +++ b/src/lime/system/ThreadPool.hx @@ -70,8 +70,9 @@ 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'll use about half the app's available time every frame. + single-threaded jobs, across all active `ThreadPool`s. For instance, the + default value of 1/2 means `ThreadPool`s will attempt to 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, @@ -107,22 +108,22 @@ class ThreadPool extends WorkOutput public var activeJobs(get, never):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. + The number of background threads in this pool, including both active and + idle threads. Excludes threads that have been instructed to shut down. **/ public var currentThreads(get, never):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. + The number of background threads in this pool that aren't currently + working on anything. **/ public var idleThreads(get, never):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. + The maximum number of background threads this pool can have at once. If + this value decreases, active jobs will still be allowed to finish. **/ public var maxThreads:Int; @@ -194,8 +195,7 @@ class ThreadPool extends WorkOutput @param 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 `run()`. Only applies in - multi-threaded mode. + immediately; only after enough calls to `run()`. @param maxThreads The maximum number of threads that will run at once. @param mode The mode jobs will run in by default. Defaults to `SINGLE_THREADED` in HTML5 for backwards compatibility. @@ -214,8 +214,11 @@ class ThreadPool extends WorkOutput } /** - Cancels all active and queued jobs. In multi-threaded mode, leaves - `minThreads` idle threads running. + Cancels all active and queued jobs. + + Note: It isn't possible to terminate a job from the outside, so canceled + jobs may continue to run for some time. However, any events they send + will be ignored. @param error If not null, this error will be dispatched for each active or queued job. **/ @@ -302,6 +305,10 @@ class ThreadPool extends WorkOutput /** Cancels one active or queued job. Does not dispatch an error event. + + Note: It isn't possible to terminate a job from the outside, so the job + may continue to run for some time. However, any events it sends will be + ignored. @return Whether a job was canceled. **/ public function cancelJob(jobID:Int):Bool @@ -343,13 +350,13 @@ class ThreadPool extends WorkOutput } /** - Runs the given function asynchronously, or queues it for later if all - threads are busy. + Runs the given function asynchronously, or queues it for later if no + more threads are available. @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. + @param state An object to pass to `doWork`. Consider passing a mutable + object so that `doWork` can save its progress. @param mode Which mode to run the job in. If omitted, the pool's default mode will be used. @return The job's unique ID.