Node tutorial says freed instance references become null instead of invalid

[wareya]

Your Godot version:

Godot 4

Issue description:

In the Nodes and scene instances tutorial, the following line:

You can alternatively call free() to immediately destroy the node. You should do this with care as any reference to it will instantly become null.

Should say "invalid" instead of "null". Saying that a reference becomes null means that it contains the null value, which is not what happens.

URL to the documentation page:

https://docs.godotengine.org/en/stable/tutorials/scripting/nodes_and_scene_instances.html#creating-nodes

[ratala321]

This is the code to check if an instance is valid after being freed/queue_freed and it does check if reference becomes null.

bool VariantUtilityFunctions::is_instance_valid(const Variant &p_instance) {
	if (p_instance.get_type() != Variant::OBJECT) {
		return false;
	}
	return p_instance.get_validated_object() != nullptr;
}

[AThousandShips]

Indeed, it checks for it, but it doesn't clear it, the method p_instance.get_validated_object() returns nullptr if the instance was freed, but the stored pointer is not null

[ratala321]

I couldn't find the binded c++ method for free(). If it's implementation is similar to queue_free, it's only a matter of time before flush_delete_queue() call memdelete() on the object.

Does anybody knows where to find the c++ code for free() in the Engine? This way, we would be sure.

[AThousandShips]

The pointer isn't cleared, there's no code doing that in the engine, the description in the documentation is wrong

Simply: The free method is called on an instance, and that method can't change the data stored in the Variant that holds the pointer, and the existence of the get_validated_object exists is evidence of this, it checks the pointer against the ObjectID that it also stores and this allows avoiding accessing freed instances

See also:

• Inconsistency in boolean validation of [Freed Object] godot#59816