mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
212 lines
13 KiB
ReStructuredText
212 lines
13 KiB
ReStructuredText
:github_url: hide
|
|
|
|
.. DO NOT EDIT THIS FILE!!!
|
|
.. Generated automatically from Godot engine sources.
|
|
.. Generator: https://github.com/godotengine/godot/tree/4.2/doc/tools/make_rst.py.
|
|
.. XML source: https://github.com/godotengine/godot/tree/4.2/doc/classes/WorkerThreadPool.xml.
|
|
|
|
.. _class_WorkerThreadPool:
|
|
|
|
WorkerThreadPool
|
|
================
|
|
|
|
**Inherits:** :ref:`Object<class_Object>`
|
|
|
|
A singleton that allocates some :ref:`Thread<class_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<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
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. table::
|
|
:widths: auto
|
|
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`add_group_task<class_WorkerThreadPool_method_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="" **)** |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`add_task<class_WorkerThreadPool_method_add_task>` **(** :ref:`Callable<class_Callable>` action, :ref:`bool<class_bool>` high_priority=false, :ref:`String<class_String>` description="" **)** |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`int<class_int>` | :ref:`get_group_processed_element_count<class_WorkerThreadPool_method_get_group_processed_element_count>` **(** :ref:`int<class_int>` group_id **)** |const| |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_group_task_completed<class_WorkerThreadPool_method_is_group_task_completed>` **(** :ref:`int<class_int>` group_id **)** |const| |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`bool<class_bool>` | :ref:`is_task_completed<class_WorkerThreadPool_method_is_task_completed>` **(** :ref:`int<class_int>` task_id **)** |const| |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| void | :ref:`wait_for_group_task_completion<class_WorkerThreadPool_method_wait_for_group_task_completion>` **(** :ref:`int<class_int>` group_id **)** |
|
|
+---------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
|
| :ref:`Error<enum_@GlobalScope_Error>` | :ref:`wait_for_task_completion<class_WorkerThreadPool_method_wait_for_task_completion>` **(** :ref:`int<class_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<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="" **)**
|
|
|
|
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``.
|
|
|
|
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<class_int>` **add_task** **(** :ref:`Callable<class_Callable>` action, :ref:`bool<class_bool>` high_priority=false, :ref:`String<class_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<class_int>` **get_group_processed_element_count** **(** :ref:`int<class_int>` group_id **)** |const|
|
|
|
|
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.
|
|
|
|
\ **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
|
|
|
|
----
|
|
|
|
.. _class_WorkerThreadPool_method_is_group_task_completed:
|
|
|
|
.. rst-class:: classref-method
|
|
|
|
:ref:`bool<class_bool>` **is_group_task_completed** **(** :ref:`int<class_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<class_bool>` **is_task_completed** **(** :ref:`int<class_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<class_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
|
|
|
|
:ref:`Error<enum_@GlobalScope_Error>` **wait_for_task_completion** **(** :ref:`int<class_int>` task_id **)**
|
|
|
|
Pauses the thread that calls this method until the task with the given ID is completed.
|
|
|
|
Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` if the task could be successfully awaited.
|
|
|
|
Returns :ref:`@GlobalScope.ERR_INVALID_PARAMETER<class_@GlobalScope_constant_ERR_INVALID_PARAMETER>` if a task with the passed ID does not exist (maybe because it was already awaited and disposed of).
|
|
|
|
Returns :ref:`@GlobalScope.ERR_BUSY<class_@GlobalScope_constant_ERR_BUSY>` if the call is made from another running task and, due to task scheduling, the task to await is at a lower level in the call stack and therefore can't progress. This is an advanced situation that should only matter when some tasks depend on others.
|
|
|
|
.. |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.)`
|
|
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
|