Browse Source

Add an `OS.crash()` method for testing system crash handler

This makes it possible to test the system's crash handler without
having to modify engine code or exploit an engine bug.
Hugo Locurcio 3 years ago
parent
commit
5761b90f3c
3 changed files with 14 additions and 1 deletions
  1. 5 0
      core/core_bind.cpp
  2. 1 0
      core/core_bind.h
  3. 8 1
      doc/classes/OS.xml

+ 5 - 0
core/core_bind.cpp

@@ -207,6 +207,10 @@ void OS::alert(const String &p_alert, const String &p_title) {
 	::OS::get_singleton()->alert(p_alert, p_title);
 }
 
+void OS::crash(const String &p_message) {
+	CRASH_NOW_MSG(p_message);
+}
+
 String OS::get_executable_path() const {
 	return ::OS::get_singleton()->get_executable_path();
 }
@@ -542,6 +546,7 @@ void OS::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("close_midi_inputs"), &OS::close_midi_inputs);
 
 	ClassDB::bind_method(D_METHOD("alert", "text", "title"), &OS::alert, DEFVAL("Alert!"));
+	ClassDB::bind_method(D_METHOD("crash", "message"), &OS::crash);
 
 	ClassDB::bind_method(D_METHOD("set_low_processor_usage_mode", "enable"), &OS::set_low_processor_usage_mode);
 	ClassDB::bind_method(D_METHOD("is_in_low_processor_usage_mode"), &OS::is_in_low_processor_usage_mode);

+ 1 - 0
core/core_bind.h

@@ -161,6 +161,7 @@ public:
 	int get_low_processor_usage_mode_sleep_usec() const;
 
 	void alert(const String &p_alert, const String &p_title = "ALERT!");
+	void crash(const String &p_message);
 
 	String get_executable_path() const;
 	int execute(const String &p_path, const Vector<String> &p_arguments, Array r_output = Array(), bool p_read_stderr = false);

+ 8 - 1
doc/classes/OS.xml

@@ -31,6 +31,13 @@
 				[b]Note:[/b] This method is implemented on Linux, macOS and Windows.
 			</description>
 		</method>
+		<method name="crash">
+			<return type="void" />
+			<argument index="0" name="message" type="String" />
+			<description>
+				Crashes the engine (or the editor if called within a [code]@tool[/code] script). This should [i]only[/i] be used for testing the system's crash handler, not for any other purpose. For general error reporting, use (in order of preference) [method @GDScript.assert], [method @GlobalScope.push_error] or [method alert]. See also [method kill].
+			</description>
+		</method>
 		<method name="create_instance">
 			<return type="int" />
 			<argument index="0" name="arguments" type="PackedStringArray" />
@@ -374,7 +381,7 @@
 			<return type="int" enum="Error" />
 			<argument index="0" name="pid" type="int" />
 			<description>
-				Kill (terminate) the process identified by the given process ID ([code]pid[/code]), e.g. the one returned by [method execute] in non-blocking mode.
+				Kill (terminate) the process identified by the given process ID ([code]pid[/code]), e.g. the one returned by [method execute] in non-blocking mode. See also [method crash].
 				[b]Note:[/b] This method can also be used to kill processes that were not spawned by the game.
 				[b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows.
 			</description>