Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
WorkerThreadPool¶
Inherits: Object
A singleton that allocates some Threads on startup, used to offload tasks to these threads.
Description¶
The WorkerThreadPool singleton allocates a set of Threads (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 Threads.
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:
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.
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.
Tutorials¶
Methods¶
add_group_task ( Callable action, int elements, int tasks_needed=-1, bool high_priority=false, String description="" ) |
|
add_task ( Callable action, bool high_priority=false, String description="" ) |
|
get_group_processed_element_count ( int group_id ) const |
|
is_group_task_completed ( int group_id ) const |
|
is_task_completed ( int task_id ) const |
|
void |
wait_for_group_task_completion ( int group_id ) |