Index · Object → RefCounted → Thread

Thread

A unit of execution in a process.

Class Description

A unit of execution in a process. Can run methods on Objects simultaneously. The use of synchronization via Mutex or Semaphore is advised if working with shared objects.

Warning: To ensure proper cleanup without crashes or deadlocks, when a Thread's reference count reaches zero and it is therefore destroyed, the following conditions must be met:

- It must not have any Mutex objects locked.

- It must not be waiting on any Semaphore objects.

- wait_to_finish() should have been called on it.

Methods

func get_id() -> String

Returns the current Thread's ID, uniquely identifying it among all threads. If the Thread has not started running or if wait_to_finish() has been called, this returns an empty string.

func is_alive() -> bool

Returns true if this Thread is currently running the provided function. This is useful for determining if wait_to_finish() can be called without blocking the calling thread.

To check if a Thread is joinable, use is_started().

func is_main_thread() -> bool

Returns true if the thread this method was called from is the main thread.

Note: This is a static method and isn't associated with a specific Thread object.

func is_started() -> bool

Returns true if this Thread has been started. Once started, this will return true until it is joined using wait_to_finish(). For checking if a Thread is still executing its task, use is_alive().

func set_thread_safety_checks_enabled(enabled: bool) -> void

Sets whether the thread safety checks the engine normally performs in methods of certain classes (e.g., Node) should happen on the current thread.

The default, for every thread, is that they are enabled (as if called with enabled being true).

Those checks are conservative. That means that they will only succeed in considering a call thread-safe (and therefore allow it to happen) if the engine can guarantee such safety.

Because of that, there may be cases where the user may want to disable them (enabled being false) to make certain operations allowed again. By doing so, it becomes the user's responsibility to ensure thread safety (e.g., by using Mutex) for those objects that are otherwise protected by the engine.

Note: This is an advanced usage of the engine. You are advised to use it only if you know what you are doing and there is no safer way.

Note: This is useful for scripts running on either arbitrary Thread objects or tasks submitted to the WorkerThreadPool. It doesn't apply to code running during Node group processing, where the checks will be always performed.

Note: Even in the case of having disabled the checks in a WorkerThreadPool task, there's no need to re-enable them at the end. The engine will do so.

func start(callable: Callable, priority: Thread.Priority = 1) -> Error

Starts a new Thread that calls callable.

If the method takes some arguments, you can pass them using Callable.bind().

The priority of the Thread can be changed by passing a value from the Priority enum.

Returns OK on success, or ERR_CANT_CREATE on failure.

func wait_to_finish() -> Variant

Joins the Thread and waits for it to finish. Returns the output of the Callable passed to start().

Should either be used when you want to retrieve the value returned from the method called by the Thread or before freeing the instance that contains the Thread.

To determine if this can be called without blocking the calling thread, check if is_alive() is false.

Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
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)

Enums & Constants

enum Priority
PRIORITY_LOW = 0

A thread running with lower priority than normally.

PRIORITY_NORMAL = 1

A thread with a standard priority.

PRIORITY_HIGH = 2

A thread running with higher priority than normally.