Index · Object → WorkerThreadPool

WorkerThreadPool

A singleton that allocates some Threads on startup, used to offload tasks to these threads.

Class 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.

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.

Methods

func add_group_task(action: Callable, elements: int, tasks_needed: int = -1, high_priority: bool = false, description: String = "") -> int

Adds action as a group task to be executed by the worker threads. The 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.

Warning: Every task must be waited for completion using wait_for_task_completion() or wait_for_group_task_completion() at some point so that any allocated resources inside the task can be cleaned up.

func add_task(action: Callable, high_priority: bool = false, description: String = "") -> int

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 wait_for_task_completion() or wait_for_group_task_completion() at some point so that any allocated resources inside the task can be cleaned up.

func get_caller_group_id() -> 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 get_caller_task_id() -> 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 get_group_processed_element_count(group_id: int) -> int

Returns how many times the 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 Callable but is yet to finish, it won't be counted.

func is_group_task_completed(group_id: int) -> bool

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 is_task_completed(task_id: int) -> bool

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 wait_for_group_task_completion(group_id: int) -> void

Pauses the thread that calls this method until the group task with the given ID is completed.

func wait_for_task_completion(task_id: int) -> Error

Pauses the thread that calls this method until the task with the given ID is completed.

Returns OK if the task could be successfully awaited.

Returns ERR_INVALID_PARAMETER if a task with the passed ID does not exist (maybe because it was already awaited and disposed of).

Returns ERR_BUSY 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).

Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)