classref: Sync with current master branch (c64afeb)

classes/class_workerthreadpool.rst

@@ -12,9 +12,68 @@ WorkerThreadPool
 
 **Inherits:** :ref:`Object<class_Object>`
 
-.. container:: contribute
+A singleton that allocates some :ref:`Thread<class_Thread>`\ s on startup, used to offload tasks to these threads.
 
-	There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+.. rst-class:: classref-introduction-group
+
+Description
+-----------
+
+The **WorkerThreadPool** singleton allocates a set of :ref:`Thread<class_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 :ref:`Thread<class_Thread>`\ s.
+
+Tasks hold the :ref:`Callable<class_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 :ref:`Callable<class_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:
+
+
+.. tabs::
+
+ .. code-tab:: 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.
+
+ .. code-tab:: 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.
+    }
+
+
+
+The above code relies on the number of elements in the ``enemies`` array remaining constant during the multithreaded part.
+
+\ **Note:** Using this singleton could affect performance negatively if the task being distributed between threads is not computationally expensive.
+
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Using multiple threads <../tutorials/performance/using_multiple_threads>`
+
+- :doc:`Thread-safe APIs <../tutorials/performance/thread_safe_apis>`
 
 .. rst-class:: classref-reftable-group
 
@@ -55,9 +114,11 @@ Method Descriptions
 
 :ref:`int<class_int>` **add_group_task** **(** :ref:`Callable<class_Callable>` action, :ref:`int<class_int>` elements, :ref:`int<class_int>` tasks_needed=-1, :ref:`bool<class_bool>` high_priority=false, :ref:`String<class_String>` description="" **)**
 
-.. container:: contribute
+Adds ``action`` as a group task to be executed by the worker threads. The :ref:`Callable<class_Callable>` will be called a number of times based on ``elements``, with the first thread calling it with the value ``0`` as a parameter, and each consecutive execution incrementing this value by 1 until it reaches ``element - 1``.
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+The number of threads the task is distributed to is defined by ``tasks_needed``, where the default value ``-1`` means it is distributed to all worker threads. ``high_priority`` determines if the task has a high priority or a low priority (default). You can optionally provide a ``description`` to help with debugging.
+
+Returns a group task ID that can be used by other methods.
 
 .. rst-class:: classref-item-separator
 
@@ -69,9 +130,9 @@ Method Descriptions
 
 :ref:`int<class_int>` **add_task** **(** :ref:`Callable<class_Callable>` action, :ref:`bool<class_bool>` high_priority=false, :ref:`String<class_String>` description="" **)**
 
-.. container:: contribute
+Adds ``action`` as a task to be executed by a worker thread. ``high_priority`` determines if the task has a high priority or a low priority (default). You can optionally provide a ``description`` to help with debugging.
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Returns a task ID that can be used by other methods.
 
 .. rst-class:: classref-item-separator
 
@@ -83,9 +144,9 @@ Method Descriptions
 
 :ref:`int<class_int>` **get_group_processed_element_count** **(** :ref:`int<class_int>` group_id **)** |const|
 
-.. container:: contribute
+Returns how many times the :ref:`Callable<class_Callable>` of the group task with the given ID has already been executed by the worker threads.
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+\ **Note:** If a thread has started executing the :ref:`Callable<class_Callable>` but is yet to finish, it won't be counted.
 
 .. rst-class:: classref-item-separator
 
@@ -97,9 +158,7 @@ Method Descriptions
 
 :ref:`bool<class_bool>` **is_group_task_completed** **(** :ref:`int<class_int>` group_id **)** |const|
 
-.. container:: contribute
-
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Returns ``true`` if the group task with the given ID is completed.
 
 .. rst-class:: classref-item-separator
 
@@ -111,9 +170,7 @@ Method Descriptions
 
 :ref:`bool<class_bool>` **is_task_completed** **(** :ref:`int<class_int>` task_id **)** |const|
 
-.. container:: contribute
-
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Returns ``true`` if the task with the given ID is completed.
 
 .. rst-class:: classref-item-separator
 
@@ -125,9 +182,7 @@ Method Descriptions
 
 void **wait_for_group_task_completion** **(** :ref:`int<class_int>` group_id **)**
 
-.. container:: contribute
-
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Pauses the thread that calls this method until the group task with the given ID is completed.
 
 .. rst-class:: classref-item-separator
 
@@ -139,9 +194,7 @@ void **wait_for_group_task_completion** **(** :ref:`int<class_int>` group_id **)
 
 void **wait_for_task_completion** **(** :ref:`int<class_int>` task_id **)**
 
-.. container:: contribute
-
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Pauses the thread that calls this method until the task with the given ID is completed.
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`