:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/4.0/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/4.0/doc/classes/WorkerThreadPool.xml. .. _class_WorkerThreadPool: WorkerThreadPool ================ **Inherits:** :ref:`Object` A singleton that allocates some :ref:`Thread`\ s on startup, used to offload tasks to these threads. .. rst-class:: classref-introduction-group Description ----------- The **WorkerThreadPool** singleton allocates a set of :ref:`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`\ s. Tasks hold the :ref:`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` 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 _enemies = new List(); // 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(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 Methods ------- .. table:: :widths: auto +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`add_group_task` **(** :ref:`Callable` action, :ref:`int` elements, :ref:`int` tasks_needed=-1, :ref:`bool` high_priority=false, :ref:`String` description="" **)** | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`add_task` **(** :ref:`Callable` action, :ref:`bool` high_priority=false, :ref:`String` description="" **)** | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_group_processed_element_count` **(** :ref:`int` group_id **)** |const| | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_group_task_completed` **(** :ref:`int` group_id **)** |const| | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_task_completed` **(** :ref:`int` task_id **)** |const| | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`wait_for_group_task_completion` **(** :ref:`int` group_id **)** | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`wait_for_task_completion` **(** :ref:`int` task_id **)** | +-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_WorkerThreadPool_method_add_group_task: .. rst-class:: classref-method :ref:`int` **add_group_task** **(** :ref:`Callable` action, :ref:`int` elements, :ref:`int` tasks_needed=-1, :ref:`bool` high_priority=false, :ref:`String` description="" **)** Adds ``action`` as a group task to be executed by the worker threads. The :ref:`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``. 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 ---- .. _class_WorkerThreadPool_method_add_task: .. rst-class:: classref-method :ref:`int` **add_task** **(** :ref:`Callable` action, :ref:`bool` high_priority=false, :ref:`String` description="" **)** 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. Returns a task ID that can be used by other methods. .. rst-class:: classref-item-separator ---- .. _class_WorkerThreadPool_method_get_group_processed_element_count: .. rst-class:: classref-method :ref:`int` **get_group_processed_element_count** **(** :ref:`int` group_id **)** |const| Returns how many times the :ref:`Callable` of the group task with the given ID has already been executed by the worker threads. \ **Note:** If a thread has started executing the :ref:`Callable` but is yet to finish, it won't be counted. .. rst-class:: classref-item-separator ---- .. _class_WorkerThreadPool_method_is_group_task_completed: .. rst-class:: classref-method :ref:`bool` **is_group_task_completed** **(** :ref:`int` group_id **)** |const| Returns ``true`` if the group task with the given ID is completed. .. rst-class:: classref-item-separator ---- .. _class_WorkerThreadPool_method_is_task_completed: .. rst-class:: classref-method :ref:`bool` **is_task_completed** **(** :ref:`int` task_id **)** |const| Returns ``true`` if the task with the given ID is completed. .. rst-class:: classref-item-separator ---- .. _class_WorkerThreadPool_method_wait_for_group_task_completion: .. rst-class:: classref-method void **wait_for_group_task_completion** **(** :ref:`int` group_id **)** Pauses the thread that calls this method until the group task with the given ID is completed. .. rst-class:: classref-item-separator ---- .. _class_WorkerThreadPool_method_wait_for_task_completion: .. rst-class:: classref-method void **wait_for_task_completion** **(** :ref:`int` task_id **)** 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.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`