From bd257092daedde5d35a8dd5c1436eb4b01d25dde Mon Sep 17 00:00:00 2001 From: VolTer Date: Fri, 28 Apr 2023 05:23:59 +0200 Subject: [PATCH] Add WorkerThreadPool documentation --- doc/classes/WorkerThreadPool.xml | 51 ++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/doc/classes/WorkerThreadPool.xml b/doc/classes/WorkerThreadPool.xml index e323cdcb616..ace5f95506e 100644 --- a/doc/classes/WorkerThreadPool.xml +++ b/doc/classes/WorkerThreadPool.xml @@ -1,10 +1,50 @@ + A singleton that allocates some [Thread]s on startup, used to offload tasks to these threads. + The [WorkerThreadPool] singleton allocates a set of [Thread]s (called worker threads) on project startup and provides methods for offloading tasks to them. This can be used for simple multithreading without having to create [Thread]s. + Tasks hold the [Callable] to be run by the threads. [WorkerThreadPool] can be used to create regular tasks, which will be taken by one worker thread, or group tasks, which can be distributed between multiple worker threads. Group tasks execute the [Callable] multiple times, which makes them useful for iterating over a lot of elements, such as the enemies in an arena. + Here's a sample on how to offload an expensive function to worker threads: + [codeblocks] + [gdscript] + var enemies = [] # An array to be filled with enemies. + + func process_enemy_ai(enemy_index): + var processed_enemy = enemies[enemy_index] + # Expensive logic... + + func _process(delta): + var task_id = WorkerThreadPool.add_group_task(process_enemy_ai, enemies.size()) + # Other code... + WorkerThreadPool.wait_for_group_task_completion(task_id) + # Other code that depends on the enemy AI already being processed. + [/gdscript] + [csharp] + private List<Node> _enemies = new List<Node>(); // A list to be filled with enemies. + + private void ProcessEnemyAI(int enemyIndex) + { + Node processedEnemy = _enemies[enemyIndex]; + // Expensive logic here. + } + + public override void _Process(double delta) + { + long taskId = WorkerThreadPool.AddGroupTask(Callable.From<int>(ProcessEnemyAI), _enemies.Count); + // Other code... + WorkerThreadPool.WaitForGroupTaskCompletion(taskId); + // Other code that depends on the enemy AI already being processed. + } + [/csharp] + [/codeblocks] + The above code relies on the number of elements in the [code]enemies[/code] array remaining constant during the multithreaded part. + [b]Note:[/b] Using this singleton could affect performance negatively if the task being distributed between threads is not computationally expensive. + $DOCS_URL/tutorials/performance/using_multiple_threads.html + $DOCS_URL/tutorials/performance/thread_safe_apis.html @@ -15,6 +55,9 @@ + Adds [param action] as a group task to be executed by the worker threads. The [Callable] will be called a number of times based on [param elements], with the first thread calling it with the value [code]0[/code] as a parameter, and each consecutive execution incrementing this value by 1 until it reaches [code]element - 1[/code]. + The number of threads the task is distributed to is defined by [param tasks_needed], where the default value [code]-1[/code] means it is distributed to all worker threads. [param high_priority] determines if the task has a high priority or a low priority (default). You can optionally provide a [param description] to help with debugging. + Returns a group task ID that can be used by other methods. @@ -23,36 +66,44 @@ + Adds [param action] as a task to be executed by a worker thread. [param high_priority] determines if the task has a high priority or a low priority (default). You can optionally provide a [param description] to help with debugging. + Returns a task ID that can be used by other methods. + Returns how many times the [Callable] of the group task with the given ID has already been executed by the worker threads. + [b]Note:[/b] If a thread has started executing the [Callable] but is yet to finish, it won't be counted. + Returns [code]true[/code] if the group task with the given ID is completed. + Returns [code]true[/code] if the task with the given ID is completed. + Pauses the thread that calls this method until the group task with the given ID is completed. + Pauses the thread that calls this method until the task with the given ID is completed.