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

Co-authored-by: Thaddeus Crews <[email protected]>

Author: dsnopek

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];
 }
 

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>

core/typedefs.h

@@ -324,6 +324,15 @@ struct BuildIndexSequence<0, Is...> : IndexSequence<Is...> {};
 #define ___gd_is_defined(val) ____gd_is_defined(__GDARG_PLACEHOLDER_##val)
 #define GD_IS_DEFINED(x) ___gd_is_defined(x)
 
+#define GODOT_DEPRECATED_BEGIN                                       \
+	GODOT_CLANG_WARNING_PUSH_AND_IGNORE("-Wdeprecated-declarations") \
+	GODOT_GCC_WARNING_PUSH_AND_IGNORE("-Wdeprecated-declarations")   \
+	GODOT_MSVC_WARNING_PUSH_AND_IGNORE(4996)
+#define GODOT_DEPRECATED_END \
+	GODOT_CLANG_WARNING_POP  \
+	GODOT_GCC_WARNING_POP    \
+	GODOT_MSVC_WARNING_POP
+
 // Whether the default value of a type is just all-0 bytes.
 // This can most commonly be exploited by using memset for these types instead of loop-construct.
 // Trivially constructible types are also zero-constructible.

core/variant/binder_common.h

@@ -36,6 +36,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"

core/variant/method_ptrcall.h

@@ -167,6 +167,27 @@ struct PtrToArg<const T *> {
 	}
 };
 
+// This is for RequiredPtr.
+
+template <class T>
+struct PtrToArg<RequiredPtr<T>> {
+	typedef T *EncodeT;
+
+	_FORCE_INLINE_ static RequiredPtr<T> convert(const void *p_ptr) {
+		if (p_ptr == nullptr) {
+			// Should we show an error?
+			GODOT_DEPRECATED_BEGIN
+			return RequiredPtr<T>::_create_null();
+			GODOT_DEPRECATED_END
+		}
+		return RequiredPtr<T>(*reinterpret_cast<T *const *>(p_ptr));
+	}
+
+	_FORCE_INLINE_ static void encode(const RequiredPtr<T> &p_var, void *p_ptr) {
+		*((T **)p_ptr) = p_var._internal_ptr();
+	}
+};
+
 // This is for ObjectID.
 
 template <>

core/variant/required_ptr.h

@@ -0,0 +1,115 @@
+/**************************************************************************/
+/*  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.                 */
+/**************************************************************************/
+
+#pragma once
+
+#include "core/variant/variant.h"
+
+template <typename T>
+class [[nodiscard]] RequiredPtr {
+	T *_value = nullptr;
+
+	RequiredPtr(std::nullptr_t) {}
+
+public:
+	using element_type = T;
+
+	[[nodiscard, deprecated("Should not be called directly; only used in EXTRACT_REQUIRED_PTR_OR_FAIL* macros.")]]
+	_FORCE_INLINE_ T *_internal_ptr() const { return _value; }
+	[[nodiscard, deprecated("Should not be called directly; only used in EXTRACT_REQUIRED_PTR_OR_FAIL* macros.")]]
+	_FORCE_INLINE_ bool _is_null() const { return _value == nullptr; }
+
+	[[nodiscard, deprecated("Should not be called directly; only used internally.")]]
+	_FORCE_INLINE_ static RequiredPtr<T> _create_null() { return RequiredPtr<T>(nullptr); }
+
+	RequiredPtr() = delete;
+
+	RequiredPtr(const RequiredPtr &p_other) = default;
+	RequiredPtr(RequiredPtr &&p_other) = default;
+	RequiredPtr &operator=(const RequiredPtr &p_other) = default;
+	RequiredPtr &operator=(RequiredPtr &&p_other) = default;
+
+	GODOT_DEPRECATED_BEGIN
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr(const RequiredPtr<T_Other> &p_other) :
+			_value(p_other._internal_ptr()) {}
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr &operator=(const RequiredPtr<T_Other> &p_other) {
+		_value = p_other._internal_ptr();
+		return *this;
+	}
+	GODOT_DEPRECATED_END
+
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr(const T_Other *p_ptr) :
+			_value(const_cast<std::remove_const_t<T_Other> *>(p_ptr)) {}
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr &operator=(const T_Other *p_ptr) {
+		_value = const_cast<std::remove_const_t<T_Other> *>(p_ptr);
+		return *this;
+	}
+
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr(const Ref<T_Other> &p_ref) :
+			_value(p_ref.ptr()) {}
+	template <typename T_Other, std::enable_if_t<std::is_base_of_v<T, T_Other>, int> = 0>
+	_FORCE_INLINE_ RequiredPtr &operator=(const Ref<T_Other> &p_ref) {
+		_value = p_ref.ptr();
+		return *this;
+	}
+
+	_FORCE_INLINE_ RequiredPtr(const Variant &p_variant) :
+			_value(static_cast<T *>(p_variant.get_validated_object())) {}
+	_FORCE_INLINE_ RequiredPtr &operator=(const Variant &p_variant) {
+		_value = static_cast<T *>(p_variant.get_validated_object());
+		return *this;
+	}
+};
+
+#define TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, m_retval, m_msg, m_editor)                                          \
+	GODOT_DEPRECATED_BEGIN                                                                                                     \
+	if (unlikely(m_param._is_null())) {                                                                                        \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Required object \"" _STR(m_param) "\" is null.", m_msg, m_editor); \
+		return m_retval;                                                                                                       \
+	}                                                                                                                          \
+	std::conditional_t<                                                                                                        \
+			std::is_base_of_v<RefCounted, std::decay_t<decltype(m_param)>::element_type>,                                      \
+			Ref<std::decay_t<decltype(m_param)>::element_type>,                                                                \
+			std::decay_t<decltype(m_param)>::element_type *>                                                                   \
+			m_name = m_param._internal_ptr();                                                                                  \
+	GODOT_DEPRECATED_END                                                                                                       \
+	static_assert(true)
+
+#define EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, void(), "", false)
+#define EXTRACT_REQUIRED_PTR_OR_FAIL_MSG(m_name, m_param, m_msg) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, void(), m_msg, false)
+#define EXTRACT_REQUIRED_PTR_OR_FAIL_EDMSG(m_name, m_param, m_msg) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, void(), m_msg, true)
+#define EXTRACT_REQUIRED_PTR_OR_FAIL_V(m_name, m_param, m_retval) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, m_retval, "", false)
+#define EXTRACT_REQUIRED_PTR_OR_FAIL_V_MSG(m_name, m_param, m_retval, m_msg) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, m_retval, m_msg, false)
+#define EXTRACT_REQUIRED_PTR_OR_FAIL_V_EDMSG(m_name, m_param, m_retval, m_msg) TMPL_EXTRACT_REQUIRED_PTR_OR_FAIL(m_name, m_param, m_retval, m_msg, true)

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,
 };
 }
 
@@ -180,6 +181,18 @@ 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()));
+	}
+};
+
 namespace GodotTypeInfo {
 namespace Internal {
 inline String enum_qualified_name_to_class_info_name(const String &p_qualified_name) {

core/variant/variant_internal.h

@@ -1045,6 +1045,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; }

scene/main/node.cpp

@@ -1809,11 +1809,11 @@ 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> &rp_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);
+	EXTRACT_REQUIRED_PTR_OR_FAIL(p_child, rp_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
 #ifdef DEBUG_ENABLED

scene/main/node.h

@@ -490,7 +490,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> &rp_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);