Add RequiredPtr<T> to mark Object * arguments and return values as required

dsnopek · dsnopek · commit 928b024ca1d7 · 2024-12-11T09:19:56.000-06:00
diff --git a/core/error/error_macros.h b/core/error/error_macros.h
@@ -391,6 +391,84 @@ void _physics_interpolation_warning(const char *p_function, const char *p_file,
 	} else                                                                                                           \
 		((void)0)
 
+// Required pointer error macros.
+
+/**
+ * Try using `ERR_FAIL_REQUIRED_PTR_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures a pointer `m_param` is not null and assigns to a local variable named `m_name`.
+ * If it is null, the current function returns.
+ */
+#define ERR_FAIL_REQUIRED_PTR(m_name, m_param)                                                          \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                  \
+	if (unlikely(m_name == nullptr)) {                                                                  \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \
+		return;                                                                                         \
+	} else                                                                                              \
+		((void)0)
+
+/**
+ * Ensures a pointer `m_param` is not null and assigns to a local variable named `m_name`.
+ * If it is null, prints `m_msg` and the current function returns.
+ */
+#define ERR_FAIL_REQUIRED_PTR_MSG(m_name, m_param, m_msg)                                                       \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                          \
+	if (unlikely(m_name == nullptr) {                                                                         \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", m_msg); \
+		return;                                                                                                \
+	} else                                                                                                     \
+		((void)0)
+
+/**
+ * Same as `ERR_FAIL_REQUIRED_PTR_MSG` but also notifies the editor.
+ */
+#define ERR_FAIL_REQUIRED_PTR_EDMSG(m_name, m_param, m_msg)                                                           \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                                \
+	if (unlikely(m_name == nullptr) {                                                                               \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", m_msg, true); \
+		return;                                                                                                      \
+	} else                                                                                                           \
+		((void)0)
+
+/**
+ * Try using `ERR_FAIL_REQUIRED_PTR_V_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures a pointer `m_param` is not null and assigns a local variable named `m_name`.
+ * If it is null, the current function returns `m_retval`.
+ */
+#define ERR_FAIL_REQUIRED_PTR_V(m_name, m_param, m_retval)                                               \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                   \
+	if (unlikely(m_name == nullptr) {                                                                  \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \
+		return m_retval;                                                                                \
+	} else                                                                                              \
+		((void)0)
+
+/**
+ * Ensures a pointer `m_param` is not null and assigns a local variable named `m_name`.
+ * If it is null, prints `m_msg` and the current function returns `m_retval`.
+ */
+#define ERR_FAIL_REQUIRED_PTR_V_MSG(m_name, m_param, m_retval, m_msg)                                           \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                          \
+	if (unlikely(m_name == nullptr) {                                                                         \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", m_msg); \
+		return m_retval;                                                                                       \
+	} else                                                                                                     \
+		((void)0)
+
+/**
+ * Same as `ERR_FAIL_REQUIRED_PTR_V_MSG` but also notifies the editor.
+ */
+#define ERR_FAIL_REQUIRED_PTR_V_EDMSG(m_name, m_param, m_retval, m_msg)                                              \
+	std::remove_reference_t<decltype(m_param)>::type m_name = m_param._internal_ptr();                               \
+	if (unlikely(m_name == nullptr)) {                                                                               \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", m_msg, true); \
+		return m_retval;                                                                                             \
+	} else                                                                                                           \
+		((void)0)
+
 /**
  * Try using `ERR_FAIL_COND_MSG`.
  * Only use this macro if there is no sensible error message.
diff --git a/core/extension/extension_api_dump.cpp b/core/extension/extension_api_dump.cpp
@@ -88,7 +88,7 @@ static String get_property_info_type_name(const PropertyInfo &p_info) {
 }
 
 static String get_type_meta_name(const GodotTypeInfo::Metadata metadata) {
-	static const char *argmeta[13] = { "none", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float", "double", "char16", "char32" };
+	static const char *argmeta[14] = { "none", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float", "double", "char16", "char32", "required" };
 	return argmeta[metadata];
 }
 
diff --git a/core/object/object.h b/core/object/object.h
@@ -42,6 +42,7 @@
 #include "core/templates/rb_map.h"
 #include "core/templates/safe_refcount.h"
 #include "core/variant/callable_bind.h"
+#include "core/variant/required_ptr.h"
 #include "core/variant/variant.h"
 
 template <typename T>
diff --git a/core/variant/binder_common.h b/core/variant/binder_common.h
@@ -38,6 +38,7 @@
 #include "core/templates/simple_type.h"
 #include "core/typedefs.h"
 #include "core/variant/method_ptrcall.h"
+#include "core/variant/required_ptr.h"
 #include "core/variant/type_info.h"
 #include "core/variant/variant.h"
 #include "core/variant/variant_internal.h"
diff --git a/core/variant/method_ptrcall.h b/core/variant/method_ptrcall.h
@@ -179,6 +179,38 @@ struct PtrToArg<const T *> {
 	}
 };
 
+// This is for RequiredPtr.
+
+template <class T>
+struct PtrToArg<RequiredPtr<T>> {
+	typedef T *EncodeT;
+
+	_FORCE_INLINE_ static T *convert(const void *p_ptr) {
+		if (p_ptr == nullptr) {
+			// Should we show an error?
+			return RequiredPtr<T>(nullptr);
+		}
+		return RequiredPtr<T>(*reinterpret_cast<T *const *>(p_ptr));
+	}
+
+	_FORCE_INLINE_ static void encode(RequiredPtr<T> p_var, void *p_ptr) {
+		*((T **)p_ptr) = p_var._internal_ptr();
+	}
+};
+
+template <class T>
+struct PtrToArg<const RequiredPtr<T> &> {
+	typedef T *EncodeT;
+
+	_FORCE_INLINE_ static RequiredPtr<T> convert(const void *p_ptr) {
+		if (p_ptr == nullptr) {
+			// Should we show an error?
+			return RequiredPtr<T>(nullptr);
+		}
+		return RequiredPtr<T>(*reinterpret_cast<T *const *>(p_ptr));
+	}
+};
+
 // This is for ObjectID.
 
 template <>
diff --git a/core/variant/required_ptr.h b/core/variant/required_ptr.h
@@ -0,0 +1,68 @@
+/**************************************************************************/
+/*  required_ptr.h                                                        */
+/**************************************************************************/
+/*                         This file is part of:                          */
+/*                             GODOT ENGINE                               */
+/*                        https://godotengine.org                         */
+/**************************************************************************/
+/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
+/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
+/*                                                                        */
+/* Permission is hereby granted, free of charge, to any person obtaining  */
+/* a copy of this software and associated documentation files (the        */
+/* "Software"), to deal in the Software without restriction, including    */
+/* without limitation the rights to use, copy, modify, merge, publish,    */
+/* distribute, sublicense, and/or sell copies of the Software, and to     */
+/* permit persons to whom the Software is furnished to do so, subject to  */
+/* the following conditions:                                              */
+/*                                                                        */
+/* The above copyright notice and this permission notice shall be         */
+/* included in all copies or substantial portions of the Software.        */
+/*                                                                        */
+/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
+/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
+/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
+/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
+/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
+/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
+/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
+/**************************************************************************/
+
+#ifndef REQUIRED_PTR_H
+#define REQUIRED_PTR_H
+
+#include "core/os/memory.h"
+
+template <class T>
+class RequiredPtr {
+	T *value = nullptr;
+
+public:
+	typedef T *type;
+
+	_FORCE_INLINE_ RequiredPtr(T *p_value) {
+		value = p_value;
+	}
+
+	_FORCE_INLINE_ RequiredPtr(const RequiredPtr &p_other) {
+		value = p_other.value;
+	}
+
+	_FORCE_INLINE_ RequiredPtr<T> &operator=(const RequiredPtr &p_other) {
+		value = p_other.value;
+	}
+
+	_FORCE_INLINE_ RequiredPtr(const Variant &p_value) :
+			RequiredPtr(dynamic_cast<T *>((Object *)p_value)) {}
+
+	//
+	// DO NOT CALL THIS DIRECTLY!
+	//
+	// You should use the ERR_FAIL_REQUIRED_PTR*() macros to get the pointer value.
+	//
+	_FORCE_INLINE_ T *_internal_ptr() const {
+		return value;
+	}
+};
+
+#endif // REQUIRED_PTR_H
diff --git a/core/variant/type_info.h b/core/variant/type_info.h
@@ -50,6 +50,7 @@ enum Metadata {
 	METADATA_REAL_IS_DOUBLE,
 	METADATA_INT_IS_CHAR16,
 	METADATA_INT_IS_CHAR32,
+	METADATA_OBJECT_IS_REQUIRED,
 };
 }
 
@@ -210,6 +211,27 @@ struct GetTypeInfo<T *, std::enable_if_t<std::is_base_of_v<Object, T>>> {
 	}
 };
 
+template <class T>
+class RequiredPtr;
+
+template <typename T>
+struct GetTypeInfo<RequiredPtr<T>, std::enable_if_t<std::is_base_of_v<Object, T>>> {
+	static const Variant::Type VARIANT_TYPE = Variant::OBJECT;
+	static const GodotTypeInfo::Metadata METADATA = GodotTypeInfo::METADATA_OBJECT_IS_REQUIRED;
+	static inline PropertyInfo get_class_info() {
+		return PropertyInfo(StringName(T::get_class_static()));
+	}
+};
+
+template <typename T>
+struct GetTypeInfo<const RequiredPtr<T> &, std::enable_if_t<std::is_base_of_v<Object, T>>> {
+	static const Variant::Type VARIANT_TYPE = Variant::OBJECT;
+	static const GodotTypeInfo::Metadata METADATA = GodotTypeInfo::METADATA_OBJECT_IS_REQUIRED;
+	static inline PropertyInfo get_class_info() {
+		return PropertyInfo(StringName(T::get_class_static()));
+	}
+};
+
 namespace godot {
 namespace details {
 inline String enum_qualified_name_to_class_info_name(const String &p_qualified_name) {
diff --git a/core/variant/variant_internal.h b/core/variant/variant_internal.h
@@ -1093,6 +1093,18 @@ struct VariantInternalAccessor<Object *> {
 	static _FORCE_INLINE_ void set(Variant *v, const Object *p_value) { VariantInternal::object_assign(v, p_value); }
 };
 
+template <class T>
+struct VariantInternalAccessor<RequiredPtr<T>> {
+	static _FORCE_INLINE_ RequiredPtr<T> get(const Variant *v) { return RequiredPtr<T>(Object::cast_to<T>(const_cast<Object *>(*VariantInternal::get_object(v)))); }
+	static _FORCE_INLINE_ void set(Variant *v, const RequiredPtr<T> &p_value) { VariantInternal::object_assign(v, p_value.ptr()); }
+};
+
+template <class T>
+struct VariantInternalAccessor<const RequiredPtr<T> &> {
+	static _FORCE_INLINE_ RequiredPtr<T> get(const Variant *v) { return RequiredPtr<T>(Object::cast_to<T>(*VariantInternal::get_object(v))); }
+	static _FORCE_INLINE_ void set(Variant *v, const RequiredPtr<T> &p_value) { VariantInternal::object_assign(v, p_value.ptr()); }
+};
+
 template <>
 struct VariantInternalAccessor<Variant> {
 	static _FORCE_INLINE_ Variant &get(Variant *v) { return *v; }
diff --git a/scene/main/node.cpp b/scene/main/node.cpp
@@ -1642,28 +1642,28 @@ void Node::_add_child_nocheck(Node *p_child, const StringName &p_name, InternalM
 	emit_signal(SNAME("child_order_changed"));
 }
 
-void Node::add_child(Node *p_child, bool p_force_readable_name, InternalMode p_internal) {
+void Node::add_child(const RequiredPtr<Node> &p_child, bool p_force_readable_name, InternalMode p_internal) {
 	ERR_FAIL_COND_MSG(data.inside_tree && !Thread::is_main_thread(), "Adding children to a node inside the SceneTree is only allowed from the main thread. Use call_deferred(\"add_child\",node).");
 
 	ERR_THREAD_GUARD
-	ERR_FAIL_NULL(p_child);
-	ERR_FAIL_COND_MSG(p_child == this, vformat("Can't add child '%s' to itself.", p_child->get_name())); // adding to itself!
-	ERR_FAIL_COND_MSG(p_child->data.parent, vformat("Can't add child '%s' to '%s', already has a parent '%s'.", p_child->get_name(), get_name(), p_child->data.parent->get_name())); //Fail if node has a parent
+	ERR_FAIL_REQUIRED_PTR(child, p_child);
+	ERR_FAIL_COND_MSG(child == this, vformat("Can't add child '%s' to itself.", child->get_name())); // adding to itself!
+	ERR_FAIL_COND_MSG(child->data.parent, vformat("Can't add child '%s' to '%s', already has a parent '%s'.", child->get_name(), get_name(), child->data.parent->get_name())); //Fail if node has a parent
 #ifdef DEBUG_ENABLED
-	ERR_FAIL_COND_MSG(p_child->is_ancestor_of(this), vformat("Can't add child '%s' to '%s' as it would result in a cyclic dependency since '%s' is already a parent of '%s'.", p_child->get_name(), get_name(), p_child->get_name(), get_name()));
+	ERR_FAIL_COND_MSG(child->is_ancestor_of(this), vformat("Can't add child '%s' to '%s' as it would result in a cyclic dependency since '%s' is already a parent of '%s'.", child->get_name(), get_name(), child->get_name(), get_name()));
 #endif
 	ERR_FAIL_COND_MSG(data.blocked > 0, "Parent node is busy setting up children, `add_child()` failed. Consider using `add_child.call_deferred(child)` instead.");
 
-	_validate_child_name(p_child, p_force_readable_name);
+	_validate_child_name(child, p_force_readable_name);
 
 #ifdef DEBUG_ENABLED
-	if (p_child->data.owner && !p_child->data.owner->is_ancestor_of(p_child)) {
-		// Owner of p_child should be ancestor of p_child.
-		WARN_PRINT(vformat("Adding '%s' as child to '%s' will make owner '%s' inconsistent. Consider unsetting the owner beforehand.", p_child->get_name(), get_name(), p_child->data.owner->get_name()));
+	if (child->data.owner && !child->data.owner->is_ancestor_of(child)) {
+		// Owner of child should be ancestor of child.
+		WARN_PRINT(vformat("Adding '%s' as child to '%s' will make owner '%s' inconsistent. Consider unsetting the owner beforehand.", child->get_name(), get_name(), child->data.owner->get_name()));
 	}
 #endif // DEBUG_ENABLED
 
-	_add_child_nocheck(p_child, p_child->data.name, p_internal);
+	_add_child_nocheck(child, child->data.name, p_internal);
 }
 
 void Node::add_sibling(Node *p_sibling, bool p_force_readable_name) {
diff --git a/scene/main/node.h b/scene/main/node.h
@@ -452,7 +452,7 @@ class Node : public Object {
 
 	InternalMode get_internal_mode() const;
 
-	void add_child(Node *p_child, bool p_force_readable_name = false, InternalMode p_internal = INTERNAL_MODE_DISABLED);
+	void add_child(const RequiredPtr<Node> &p_child, bool p_force_readable_name = false, InternalMode p_internal = INTERNAL_MODE_DISABLED);
 	void add_sibling(Node *p_sibling, bool p_force_readable_name = false);
 	void remove_child(Node *p_child);
 

Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,7 @@ static String get_property_info_type_name(const PropertyInfo &p_info) {`
`88`	`88`	`}`
`89`	`89`
`90`	`90`	`static String get_type_meta_name(const GodotTypeInfo::Metadata metadata) {`
`91`		`- static const char *argmeta[13] = { "none", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float", "double", "char16", "char32" };`
	`91`	`+ static const char *argmeta[14] = { "none", "int8", "int16", "int32", "int64", "uint8", "uint16", "uint32", "uint64", "float", "double", "char16", "char32", "required" };`
`92`	`92`	`return argmeta[metadata];`
`93`	`93`	`}`
`94`	`94`