Attention: Here be dragons
This is the
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
A unit of execution in a process.
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:
get_id ( ) const
is_alive ( ) const
is_started ( ) const
wait_to_finish ( )
Priority PRIORITY_LOW =
A thread running with lower priority than normally.
Priority PRIORITY_NORMAL =
A thread with a standard priority.
Priority PRIORITY_HIGH =
A thread running with higher priority than normally.
String get_id ( ) const
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.
bool is_alive ( ) const
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.
bool is_started ( ) const
void set_thread_safety_checks_enabled ( bool enabled ) static
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
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 (
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.
Starts a new Thread that calls
If the method takes some arguments, you can pass them using Callable.bind.
priority of the Thread can be changed by passing a value from the Priority enum.
Variant wait_to_finish ( )
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