Documentation
¶
Overview ¶
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 func 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 func 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:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/WorkerThreadPool"
)
var enemies []Node.Instance
func process_enemy_ai(enemy_index int) {
var processed_enemy = enemies[enemy_index]
// Expensive logic...
_ = processed_enemy
}
func process() {
var task_id = WorkerThreadPool.AddGroupTask(process_enemy_ai, len(enemies), false, "")
// Other code...
WorkerThreadPool.WaitForGroupTaskCompletion(task_id)
// 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.
Index ¶
- func AddGroupTask(action func(int), elements int, high_priority bool, description string) int
- func AddGroupTaskOptions(action func(int), elements int, tasks_needed int, high_priority bool, ...) int
- func AddTask(action func(int), high_priority bool, description string) int
- func Advanced() class
- func GetCallerGroupId() int
- func GetCallerTaskId() int
- func GetGroupProcessedElementCount(group_id int) int
- func IsGroupTaskCompleted(group_id int) bool
- func IsTaskCompleted(task_id int) bool
- func WaitForGroupTaskCompletion(group_id int)
- func WaitForTaskCompletion(task_id int) error
- type Extension
- type ID
- type Instance
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddGroupTask ¶
Adds 'action' as a group task to be executed by the worker threads. The func 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.
Warning: Every task must be waited for completion using WaitForTaskCompletion or WaitForGroupTaskCompletion at some point so that any allocated resources inside the task can be cleaned up.
func AddGroupTaskOptions ¶
func AddGroupTaskOptions(action func(int), elements int, tasks_needed int, high_priority bool, description string) int
Adds 'action' as a group task to be executed by the worker threads. The func 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.
Warning: Every task must be waited for completion using WaitForTaskCompletion or WaitForGroupTaskCompletion at some point so that any allocated resources inside the task can be cleaned up.
func AddTask ¶
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.
Warning: Every task must be waited for completion using WaitForTaskCompletion or WaitForGroupTaskCompletion at some point so that any allocated resources inside the task can be cleaned up.
func Advanced ¶
func Advanced() class
Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.
func GetCallerGroupId ¶
func GetCallerGroupId() int
Returns the task group ID of the current thread calling this method, or -1 if invalid or the current thread is not part of a task group.
func GetCallerTaskId ¶
func GetCallerTaskId() int
Returns the task ID of the current thread calling this method, or -1 if the task is a group task, invalid or the current thread is not part of the thread pool (e.g. the main thread).
Can be used by a task to get its own task ID, or to determine whether the current code is running inside the worker thread pool.
Note: Group tasks have their own IDs, so this method will return -1 for group tasks.
func GetGroupProcessedElementCount ¶
Returns how many times the func of the group task with the given ID has already been executed by the worker threads.
Note: If a thread has started executing the func but is yet to finish, it won't be counted.
func IsGroupTaskCompleted ¶
Returns true if the group task with the given ID is completed.
Note: You should only call this method between adding the group task and awaiting its completion.
func IsTaskCompleted ¶
Returns true if the task with the given ID is completed.
Note: You should only call this method between adding the task and awaiting its completion.
func WaitForGroupTaskCompletion ¶
func WaitForGroupTaskCompletion(group_id int)
Pauses the thread that calls this method until the group task with the given ID is completed.
func WaitForTaskCompletion ¶
Pauses the thread that calls this method until the task with the given ID is completed.
Returns [@Globalscope.Ok] if the task could be successfully awaited.
Returns [@Globalscope.ErrInvalidParameter] if a task with the passed ID does not exist (maybe because it was already awaited and disposed of).
Returns [@Globalscope.ErrBusy] if the call is made from another running task and, due to task scheduling, there's potential for deadlocking (e.g., the task to await may be 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 (in the current implementation, the tricky case is a task trying to wait on an older one).
Types ¶
type Extension ¶
Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension
type ID ¶
ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.
type Instance ¶
type Instance [1]gdclass.WorkerThreadPool
Instance of the class with convieniently typed arguments and results.
Source Files