Merge pull request #78000 from RandomShaper/let_users_mess_up

Let user scripts disable thread safety checks

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/classes/Thread.xml b/doc/classes/Thread.xml
index 9ba37a035e..b212391d2a 100644
--- a/doc/classes/Thread.xml
+++ b/doc/classes/Thread.xml
@@ -37,6 +37,19 @@
 				Returns [code]true[/code] if this [Thread] has been started. Once started, this will return [code]true[/code] until it is joined using [method wait_to_finish]. For checking if a [Thread] is still executing its task, use [method is_alive].
 			</description>
 		</method>
+		<method name="set_thread_safety_checks_enabled" qualifiers="static">
+			<return type="void" />
+			<param index="0" name="enabled" type="bool" />
+			<description>
+				Sets whether the thread safety checks the engine normally performs in methods of certain classes (e.g., [Node]) should happen [b]on the current thread[/b].
+				The default, for every thread, is that they are enabled (as if called with [param enabled] being [code]true[/code]).
+				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 ([param enabled] being [code]false[/code]) 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.
+				[b]Note:[/b] 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.
+				[b]Note:[/b] 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.
+				[b]Note:[/b] 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.
+			</description>
+		</method>
 		<method name="start">
 			<return type="int" enum="Error" />
 			<param index="0" name="callable" type="Callable" />