Make #[cfg] model for safeguards easier to understand

Use simple #[cfg]s: `safeguards_strict` + `safeguards_balanced`.
This implies "at least this safety level". No more indirect
`*_at_least = "string"` conditions and extra negation.

Author: Bromeon

godot-bindings/src/lib.rs

@@ -269,8 +269,13 @@ pub fn since_api(major_minor: &str) -> bool {
 }
 
 pub fn emit_safeguard_levels() {
-    let safeguard_modes = ["disengaged", "balanced", "strict"];
+    // Determine safeguard level:
+    // - Disengaged (0): no runtime checks, maximum performance
+    // - Balanced (1): essential safety checks, good balance (default for release)
+    // - Strict (2): all checks including expensive ones (default for debug)
     let mut safeguards_level = if cfg!(debug_assertions) { 2 } else { 1 };
+
+    // Features can override the default level
     #[cfg(debug_assertions)]
     if cfg!(feature = "safeguards-dev-balanced") {
         safeguards_level = 1;
@@ -280,10 +285,15 @@ pub fn emit_safeguard_levels() {
         safeguards_level = 0;
     }
 
-    for mode in safeguard_modes.iter() {
-        println!(r#"cargo:rustc-check-cfg=cfg(safeguards_at_least, values("{mode}"))"#);
+    // Emit cfg checks for rustc
+    println!(r#"cargo:rustc-check-cfg=cfg(safeguards_balanced)"#);
+    println!(r#"cargo:rustc-check-cfg=cfg(safeguards_strict)"#);
+
+    // Emit cfgs cumulatively: strict builds get both balanced and strict
+    if safeguards_level >= 1 {
+        println!(r#"cargo:rustc-cfg=safeguards_balanced"#);
     }
-    for mode in safeguard_modes.iter().take(safeguards_level + 1) {
-        println!(r#"cargo:rustc-cfg=safeguards_at_least="{mode}""#);
+    if safeguards_level >= 2 {
+        println!(r#"cargo:rustc-cfg=safeguards_strict"#);
     }
 }

godot-codegen/src/generator/classes.rs

@@ -195,7 +195,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         fn __checked_id(&self) -> Option<crate::obj::InstanceId> {
             // SAFETY: only Option due to layout-compatibility with RawGd<T>; it is always Some because stored in Gd<T> which is non-null.
             let rtti = unsafe { self.rtti.as_ref().unwrap_unchecked() };
-            #[cfg(safeguards_at_least = "strict")]
+            #[cfg(safeguards_strict)]
             rtti.check_type::<Self>();
             Some(rtti.instance_id())
         }

godot-codegen/src/generator/native_structures.rs

@@ -219,7 +219,7 @@ fn make_native_structure_field_and_accessor(
 
                 let obj = #snake_field_name.upcast();
 
-                #[cfg(safeguards_at_least = "balanced")]
+                #[cfg(safeguards_balanced)]
                 assert!(obj.is_instance_valid(), "provided node is dead");
 
                 let id = obj.instance_id().to_u64();

godot-core/src/builtin/collections/array.rs

@@ -968,7 +968,7 @@ impl<T: ArrayElement> Array<T> {
     }
 
     /// Validates that all elements in this array can be converted to integers of type `T`.
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     pub(crate) fn debug_validate_int_elements(&self) -> Result<(), ConvertError> {
         // SAFETY: every element is internally represented as Variant.
         let canonical_array = unsafe { self.assume_type_ref::<Variant>() };
@@ -990,7 +990,7 @@ impl<T: ArrayElement> Array<T> {
     }
 
     // No-op in Release. Avoids O(n) conversion checks, but still panics on access.
-    #[cfg(not(safeguards_at_least = "strict"))]
+    #[cfg(not(safeguards_strict))]
     pub(crate) fn debug_validate_int_elements(&self) -> Result<(), ConvertError> {
         Ok(())
     }
@@ -1233,7 +1233,7 @@ impl<T: ArrayElement> Clone for Array<T> {
         let copy = unsafe { self.clone_unchecked() };
 
         // Double-check copy's runtime type in Debug mode.
-        if cfg!(safeguards_at_least = "strict") {
+        if cfg!(safeguards_strict) {
             copy.with_checked_type()
                 .expect("copied array should have same type as original array")
         } else {

godot-core/src/classes/class_runtime.rs

@@ -8,10 +8,10 @@
 //! Runtime checks and inspection of Godot classes.
 
 use crate::builtin::{GString, StringName, Variant, VariantType};
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 use crate::classes::{ClassDb, Object};
 use crate::meta::CallContext;
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 use crate::meta::ClassId;
 use crate::obj::{bounds, Bounds, Gd, GodotClass, InstanceId, RawGd, Singleton};
 use crate::sys;
@@ -191,7 +191,7 @@ where
     Gd::<T>::from_obj_sys(object_ptr)
 }
 
-#[cfg(safeguards_at_least = "balanced")]
+#[cfg(safeguards_balanced)]
 pub(crate) fn ensure_object_alive(
     instance_id: InstanceId,
     old_object_ptr: sys::GDExtensionObjectPtr,
@@ -212,7 +212,7 @@ pub(crate) fn ensure_object_alive(
     );
 }
 
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 pub(crate) fn ensure_object_inherits(derived: ClassId, base: ClassId, instance_id: InstanceId) {
     if derived == base
         || base == Object::class_id() // for Object base, anything inherits by definition
@@ -227,7 +227,7 @@ pub(crate) fn ensure_object_inherits(derived: ClassId, base: ClassId, instance_i
     )
 }
 
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 pub(crate) fn ensure_binding_not_null<T>(binding: sys::GDExtensionClassInstancePtr)
 where
     T: GodotClass + Bounds<Declarer = bounds::DeclUser>,
@@ -255,7 +255,7 @@ where
 // Implementation of this file
 
 /// Checks if `derived` inherits from `base`, using a cache for _successful_ queries.
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 fn is_derived_base_cached(derived: ClassId, base: ClassId) -> bool {
     use std::collections::HashSet;
 

godot-core/src/init/mod.rs

@@ -535,14 +535,12 @@ unsafe fn ensure_godot_features_compatible() {
     out!("Check Godot precision setting...");
 
     #[cfg(feature = "debug-log")] // Display safeguards level in debug log.
-    let safeguards_level = if cfg!(safeguards_at_least = "strict") {
+    let safeguards_level = if cfg!(safeguards_strict) {
         "strict"
-    } else if cfg!(safeguards_at_least = "balanced") {
+    } else if cfg!(safeguards_balanced) {
         "balanced"
-    } else if cfg!(safeguards_at_least = "disengaged") {
-        "disengaged"
     } else {
-        "unknown"
+        "disengaged"
     };
     out!("Safeguards: {safeguards_level}");
 

godot-core/src/meta/error/convert_error.rs

@@ -189,7 +189,7 @@ pub(crate) enum FromGodotError {
     },
 
     /// Special case of `BadArrayType` where a custom int type such as `i8` cannot hold a dynamic `i64` value.
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     BadArrayTypeInt {
         expected_int_type: &'static str,
         value: i64,
@@ -234,7 +234,7 @@ impl fmt::Display for FromGodotError {
 
                 write!(f, "expected array of type {exp_class}, got {act_class}")
             }
-            #[cfg(safeguards_at_least = "strict")]
+            #[cfg(safeguards_strict)]
             Self::BadArrayTypeInt {
                 expected_int_type,
                 value,

godot-core/src/meta/signature.rs

@@ -145,7 +145,7 @@ impl<Params: OutParamTuple, Ret: FromGodot> Signature<Params, Ret> {
 
         // Note: varcalls are not safe from failing, if they happen through an object pointer -> validity check necessary.
         // paranoid since we already check the validity in check_rtti, this is unlikely to happen.
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         if let Some(instance_id) = maybe_instance_id {
             crate::classes::ensure_object_alive(instance_id, object_ptr, &call_ctx);
         }
@@ -307,7 +307,7 @@ impl<Params: OutParamTuple, Ret: FromGodot> Signature<Params, Ret> {
         // $crate::out!("out_class_ptrcall: {call_ctx}");
 
         // paranoid since we already check the validity in check_rtti, this is unlikely to happen.
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         if let Some(instance_id) = maybe_instance_id {
             crate::classes::ensure_object_alive(instance_id, object_ptr, &call_ctx);
         }

godot-core/src/obj/base.rs

@@ -5,13 +5,14 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 use std::cell::Cell;
 use std::cell::RefCell;
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
 use std::fmt::{Debug, Display, Formatter, Result as FmtResult};
 use std::mem::ManuallyDrop;
+#[cfg(safeguards_strict)]
 use std::rc::Rc;
 
 use crate::builtin::Callable;
@@ -27,7 +28,7 @@ thread_local! {
 }
 
 /// Represents the initialization state of a `Base<T>` object.
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 enum InitState {
     /// Object is being constructed (inside `I*::init()` or `Gd::from_init_fn()`).
@@ -38,14 +39,14 @@ enum InitState {
     Script,
 }
 
-#[cfg(safeguards_at_least = "strict")]
+#[cfg(safeguards_strict)]
 macro_rules! base_from_obj {
     ($obj:expr, $state:expr) => {
         Base::from_obj($obj, $state)
     };
 }
 
-#[cfg(not(safeguards_at_least = "strict"))]
+#[cfg(not(safeguards_strict))]
 macro_rules! base_from_obj {
     ($obj:expr, $state:expr) => {
         Base::from_obj($obj)
@@ -82,7 +83,7 @@ pub struct Base<T: GodotClass> {
     /// Tracks the initialization state of this `Base<T>` in Debug mode.
     ///
     /// Rc allows to "copy-construct" the base from an existing one, while still affecting the user-instance through the original `Base<T>`.
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     init_state: Rc<Cell<InitState>>,
 }
 
@@ -95,14 +96,14 @@ impl<T: GodotClass> Base<T> {
     /// `base` must be alive at the time of invocation, i.e. user `init()` (which could technically destroy it) must not have run yet.
     /// If `base` is destroyed while the returned `Base<T>` is in use, that constitutes a logic error, not a safety issue.
     pub(crate) unsafe fn from_base(base: &Base<T>) -> Base<T> {
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         assert!(base.obj.is_instance_valid());
 
         let obj = Gd::from_obj_sys_weak(base.obj.obj_sys());
 
         Self {
             obj: ManuallyDrop::new(obj),
-            #[cfg(safeguards_at_least = "strict")]
+            #[cfg(safeguards_strict)]
             init_state: Rc::clone(&base.init_state),
         }
     }
@@ -115,7 +116,7 @@ impl<T: GodotClass> Base<T> {
     /// `gd` must be alive at the time of invocation. If it is destroyed while the returned `Base<T>` is in use, that constitutes a logic
     /// error, not a safety issue.
     pub(crate) unsafe fn from_script_gd(gd: &Gd<T>) -> Self {
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         assert!(gd.is_instance_valid());
 
         let obj = Gd::from_obj_sys_weak(gd.obj_sys());
@@ -143,15 +144,15 @@ impl<T: GodotClass> Base<T> {
         base_from_obj!(obj, InitState::ObjectConstructing)
     }
 
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     fn from_obj(obj: Gd<T>, init_state: InitState) -> Self {
         Self {
             obj: ManuallyDrop::new(obj),
             init_state: Rc::new(Cell::new(init_state)),
         }
     }
 
-    #[cfg(not(safeguards_at_least = "strict"))]
+    #[cfg(not(safeguards_strict))]
     fn from_obj(obj: Gd<T>) -> Self {
         Self {
             obj: ManuallyDrop::new(obj),
@@ -178,7 +179,7 @@ impl<T: GodotClass> Base<T> {
     /// # Panics (Debug)
     /// If called outside an initialization function, or for ref-counted objects on a non-main thread.
     pub fn to_init_gd(&self) -> Gd<T> {
-        #[cfg(safeguards_at_least = "strict")] // debug_assert! still checks existence of symbols.
+        #[cfg(safeguards_strict)] // debug_assert! still checks existence of symbols.
         assert!(
             self.is_initializing(),
             "Base::to_init_gd() can only be called during object initialization, inside I*::init() or Gd::from_init_fn()"
@@ -250,7 +251,7 @@ impl<T: GodotClass> Base<T> {
 
     /// Finalizes the initialization of this `Base<T>` and returns whether
     pub(crate) fn mark_initialized(&mut self) {
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         {
             assert_eq!(
                 self.init_state.get(),
@@ -267,7 +268,7 @@ impl<T: GodotClass> Base<T> {
     /// Returns a [`Gd`] referencing the base object, assuming the derived object is fully constructed.
     #[doc(hidden)]
     pub fn __fully_constructed_gd(&self) -> Gd<T> {
-        #[cfg(safeguards_at_least = "strict")] // debug_assert! still checks existence of symbols.
+        #[cfg(safeguards_strict)] // debug_assert! still checks existence of symbols.
         assert!(
             !self.is_initializing(),
             "WithBaseField::to_gd(), base(), base_mut() can only be called on fully-constructed objects, after I*::init() or Gd::from_init_fn()"
@@ -298,7 +299,7 @@ impl<T: GodotClass> Base<T> {
 
     /// Returns a passive reference to the base object, for use in script contexts only.
     pub(crate) fn to_script_passive(&self) -> PassiveGd<T> {
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         assert_eq!(
             self.init_state.get(),
             InitState::Script,
@@ -310,15 +311,15 @@ impl<T: GodotClass> Base<T> {
     }
 
     /// Returns `true` if this `Base<T>` is currently in the initializing state.
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     fn is_initializing(&self) -> bool {
         self.init_state.get() == InitState::ObjectConstructing
     }
 
     /// Returns a [`Gd`] referencing the base object, assuming the derived object is fully constructed.
     #[doc(hidden)]
     pub fn __constructed_gd(&self) -> Gd<T> {
-        #[cfg(safeguards_at_least = "strict")] // debug_assert! still checks existence of symbols.
+        #[cfg(safeguards_strict)] // debug_assert! still checks existence of symbols.
         assert!(
             !self.is_initializing(),
             "WithBaseField::to_gd(), base(), base_mut() can only be called on fully-constructed objects, after I*::init() or Gd::from_init_fn()"
@@ -335,7 +336,7 @@ impl<T: GodotClass> Base<T> {
     /// # Safety
     /// Caller must ensure that the underlying object remains valid for the entire lifetime of the returned `PassiveGd`.
     pub(crate) unsafe fn constructed_passive(&self) -> PassiveGd<T> {
-        #[cfg(safeguards_at_least = "strict")] // debug_assert! still checks existence of symbols.
+        #[cfg(safeguards_strict)] // debug_assert! still checks existence of symbols.
         assert!(
             !self.is_initializing(),
             "WithBaseField::base(), base_mut() can only be called on fully-constructed objects, after I*::init() or Gd::from_init_fn()"

godot-core/src/obj/casts.rs

@@ -48,15 +48,15 @@ impl<T: GodotClass, U: GodotClass> CastSuccess<T, U> {
     }
 
     /// Access shared reference to destination, without consuming object.
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     pub fn as_dest_ref(&self) -> &RawGd<U> {
         self.check_validity();
         &self.dest
     }
 
     /// Access exclusive reference to destination, without consuming object.
     pub fn as_dest_mut(&mut self) -> &mut RawGd<U> {
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         self.check_validity();
         &mut self.dest
     }
@@ -71,14 +71,14 @@ impl<T: GodotClass, U: GodotClass> CastSuccess<T, U> {
             self.dest.instance_id_unchecked(),
             "traded_source must point to the same object as the destination"
         );
-        #[cfg(safeguards_at_least = "strict")]
+        #[cfg(safeguards_strict)]
         self.check_validity();
 
         std::mem::forget(traded_source);
         ManuallyDrop::into_inner(self.dest)
     }
 
-    #[cfg(safeguards_at_least = "strict")]
+    #[cfg(safeguards_strict)]
     fn check_validity(&self) {
         assert!(self.dest.is_null() || self.dest.is_instance_valid());
     }