module Lapis::Docs::E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::C_BOEHM_GC_VS_REFCOUNTING

Overview

Boehm GC vs Godot Reference Counting

In-depth architectural comparison between Crystal's Boehm-Demers-Weiser Garbage Collector and Godot's native reference-counting system (RefCounted, Resource).

Executive Summary & Key Topics

Topic Method / Anchor Description
The Two Memory Models .topic_00_memory_paradigms Crystal heap objects vs Godot native reference-counted instances.
RefCounted & Resource Lifecycle Rules .topic_01_refcounted_rules Never call manual .destroy on RefCounted or Resource instances.

Related Guides & Source References

Defined in:

libgodot/docs/e_memory_safety_and_engine_internals/c_boehm_gc_vs_refcounting.cr

Class Method Summary

Class Method Detail

def self.topic_00_memory_paradigms : Nil #

The Two Memory Models: Crystal heap objects vs Godot native reference-counted instances.

Key Topics & Information

  • Crystal Objects: Managed by Boehm GC (GC.collect)
  • Godot Nodes: Managed by SceneTree ownership (queue_free)
  • Godot Resources: Managed by atomic reference counters (reference/unreference)

def self.topic_01_refcounted_rules : Nil #

RefCounted & Resource Lifecycle Rules: Never call manual .destroy on RefCounted or Resource instances.

Rule 1: Never Call .destroy on RefCounted Resources

RefCounted and Resource instances (e.g. Texture2D, Shader, AudioStream) are freed automatically when their reference count drops to 0. Calling manual .destroy destroys native C++ state prematurely, crashing Godot when the counter decrements.

Rule 2: Standalone Nodes Must Be Explicitly Freed

Nodes created via Godot.create(Godot::Node2D) that are never added to the scene tree via add_child are not owned by Godot. To prevent C++ memory leaks, you must explicitly call node.destroy when done with them.