From 4ea5cbeaf42d84bcdd61836c94eeac43bd06de15 Mon Sep 17 00:00:00 2001
From: Lili Zoey Zyli <sayaks1@gmail.com>
Date: Sun, 26 Nov 2023 05:33:09 +0100
Subject: [PATCH 1/7] Make access to base field go through trait.

---
 examples/dodge-the-creeps/rust/src/hud.rs     | 20 +++++------
 .../dodge-the-creeps/rust/src/main_scene.rs   | 30 ++++++++--------
 examples/dodge-the-creeps/rust/src/mob.rs     |  6 ++--
 examples/dodge-the-creeps/rust/src/player.rs  | 22 ++++++------
 godot-core/src/obj/base.rs                    | 35 +++++++++----------
 godot-core/src/obj/guards.rs                  | 35 +++++++++++++++++++
 godot-core/src/obj/traits.rs                  | 23 ++++++++++++
 godot-core/src/storage.rs                     |  4 +--
 godot-macros/src/class/derive_godot_class.rs  |  4 +++
 .../builtin_tests/containers/signal_test.rs   |  4 +--
 itest/rust/src/object_tests/base_test.rs      | 12 +++----
 itest/rust/src/register_tests/func_test.rs    |  2 +-
 12 files changed, 129 insertions(+), 68 deletions(-)

diff --git a/examples/dodge-the-creeps/rust/src/hud.rs b/examples/dodge-the-creeps/rust/src/hud.rs
index 326ed141a..ebcc87324 100644
--- a/examples/dodge-the-creeps/rust/src/hud.rs
+++ b/examples/dodge-the-creeps/rust/src/hud.rs
@@ -15,53 +15,53 @@ impl Hud {
 
     #[func]
     pub fn show_message(&self, text: GString) {
-        let mut message_label = self.base.get_node_as::<Label>("MessageLabel");
+        let mut message_label = self.base().get_node_as::<Label>("MessageLabel");
         message_label.set_text(text);
         message_label.show();
 
-        let mut timer = self.base.get_node_as::<Timer>("MessageTimer");
+        let mut timer = self.base().get_node_as::<Timer>("MessageTimer");
         timer.start();
     }
 
     pub fn show_game_over(&self) {
         self.show_message("Game Over".into());
 
-        let mut timer = self.base.get_tree().unwrap().create_timer(2.0).unwrap();
-        timer.connect("timeout".into(), self.base.callable("show_start_button"));
+        let mut timer = self.base().get_tree().unwrap().create_timer(2.0).unwrap();
+        timer.connect("timeout".into(), self.base().callable("show_start_button"));
     }
 
     #[func]
     fn show_start_button(&mut self) {
-        let mut message_label = self.base.get_node_as::<Label>("MessageLabel");
+        let mut message_label = self.base().get_node_as::<Label>("MessageLabel");
         message_label.set_text("Dodge the\nCreeps!".into());
         message_label.show();
 
-        let mut button = self.base.get_node_as::<Button>("StartButton");
+        let mut button = self.base().get_node_as::<Button>("StartButton");
         button.show();
     }
 
     #[func]
     pub fn update_score(&self, score: i64) {
-        let mut label = self.base.get_node_as::<Label>("ScoreLabel");
+        let mut label = self.base().get_node_as::<Label>("ScoreLabel");
 
         label.set_text(score.to_string().into());
     }
 
     #[func]
     fn on_start_button_pressed(&mut self) {
-        let mut button = self.base.get_node_as::<Button>("StartButton");
+        let mut button = self.base().get_node_as::<Button>("StartButton");
         button.hide();
 
         // Note: this works only because `start_game` is a deferred signal.
         // This method keeps a &mut Hud, and start_game calls Main::new_game(), which itself accesses this Hud
         // instance through Gd<Hud>::bind_mut(). It will try creating a 2nd &mut reference, and thus panic.
         // Deferring the signal is one option to work around it.
-        self.base.emit_signal("start_game".into(), &[]);
+        self.base_mut().emit_signal("start_game".into(), &[]);
     }
 
     #[func]
     fn on_message_timer_timeout(&self) {
-        let mut message_label = self.base.get_node_as::<Label>("MessageLabel");
+        let mut message_label = self.base().get_node_as::<Label>("MessageLabel");
         message_label.hide()
     }
 }
diff --git a/examples/dodge-the-creeps/rust/src/main_scene.rs b/examples/dodge-the-creeps/rust/src/main_scene.rs
index 1267ff796..5e5e4ecc6 100644
--- a/examples/dodge-the-creeps/rust/src/main_scene.rs
+++ b/examples/dodge-the-creeps/rust/src/main_scene.rs
@@ -24,13 +24,13 @@ pub struct Main {
 impl Main {
     #[func]
     fn game_over(&mut self) {
-        let mut score_timer = self.base.get_node_as::<Timer>("ScoreTimer");
-        let mut mob_timer = self.base.get_node_as::<Timer>("MobTimer");
+        let mut score_timer = self.base().get_node_as::<Timer>("ScoreTimer");
+        let mut mob_timer = self.base().get_node_as::<Timer>("MobTimer");
 
         score_timer.stop();
         mob_timer.stop();
 
-        let mut hud = self.base.get_node_as::<Hud>("Hud");
+        let mut hud = self.base().get_node_as::<Hud>("Hud");
         hud.bind_mut().show_game_over();
 
         self.music().stop();
@@ -39,16 +39,16 @@ impl Main {
 
     #[func]
     pub fn new_game(&mut self) {
-        let start_position = self.base.get_node_as::<Marker2D>("StartPosition");
-        let mut player = self.base.get_node_as::<player::Player>("Player");
-        let mut start_timer = self.base.get_node_as::<Timer>("StartTimer");
+        let start_position = self.base().get_node_as::<Marker2D>("StartPosition");
+        let mut player = self.base().get_node_as::<player::Player>("Player");
+        let mut start_timer = self.base().get_node_as::<Timer>("StartTimer");
 
         self.score = 0;
 
         player.bind_mut().start(start_position.get_position());
         start_timer.start();
 
-        let mut hud = self.base.get_node_as::<Hud>("Hud");
+        let mut hud = self.base().get_node_as::<Hud>("Hud");
         let hud = hud.bind_mut();
         hud.update_score(self.score);
         hud.show_message("Get Ready".into());
@@ -58,8 +58,8 @@ impl Main {
 
     #[func]
     fn on_start_timer_timeout(&self) {
-        let mut mob_timer = self.base.get_node_as::<Timer>("MobTimer");
-        let mut score_timer = self.base.get_node_as::<Timer>("ScoreTimer");
+        let mut mob_timer = self.base().get_node_as::<Timer>("MobTimer");
+        let mut score_timer = self.base().get_node_as::<Timer>("ScoreTimer");
         mob_timer.start();
         score_timer.start();
     }
@@ -68,14 +68,14 @@ impl Main {
     fn on_score_timer_timeout(&mut self) {
         self.score += 1;
 
-        let mut hud = self.base.get_node_as::<Hud>("Hud");
+        let mut hud = self.base().get_node_as::<Hud>("Hud");
         hud.bind_mut().update_score(self.score);
     }
 
     #[func]
     fn on_mob_timer_timeout(&mut self) {
         let mut mob_spawn_location = self
-            .base
+            .base()
             .get_node_as::<PathFollow2D>("MobPath/MobSpawnLocation");
 
         let mut mob_scene = self.mob_scene.instantiate_as::<RigidBody2D>();
@@ -91,7 +91,7 @@ impl Main {
 
         mob_scene.set_rotation(direction);
 
-        self.base.add_child(mob_scene.clone().upcast());
+        self.base_mut().add_child(mob_scene.clone().upcast());
 
         let mut mob = mob_scene.cast::<mob::Mob>();
         let range = {
@@ -102,7 +102,7 @@ impl Main {
 
         mob.set_linear_velocity(Vector2::new(range, 0.0).rotated(real::from_f32(direction)));
 
-        let mut hud = self.base.get_node_as::<Hud>("Hud");
+        let mut hud = self.base().get_node_as::<Hud>("Hud");
         hud.connect("start_game".into(), mob.callable("on_start_game"));
     }
 
@@ -132,7 +132,7 @@ impl INode for Main {
         // If the resource does not exist or has an incompatible type, this panics.
         // There is also try_load() if you want to check whether loading succeeded.
         self.mob_scene = load("res://Mob.tscn");
-        self.music = Some(self.base.get_node_as("Music"));
-        self.death_sound = Some(self.base.get_node_as("DeathSound"));
+        self.music = Some(self.base().get_node_as("Music"));
+        self.death_sound = Some(self.base().get_node_as("DeathSound"));
     }
 }
diff --git a/examples/dodge-the-creeps/rust/src/mob.rs b/examples/dodge-the-creeps/rust/src/mob.rs
index 55eac6889..203c498af 100644
--- a/examples/dodge-the-creeps/rust/src/mob.rs
+++ b/examples/dodge-the-creeps/rust/src/mob.rs
@@ -16,12 +16,12 @@ pub struct Mob {
 impl Mob {
     #[func]
     fn on_visibility_screen_exited(&mut self) {
-        self.base.queue_free();
+        self.base_mut().queue_free();
     }
 
     #[func]
     fn on_start_game(&mut self) {
-        self.base.queue_free();
+        self.base_mut().queue_free();
     }
 }
 
@@ -37,7 +37,7 @@ impl IRigidBody2D for Mob {
 
     fn ready(&mut self) {
         let mut sprite = self
-            .base
+            .base()
             .get_node_as::<AnimatedSprite2D>("AnimatedSprite2D");
 
         sprite.play();
diff --git a/examples/dodge-the-creeps/rust/src/player.rs b/examples/dodge-the-creeps/rust/src/player.rs
index c2c4adf83..2b0d3ea49 100644
--- a/examples/dodge-the-creeps/rust/src/player.rs
+++ b/examples/dodge-the-creeps/rust/src/player.rs
@@ -18,11 +18,11 @@ impl Player {
 
     #[func]
     fn on_player_body_entered(&mut self, _body: Gd<PhysicsBody2D>) {
-        self.base.hide();
-        self.base.emit_signal("hit".into(), &[]);
+        self.base_mut().hide();
+        self.base_mut().emit_signal("hit".into(), &[]);
 
         let mut collision_shape = self
-            .base
+            .base()
             .get_node_as::<CollisionShape2D>("CollisionShape2D");
 
         collision_shape.set_deferred("disabled".into(), true.to_variant());
@@ -30,11 +30,11 @@ impl Player {
 
     #[func]
     pub fn start(&mut self, pos: Vector2) {
-        self.base.set_global_position(pos);
-        self.base.show();
+        self.base_mut().set_global_position(pos);
+        self.base_mut().show();
 
         let mut collision_shape = self
-            .base
+            .base()
             .get_node_as::<CollisionShape2D>("CollisionShape2D");
 
         collision_shape.set_disabled(false);
@@ -52,14 +52,14 @@ impl IArea2D for Player {
     }
 
     fn ready(&mut self) {
-        let viewport = self.base.get_viewport_rect();
+        let viewport = self.base().get_viewport_rect();
         self.screen_size = viewport.size;
-        self.base.hide();
+        self.base_mut().hide();
     }
 
     fn process(&mut self, delta: f64) {
         let mut animated_sprite = self
-            .base
+            .base()
             .get_node_as::<AnimatedSprite2D>("AnimatedSprite2D");
 
         let mut velocity = Vector2::new(0.0, 0.0);
@@ -101,11 +101,11 @@ impl IArea2D for Player {
         }
 
         let change = velocity * real::from_f64(delta);
-        let position = self.base.get_global_position() + change;
+        let position = self.base().get_global_position() + change;
         let position = Vector2::new(
             position.x.clamp(0.0, self.screen_size.x),
             position.y.clamp(0.0, self.screen_size.y),
         );
-        self.base.set_global_position(position);
+        self.base_mut().set_global_position(position);
     }
 }
diff --git a/godot-core/src/obj/base.rs b/godot-core/src/obj/base.rs
index b551d7834..ec8b0100d 100644
--- a/godot-core/src/obj/base.rs
+++ b/godot-core/src/obj/base.rs
@@ -10,7 +10,6 @@ use crate::obj::GodotClass;
 use crate::{engine, sys};
 use std::fmt::{Debug, Display, Formatter, Result as FmtResult};
 use std::mem::ManuallyDrop;
-use std::ops::{Deref, DerefMut};
 
 /// Restricted version of `Gd`, to hold the base instance inside a user's `GodotClass`.
 ///
@@ -39,7 +38,7 @@ impl<T: GodotClass> Base<T> {
     /// # Safety
     /// The returned Base is a weak pointer, so holding it will not keep the object alive. It must not be accessed after the object is destroyed.
     pub(crate) unsafe fn from_base(base: &Base<T>) -> Base<T> {
-        Base::from_obj(Gd::from_obj_sys_weak(base.obj_sys()))
+        Base::from_obj(Gd::from_obj_sys_weak(base.as_gd().obj_sys()))
     }
 
     // Note: not &mut self, to only borrow one field and not the entire struct
@@ -62,6 +61,22 @@ impl<T: GodotClass> Base<T> {
             obj: ManuallyDrop::new(obj),
         }
     }
+
+    /// Returns a [`Gd`] referencing the same object as this reference.
+    ///
+    /// Using this method to call methods on the base field of a Rust object is discouraged, instead use the
+    /// methods from [`WithBaseField`](super::WithBaseField) when possible.
+    pub fn to_gd(&self) -> Gd<T> {
+        (*self.obj).clone()
+    }
+
+    /// Returns a [`Gd`] referencing the same object as this reference.
+    ///
+    /// Using this method to call methods on the base field of a Rust object is discouraged, instead use the
+    /// methods from [`WithBaseField`](super::WithBaseField) when possible.
+    pub fn as_gd(&self) -> &Gd<T> {
+        &self.obj
+    }
 }
 
 impl<T: GodotClass> Debug for Base<T> {
@@ -75,19 +90,3 @@ impl<T: GodotClass> Display for Base<T> {
         engine::display_string(&self.obj, f)
     }
 }
-
-impl<T: GodotClass> Deref for Base<T> {
-    type Target = Gd<T>;
-
-    fn deref(&self) -> &Self::Target {
-        &self.obj
-    }
-}
-
-// Note: having DerefMut is almost equivalent to directly storing Gd<T>
-// Main difference is that an existing Gd<T> cannot be used as the base, and mem::take/replace() don't work as easily
-impl<T: GodotClass> DerefMut for Base<T> {
-    fn deref_mut(&mut self) -> &mut Self::Target {
-        &mut self.obj
-    }
-}
diff --git a/godot-core/src/obj/guards.rs b/godot-core/src/obj/guards.rs
index 1dba12be2..26135f5b3 100644
--- a/godot-core/src/obj/guards.rs
+++ b/godot-core/src/obj/guards.rs
@@ -10,10 +10,13 @@ use godot_ffi::out;
 #[cfg(not(feature = "experimental-threads"))]
 use std::cell;
 use std::fmt::Debug;
+use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
 #[cfg(feature = "experimental-threads")]
 use std::sync;
 
+use super::{Gd, GodotClass};
+
 /// Immutably/shared bound reference guard for a [`Gd`][crate::obj::Gd] smart pointer.
 ///
 /// See [`Gd::bind`][crate::obj::Gd::bind] for usage.
@@ -101,3 +104,35 @@ impl<T> Drop for GdMut<'_, T> {
         out!("GdMut drop: {:?}", std::any::type_name::<T>());
     }
 }
+
+pub struct BaseRef<'a, T: GodotClass> {
+    pub(crate) gd: Gd<T>,
+    pub(crate) _p: PhantomData<&'a ()>,
+}
+
+impl<T: GodotClass> Deref for BaseRef<'_, T> {
+    type Target = Gd<T>;
+
+    fn deref(&self) -> &Gd<T> {
+        &self.gd
+    }
+}
+
+pub struct BaseMut<'a, T: GodotClass> {
+    pub(crate) gd: Gd<T>,
+    pub(crate) _p: PhantomData<&'a mut ()>,
+}
+
+impl<T: GodotClass> Deref for BaseMut<'_, T> {
+    type Target = Gd<T>;
+
+    fn deref(&self) -> &Gd<T> {
+        &self.gd
+    }
+}
+
+impl<T: GodotClass> DerefMut for BaseMut<'_, T> {
+    fn deref_mut(&mut self) -> &mut Gd<T> {
+        &mut self.gd
+    }
+}
diff --git a/godot-core/src/obj/traits.rs b/godot-core/src/obj/traits.rs
index aadb4238e..4e4554de5 100644
--- a/godot-core/src/obj/traits.rs
+++ b/godot-core/src/obj/traits.rs
@@ -5,6 +5,8 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use std::marker::PhantomData;
+
 use crate::builder::ClassBuilder;
 use crate::builtin::meta::ClassName;
 use crate::builtin::GString;
@@ -13,6 +15,8 @@ use crate::obj::Gd;
 
 use godot_ffi as sys;
 
+use super::{Base, BaseMut, BaseRef};
+
 /// Makes `T` eligible to be managed by Godot and stored in [`Gd<T>`][crate::obj::Gd] pointers.
 ///
 /// The behavior of types implementing this trait is influenced by the associated types; check their documentation for information.
@@ -241,6 +245,25 @@ pub trait WithBaseField: GodotClass {
     /// This is intended to be stored or passed to engine methods. You cannot call `bind()` or `bind_mut()` on it, while the method
     /// calling `to_gd()` is still running; that would lead to a double borrow panic.
     fn to_gd(&self) -> Gd<Self>;
+
+    /// Returns a reference to the `Base` stored by this object.
+    fn base_field(&self) -> &Base<Self::Base>;
+
+    /// Returns a shared reference suitable for calling engine methods on this object.
+    fn base(&self) -> BaseRef<'_, Self::Base> {
+        BaseRef {
+            gd: self.base_field().to_gd(),
+            _p: PhantomData,
+        }
+    }
+
+    /// Returns a mutable reference suitable for calling engine methods on this object.
+    fn base_mut(&mut self) -> BaseMut<'_, Self::Base> {
+        BaseMut {
+            gd: self.base_field().to_gd(),
+            _p: PhantomData,
+        }
+    }
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/godot-core/src/storage.rs b/godot-core/src/storage.rs
index 6206546bd..7fea885f6 100644
--- a/godot-core/src/storage.rs
+++ b/godot-core/src/storage.rs
@@ -86,7 +86,7 @@ mod single_threaded {
         where
             T: Inherits<<T as GodotClass>::Base>,
         {
-            self.base.clone().cast()
+            self.base.to_gd().cast()
         }
 
         pub(super) fn godot_ref_count(&self) -> u32 {
@@ -212,7 +212,7 @@ mod multi_threaded {
         where
             T: Inherits<<T as GodotClass>::Base>,
         {
-            self.base.clone().cast()
+            self.base().clone().cast()
         }
 
         pub(super) fn godot_ref_count(&self) -> u32 {
diff --git a/godot-macros/src/class/derive_godot_class.rs b/godot-macros/src/class/derive_godot_class.rs
index 489fa893a..140f05265 100644
--- a/godot-macros/src/class/derive_godot_class.rs
+++ b/godot-macros/src/class/derive_godot_class.rs
@@ -60,6 +60,10 @@ pub fn derive_godot_class(decl: Declaration) -> ParseResult<TokenStream> {
                 fn to_gd(&self) -> ::godot::obj::Gd<Self> {
                     ::godot::obj::Gd::clone(&*self.#name).cast()
                 }
+
+                fn base_field(&self) -> &::godot::obj::Base<<Self as ::godot::obj::GodotClass>::Base> {
+                    &self.#name
+                }
             }
         }
     } else {
diff --git a/itest/rust/src/builtin_tests/containers/signal_test.rs b/itest/rust/src/builtin_tests/containers/signal_test.rs
index 5b005b57b..be6062dc3 100644
--- a/itest/rust/src/builtin_tests/containers/signal_test.rs
+++ b/itest/rust/src/builtin_tests/containers/signal_test.rs
@@ -11,7 +11,7 @@ use godot::bind::{godot_api, GodotClass};
 use godot::builtin::{GString, Variant};
 
 use godot::engine::Object;
-use godot::obj::{Base, Gd, UserClass};
+use godot::obj::{Base, Gd, UserClass, WithBaseField};
 use godot::sys;
 
 use crate::framework::itest;
@@ -51,7 +51,7 @@ impl Receiver {
     }
     #[func]
     fn receive_2_arg(&self, arg1: Gd<Object>, arg2: GString) {
-        assert_eq!(self.base.clone(), arg1);
+        assert_eq!(self.base().clone(), arg1);
         assert_eq!(SIGNAL_ARG_STRING, arg2.to_string());
 
         self.used[2].set(true);
diff --git a/itest/rust/src/object_tests/base_test.rs b/itest/rust/src/object_tests/base_test.rs
index 560da278b..00b0feb40 100644
--- a/itest/rust/src/object_tests/base_test.rs
+++ b/itest/rust/src/object_tests/base_test.rs
@@ -18,7 +18,7 @@ fn base_test_is_weak() {
 fn base_instance_id() {
     let obj = Based::alloc_gd();
     let obj_id = obj.instance_id();
-    let base_id = obj.bind().base.instance_id();
+    let base_id = obj.bind().base().instance_id();
 
     assert_eq!(obj_id, base_id);
     obj.free();
@@ -52,7 +52,7 @@ fn base_display() {
     let obj = Based::alloc_gd();
     {
         let guard = obj.bind();
-        let id = guard.base.instance_id();
+        let id = guard.base().instance_id();
 
         // We expect the dynamic type to be part of Godot's to_string(), so Based and not Node2D
         let actual = format!(".:{}:.", guard.base);
@@ -68,7 +68,7 @@ fn base_debug() {
     let obj = Based::alloc_gd();
     {
         let guard = obj.bind();
-        let id = guard.base.instance_id();
+        let id = guard.base().instance_id();
 
         // We expect the dynamic type to be part of Godot's to_string(), so Based and not Node2D
         let actual = format!(".:{:?}:.", guard.base);
@@ -81,15 +81,15 @@ fn base_debug() {
 
 #[itest]
 fn base_with_init() {
-    let obj = Gd::<Based>::from_init_fn(|mut base| {
-        base.set_rotation(11.0);
+    let obj = Gd::<Based>::from_init_fn(|base| {
+        base.to_gd().set_rotation(11.0);
         Based { base, i: 732 }
     });
 
     {
         let guard = obj.bind();
         assert_eq!(guard.i, 732);
-        assert_eq!(guard.base.get_rotation(), 11.0);
+        assert_eq!(guard.base().get_rotation(), 11.0);
     }
     obj.free();
 }
diff --git a/itest/rust/src/register_tests/func_test.rs b/itest/rust/src/register_tests/func_test.rs
index 589742e4b..052532843 100644
--- a/itest/rust/src/register_tests/func_test.rs
+++ b/itest/rust/src/register_tests/func_test.rs
@@ -180,7 +180,7 @@ impl GdSelfReference {
         // Since a self reference is held while the signal is emitted, when
         // GDScript tries to call update_internal(), there will be a failure due
         // to the double borrow and self.internal_value won't be changed.
-        self.base.emit_signal(
+        self.base_mut().emit_signal(
             "update_internal_signal".into(),
             &[new_internal.to_variant()],
         );

From 9c3480b53ed49b5f9712ccef8f9e4ff159d14287 Mon Sep 17 00:00:00 2001
From: Lili Zoey Zyli <sayaks1@gmail.com>
Date: Sun, 26 Nov 2023 05:58:51 +0100
Subject: [PATCH 2/7] Add `Storage` trait.

---
 godot-core/src/lib.rs                      |   2 +-
 godot-core/src/obj/guards.rs               |  64 ++--
 godot-core/src/obj/raw.rs                  |   6 +-
 godot-core/src/obj/traits.rs               |   5 +-
 godot-core/src/registry.rs                 |   1 +
 godot-core/src/storage.rs                  | 325 ++++-----------------
 godot-core/src/storage/multi_threaded.rs   | 173 +++++++++++
 godot-core/src/storage/single_threaded.rs  | 107 +++++++
 godot-macros/src/class/data_models/func.rs |   6 +-
 9 files changed, 373 insertions(+), 316 deletions(-)
 create mode 100644 godot-core/src/storage/multi_threaded.rs
 create mode 100644 godot-core/src/storage/single_threaded.rs

diff --git a/godot-core/src/lib.rs b/godot-core/src/lib.rs
index dc6686b2c..b0ebe95a8 100644
--- a/godot-core/src/lib.rs
+++ b/godot-core/src/lib.rs
@@ -50,7 +50,7 @@ pub mod private {
 
     pub use crate::gen::classes::class_macros;
     pub use crate::registry::{callbacks, ClassPlugin, ErasedRegisterFn, PluginComponent};
-    pub use crate::storage::as_storage;
+    pub use crate::storage::{as_storage, Storage};
     pub use sys::out;
 
     use crate::{log, sys};
diff --git a/godot-core/src/obj/guards.rs b/godot-core/src/obj/guards.rs
index 26135f5b3..d366db29a 100644
--- a/godot-core/src/obj/guards.rs
+++ b/godot-core/src/obj/guards.rs
@@ -7,13 +7,11 @@
 
 use godot_ffi::out;
 
-#[cfg(not(feature = "experimental-threads"))]
-use std::cell;
 use std::fmt::Debug;
 use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
-#[cfg(feature = "experimental-threads")]
-use std::sync;
+
+use crate::storage::{MutGuard, RefGuard};
 
 use super::{Gd, GodotClass};
 
@@ -21,36 +19,25 @@ use super::{Gd, GodotClass};
 ///
 /// See [`Gd::bind`][crate::obj::Gd::bind] for usage.
 #[derive(Debug)]
-pub struct GdRef<'a, T> {
-    #[cfg(not(feature = "experimental-threads"))]
-    cell_ref: cell::Ref<'a, T>,
-
-    #[cfg(feature = "experimental-threads")]
-    cell_ref: sync::RwLockReadGuard<'a, T>,
+pub struct GdRef<'a, T: GodotClass> {
+    guard: RefGuard<'a, T>,
 }
 
-impl<'a, T> GdRef<'a, T> {
-    #[cfg(not(feature = "experimental-threads"))]
-    pub(crate) fn from_cell(cell_ref: cell::Ref<'a, T>) -> Self {
-        Self { cell_ref }
-    }
-
-    #[cfg(feature = "experimental-threads")]
-    pub(crate) fn from_cell(cell_ref: sync::RwLockReadGuard<'a, T>) -> Self {
-        out!("GdRef init: {:?}", std::any::type_name::<T>());
-        Self { cell_ref }
+impl<'a, T: GodotClass> GdRef<'a, T> {
+    pub(crate) fn from_guard(guard: RefGuard<'a, T>) -> Self {
+        Self { guard }
     }
 }
 
-impl<T> Deref for GdRef<'_, T> {
+impl<T: GodotClass> Deref for GdRef<'_, T> {
     type Target = T;
 
     fn deref(&self) -> &T {
-        self.cell_ref.deref()
+        &self.guard
     }
 }
 
-impl<T> Drop for GdRef<'_, T> {
+impl<T: GodotClass> Drop for GdRef<'_, T> {
     fn drop(&mut self) {
         out!("GdRef drop: {:?}", std::any::type_name::<T>());
     }
@@ -64,42 +51,31 @@ impl<T> Drop for GdRef<'_, T> {
 ///
 /// See [`Gd::bind_mut`][crate::obj::Gd::bind_mut] for usage.
 #[derive(Debug)]
-pub struct GdMut<'a, T> {
-    #[cfg(not(feature = "experimental-threads"))]
-    cell_ref: cell::RefMut<'a, T>,
-
-    #[cfg(feature = "experimental-threads")]
-    cell_ref: sync::RwLockWriteGuard<'a, T>,
+pub struct GdMut<'a, T: GodotClass> {
+    guard: MutGuard<'a, T>,
 }
 
-impl<'a, T> GdMut<'a, T> {
-    #[cfg(not(feature = "experimental-threads"))]
-    pub(crate) fn from_cell(cell_ref: cell::RefMut<'a, T>) -> Self {
-        Self { cell_ref }
-    }
-
-    #[cfg(feature = "experimental-threads")]
-    pub(crate) fn from_cell(cell_ref: sync::RwLockWriteGuard<'a, T>) -> Self {
-        out!("GdMut init: {:?}", std::any::type_name::<T>());
-        Self { cell_ref }
+impl<'a, T: GodotClass> GdMut<'a, T> {
+    pub(crate) fn from_guard(guard: MutGuard<'a, T>) -> Self {
+        Self { guard }
     }
 }
 
-impl<T> Deref for GdMut<'_, T> {
+impl<T: GodotClass> Deref for GdMut<'_, T> {
     type Target = T;
 
     fn deref(&self) -> &T {
-        self.cell_ref.deref()
+        &self.guard
     }
 }
 
-impl<T> DerefMut for GdMut<'_, T> {
+impl<T: GodotClass> DerefMut for GdMut<'_, T> {
     fn deref_mut(&mut self) -> &mut T {
-        self.cell_ref.deref_mut()
+        &mut self.guard
     }
 }
 
-impl<T> Drop for GdMut<'_, T> {
+impl<T: GodotClass> Drop for GdMut<'_, T> {
     fn drop(&mut self) {
         out!("GdMut drop: {:?}", std::any::type_name::<T>());
     }
diff --git a/godot-core/src/obj/raw.rs b/godot-core/src/obj/raw.rs
index 8af612a4b..5cd65613d 100644
--- a/godot-core/src/obj/raw.rs
+++ b/godot-core/src/obj/raw.rs
@@ -20,7 +20,7 @@ use crate::obj::mem::Memory as _;
 use crate::obj::rtti::ObjectRtti;
 use crate::obj::GdDerefTarget;
 use crate::obj::{dom, GdMut, GdRef, GodotClass, InstanceId};
-use crate::storage::InstanceStorage;
+use crate::storage::{InstanceStorage, Storage};
 use crate::{engine, out};
 
 /// Low-level bindings for object pointers in Godot.
@@ -305,7 +305,7 @@ where
     // Note: possible names: write/read, hold/hold_mut, r/w, r/rw, ...
     pub(crate) fn bind(&self) -> GdRef<T> {
         self.check_rtti("bind");
-        GdRef::from_cell(self.storage().unwrap().get())
+        GdRef::from_guard(self.storage().unwrap().get())
     }
 
     /// Hands out a guard for an exclusive borrow, through which the user instance can be read and written.
@@ -313,7 +313,7 @@ where
     /// See [`crate::obj::Gd::bind_mut()`] for a more in depth explanation.
     pub(crate) fn bind_mut(&mut self) -> GdMut<T> {
         self.check_rtti("bind_mut");
-        GdMut::from_cell(self.storage().unwrap().get_mut())
+        GdMut::from_guard(self.storage().unwrap().get_mut())
     }
 
     /// Storage object associated with the extension instance.
diff --git a/godot-core/src/obj/traits.rs b/godot-core/src/obj/traits.rs
index 4e4554de5..14f4cd08d 100644
--- a/godot-core/src/obj/traits.rs
+++ b/godot-core/src/obj/traits.rs
@@ -367,7 +367,10 @@ mod private {
 
 pub mod dom {
     use super::private::Sealed;
-    use crate::obj::{GodotClass, RawGd};
+    use crate::{
+        obj::{GodotClass, RawGd},
+        storage::Storage,
+    };
 
     /// Trait that specifies who declares a given `GodotClass`.
     pub trait Domain: Sealed {
diff --git a/godot-core/src/registry.rs b/godot-core/src/registry.rs
index a186c42ba..b533f562f 100644
--- a/godot-core/src/registry.rs
+++ b/godot-core/src/registry.rs
@@ -508,6 +508,7 @@ pub mod callbacks {
     use super::*;
     use crate::builder::ClassBuilder;
     use crate::obj::Base;
+    use crate::storage::{Storage, StorageRefCounted};
 
     pub unsafe extern "C" fn create<T: cap::GodotDefault>(
         _class_userdata: *mut std::ffi::c_void,
diff --git a/godot-core/src/storage.rs b/godot-core/src/storage.rs
index 7fea885f6..87a83d08a 100644
--- a/godot-core/src/storage.rs
+++ b/godot-core/src/storage.rs
@@ -5,7 +5,9 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use crate::obj::GodotClass;
+use std::ops::{Deref, DerefMut};
+
+use crate::obj::{Base, Gd, GodotClass, Inherits};
 use crate::{godot_error, out};
 use godot_ffi as sys;
 
@@ -16,312 +18,107 @@ pub enum Lifecycle {
     Destroying,
 }
 
-#[cfg(not(feature = "experimental-threads"))]
-pub(crate) use single_threaded::*;
-
-#[cfg(feature = "experimental-threads")]
-pub(crate) use multi_threaded::*;
-
-#[cfg(not(feature = "experimental-threads"))]
-mod single_threaded {
-    use std::any::type_name;
-    use std::cell;
-
-    use crate::obj::{Base, Gd, GodotClass, Inherits};
-    use crate::out;
-
-    use super::Lifecycle;
-
-    /// Manages storage and lifecycle of user's extension class instances.
-    pub struct InstanceStorage<T: GodotClass> {
-        user_instance: cell::RefCell<T>,
-        pub(super) base: Base<T::Base>,
-
-        // Declared after `user_instance`, is dropped last
-        pub(super) lifecycle: cell::Cell<Lifecycle>,
-        godot_ref_count: cell::Cell<u32>,
-    }
-
-    /// For all Godot extension classes
-    impl<T: GodotClass> InstanceStorage<T> {
-        pub fn construct(user_instance: T, base: Base<T::Base>) -> Self {
-            out!("    Storage::construct             <{}>", type_name::<T>());
-
-            Self {
-                user_instance: cell::RefCell::new(user_instance),
-                base,
-                lifecycle: cell::Cell::new(Lifecycle::Alive),
-                godot_ref_count: cell::Cell::new(1),
-            }
-        }
-
-        pub fn is_bound(&self) -> bool {
-            // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
-            self.user_instance.try_borrow_mut().is_err()
-        }
-
-        pub fn get(&self) -> cell::Ref<T> {
-            self.user_instance.try_borrow().unwrap_or_else(|_e| {
-                panic!(
-                    "Gd<T>::bind() failed, already bound; T = {}.\n  \
-                     Make sure there is no &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                    type_name::<T>()
-                )
-            })
-        }
-
-        pub fn get_mut(&self) -> cell::RefMut<T> {
-            self.user_instance.try_borrow_mut().unwrap_or_else(|_e| {
-                panic!(
-                    "Gd<T>::bind_mut() failed, already bound; T = {}.\n  \
-                     Make sure there is no &T or &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                    type_name::<T>()
-                )
-            })
-        }
-
-        pub fn get_gd(&self) -> Gd<T>
-        where
-            T: Inherits<<T as GodotClass>::Base>,
-        {
-            self.base.to_gd().cast()
-        }
-
-        pub(super) fn godot_ref_count(&self) -> u32 {
-            self.godot_ref_count.get()
-        }
+#[cfg_attr(feature = "experimental-threads", allow(dead_code))]
+mod single_threaded;
 
-        pub(crate) fn on_inc_ref(&self) {
-            let refc = self.godot_ref_count.get() + 1;
-            self.godot_ref_count.set(refc);
+#[cfg_attr(not(feature = "experimental-threads"), allow(dead_code))]
+mod multi_threaded;
 
-            out!(
-                "    Storage::on_inc_ref (rc={})     <{}>", // -- {:?}",
-                refc,
-                type_name::<T>(),
-                //self.user_instance
-            );
-        }
-
-        pub(crate) fn on_dec_ref(&self) {
-            let refc = self.godot_ref_count.get() - 1;
-            self.godot_ref_count.set(refc);
-
-            out!(
-                "  | Storage::on_dec_ref (rc={})     <{}>", // -- {:?}",
-                refc,
-                type_name::<T>(),
-                //self.user_instance
-            );
-        }
-    }
-}
+pub trait Storage {
+    type Instance: GodotClass;
+    type RefGuard<'a>: Deref<Target = Self::Instance>
+    where
+        Self: 'a;
+    type MutGuard<'a>: Deref<Target = Self::Instance> + DerefMut
+    where
+        Self: 'a;
 
-#[cfg(feature = "experimental-threads")]
-mod multi_threaded {
-    use std::sync;
-    use std::sync::atomic::{AtomicU32, Ordering};
+    fn construct(
+        user_instance: Self::Instance,
+        base: Base<<Self::Instance as GodotClass>::Base>,
+    ) -> Self;
 
-    use crate::obj::{Base, Gd, GodotClass, Inherits};
-    use crate::out;
+    fn is_bound(&self) -> bool;
 
-    use super::Lifecycle;
+    fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base>;
 
-    pub struct AtomicLifecycle {
-        atomic: AtomicU32,
-    }
+    fn get(&self) -> Self::RefGuard<'_>;
 
-    impl AtomicLifecycle {
-        pub fn new(value: Lifecycle) -> Self {
-            Self {
-                atomic: AtomicU32::new(value as u32),
-            }
-        }
+    fn get_mut(&self) -> Self::MutGuard<'_>;
 
-        pub fn get(&self) -> Lifecycle {
-            match self.atomic.load(Ordering::Relaxed) {
-                0 => Lifecycle::Alive,
-                1 => Lifecycle::Destroying,
-                other => panic!("invalid lifecycle {other}"),
-            }
-        }
+    fn get_lifecycle(&self) -> Lifecycle;
 
-        pub fn set(&self, lifecycle: Lifecycle) {
-            let value = match lifecycle {
-                Lifecycle::Alive => 0,
-                Lifecycle::Destroying => 1,
-            };
+    fn set_lifecycle(&self, lifecycle: Lifecycle);
 
-            self.atomic.store(value, Ordering::Relaxed);
-        }
+    fn get_gd(&self) -> Gd<Self::Instance>
+    where
+        Self::Instance: Inherits<<Self::Instance as GodotClass>::Base>,
+    {
+        self.base().to_gd().cast()
     }
 
-    /// Manages storage and lifecycle of user's extension class instances.
-    pub struct InstanceStorage<T: GodotClass> {
-        user_instance: sync::RwLock<T>,
-        pub(super) base: Base<T::Base>,
-
-        // Declared after `user_instance`, is dropped last
-        pub(super) lifecycle: AtomicLifecycle,
-        godot_ref_count: AtomicU32,
-    }
-
-    /// For all Godot extension classes
-    impl<T: GodotClass> InstanceStorage<T> {
-        pub fn construct(user_instance: T, base: Base<T::Base>) -> Self {
-            out!("    Storage::construct             <{:?}>", base);
-
-            Self {
-                user_instance: sync::RwLock::new(user_instance),
-                base,
-                lifecycle: AtomicLifecycle::new(Lifecycle::Alive),
-                godot_ref_count: AtomicU32::new(1),
-            }
-        }
-
-        pub fn is_bound(&self) -> bool {
-            // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
-            self.write_ignoring_poison().is_none()
-        }
-
-        pub fn get(&self) -> sync::RwLockReadGuard<T> {
-            self.read_ignoring_poison().unwrap_or_else(|| {
-                panic!(
-                    "Gd<T>::bind() failed, already bound; obj = {}.\n  \
-                     Make sure there is no &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                    self.base,
-                )
-            })
-        }
-
-        pub fn get_mut(&self) -> sync::RwLockWriteGuard<T> {
-            self.write_ignoring_poison().unwrap_or_else(|| {
-                panic!(
-                    "Gd<T>::bind_mut() failed, already bound; obj = {}.\n  \
-                     Make sure there is no &T or &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                    self.base,
-                )
-            })
-        }
-
-        pub fn get_gd(&self) -> Gd<T>
-        where
-            T: Inherits<<T as GodotClass>::Base>,
-        {
-            self.base().clone().cast()
-        }
-
-        pub(super) fn godot_ref_count(&self) -> u32 {
-            self.godot_ref_count.load(Ordering::Relaxed)
-        }
-
-        pub(crate) fn on_inc_ref(&self) {
-            self.godot_ref_count.fetch_add(1, Ordering::Relaxed);
-            out!(
-                "    Storage::on_inc_ref (rc={})     <{:?}>",
-                self.godot_ref_count(),
-                self.base,
-            );
-        }
-
-        pub(crate) fn on_dec_ref(&self) {
-            self.godot_ref_count.fetch_sub(1, Ordering::Relaxed);
-            out!(
-                "  | Storage::on_dec_ref (rc={})     <{:?}>",
-                self.godot_ref_count(),
-                self.base,
-            );
-        }
-
-        /// Returns a write guard (even if poisoned), or `None` when the lock is held by another thread.
-        /// This might need adjustment if threads should await locks.
-        #[must_use]
-        fn write_ignoring_poison(&self) -> Option<sync::RwLockWriteGuard<T>> {
-            match self.user_instance.try_write() {
-                Ok(guard) => Some(guard),
-                Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
-                Err(sync::TryLockError::WouldBlock) => None,
-            }
-        }
-
-        /// Returns a read guard (even if poisoned), or `None` when the lock is held by another writing thread.
-        /// This might need adjustment if threads should await locks.
-        #[must_use]
-        fn read_ignoring_poison(&self) -> Option<sync::RwLockReadGuard<T>> {
-            match self.user_instance.try_read() {
-                Ok(guard) => Some(guard),
-                Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
-                Err(sync::TryLockError::WouldBlock) => None,
-            }
-        }
-
-        // fn __static_type_check() {
-        //     enforce_sync::<InstanceStorage<T>>();
-        // }
-    }
-
-    // TODO make InstanceStorage<T> Sync
-    // This type can be accessed concurrently from multiple threads, so it should be Sync. That implies however that T must be Sync too
-    // (and possibly Send, because with `&mut` access, a `T` can be extracted as a value using mem::take() etc.).
-    // Which again means that we need to infest half the codebase with T: Sync + Send bounds, *and* make it all conditional on
-    // `#[cfg(feature = "experimental-threads")]`.
-    //
-    // A better design would be a distinct Gds<T: Sync> pointer, which requires synchronized.
-    // This needs more design on the multi-threading front (#18).
-    //
-    // The following code + __static_type_check() above would make sure that InstanceStorage is Sync.
-    // Make sure storage is Sync in multi-threaded case, as it can be concurrently accessed through aliased Gd<T> pointers.
-    // fn enforce_sync<T: Sync>() {}
-}
-
-impl<T: GodotClass> InstanceStorage<T> {
-    pub fn debug_info(&self) -> String {
+    fn debug_info(&self) -> String {
         // Unlike get_gd(), this doesn't require special trait bounds.
 
-        format!("{:?}", self.base)
+        format!("{:?}", self.base())
     }
 
     #[must_use]
-    pub fn into_raw(self) -> *mut Self {
+    fn into_raw(self) -> *mut Self
+    where
+        Self: Sized,
+    {
         Box::into_raw(Box::new(self))
     }
 
-    pub fn mark_destroyed_by_godot(&self) {
+    fn mark_destroyed_by_godot(&self) {
         out!(
             "    Storage::mark_destroyed_by_godot", // -- {:?}",
                                                     //self.user_instance
         );
-        self.lifecycle.set(Lifecycle::Destroying);
+        self.set_lifecycle(Lifecycle::Destroying);
         out!(
             "    mark;  self={:?}, val={:?}, obj={:?}",
             self as *const _,
-            self.lifecycle.get(),
-            self.base,
+            self.get_lifecycle(),
+            self.base(),
         );
     }
 
     #[inline(always)]
-    pub fn destroyed_by_godot(&self) -> bool {
+    fn destroyed_by_godot(&self) -> bool {
         out!(
             "    is_d;  self={:?}, val={:?}, obj={:?}",
             self as *const _,
-            self.lifecycle.get(),
-            self.base,
+            self.get_lifecycle(),
+            self.base(),
         );
-        matches!(self.lifecycle.get(), Lifecycle::Destroying)
+        matches!(self.get_lifecycle(), Lifecycle::Destroying)
     }
 }
 
+pub(crate) trait StorageRefCounted: Storage {
+    fn godot_ref_count(&self) -> u32;
+
+    fn on_inc_ref(&self);
+
+    fn on_dec_ref(&self);
+}
+
+#[cfg(not(feature = "experimental-threads"))]
+pub type InstanceStorage<T> = single_threaded::InstanceStorage<T>;
+#[cfg(feature = "experimental-threads")]
+pub type InstanceStorage<T> = multi_threaded::InstanceStorage<T>;
+
+pub type RefGuard<'a, T> = <InstanceStorage<T> as Storage>::RefGuard<'a>;
+pub type MutGuard<'a, T> = <InstanceStorage<T> as Storage>::MutGuard<'a>;
+
 impl<T: GodotClass> Drop for InstanceStorage<T> {
     fn drop(&mut self) {
         out!(
             "    Storage::drop (rc={})           <{:?}>",
             self.godot_ref_count(),
-            self.base,
+            self.base(),
         );
         //let _ = mem::take(&mut self.user_instance);
         //out!("    Storage::drop end              <{:?}>", self.base);
diff --git a/godot-core/src/storage/multi_threaded.rs b/godot-core/src/storage/multi_threaded.rs
new file mode 100644
index 000000000..903167dd4
--- /dev/null
+++ b/godot-core/src/storage/multi_threaded.rs
@@ -0,0 +1,173 @@
+use std::sync;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+use crate::obj::{Base, GodotClass};
+use crate::out;
+
+use super::Lifecycle;
+
+pub struct AtomicLifecycle {
+    atomic: AtomicU32,
+}
+
+impl AtomicLifecycle {
+    pub fn new(value: Lifecycle) -> Self {
+        Self {
+            atomic: AtomicU32::new(value as u32),
+        }
+    }
+
+    pub fn get(&self) -> Lifecycle {
+        match self.atomic.load(Ordering::Relaxed) {
+            0 => Lifecycle::Alive,
+            1 => Lifecycle::Destroying,
+            other => panic!("invalid lifecycle {other}"),
+        }
+    }
+
+    pub fn set(&self, lifecycle: Lifecycle) {
+        let value = match lifecycle {
+            Lifecycle::Alive => 0,
+            Lifecycle::Destroying => 1,
+        };
+
+        self.atomic.store(value, Ordering::Relaxed);
+    }
+}
+
+/// Manages storage and lifecycle of user's extension class instances.
+pub struct InstanceStorage<T: GodotClass> {
+    user_instance: sync::RwLock<T>,
+    pub(super) base: Base<T::Base>,
+
+    // Declared after `user_instance`, is dropped last
+    pub(super) lifecycle: AtomicLifecycle,
+    godot_ref_count: AtomicU32,
+}
+
+/// For all Godot extension classes
+impl<T: GodotClass> InstanceStorage<T> {
+    /// Returns a write guard (even if poisoned), or `None` when the lock is held by another thread.
+    /// This might need adjustment if threads should await locks.
+    #[must_use]
+    fn write_ignoring_poison(&self) -> Option<sync::RwLockWriteGuard<T>> {
+        match self.user_instance.try_write() {
+            Ok(guard) => Some(guard),
+            Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
+            Err(sync::TryLockError::WouldBlock) => None,
+        }
+    }
+
+    /// Returns a read guard (even if poisoned), or `None` when the lock is held by another writing thread.
+    /// This might need adjustment if threads should await locks.
+    #[must_use]
+    fn read_ignoring_poison(&self) -> Option<sync::RwLockReadGuard<T>> {
+        match self.user_instance.try_read() {
+            Ok(guard) => Some(guard),
+            Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
+            Err(sync::TryLockError::WouldBlock) => None,
+        }
+    }
+
+    // fn __static_type_check() {
+    //     enforce_sync::<InstanceStorage<T>>();
+    // }
+}
+
+impl<T: GodotClass> super::Storage for InstanceStorage<T> {
+    type Instance = T;
+
+    type RefGuard<'a> = sync::RwLockReadGuard<'a, T>;
+
+    type MutGuard<'a> = sync::RwLockWriteGuard<'a, T>;
+
+    fn construct(
+        user_instance: Self::Instance,
+        base: Base<<Self::Instance as GodotClass>::Base>,
+    ) -> Self {
+        out!("    Storage::construct             <{:?}>", base);
+
+        Self {
+            user_instance: sync::RwLock::new(user_instance),
+            base,
+            lifecycle: AtomicLifecycle::new(Lifecycle::Alive),
+            godot_ref_count: AtomicU32::new(1),
+        }
+    }
+
+    fn is_bound(&self) -> bool {
+        // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
+        self.write_ignoring_poison().is_none()
+    }
+
+    fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base> {
+        &self.base
+    }
+
+    fn get(&self) -> Self::RefGuard<'_> {
+        self.read_ignoring_poison().unwrap_or_else(|| {
+            panic!(
+                "Gd<T>::bind() failed, already bound; obj = {}.\n  \
+                     Make sure there is no &mut T live at the time.\n  \
+                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
+                self.base,
+            )
+        })
+    }
+
+    fn get_mut(&self) -> Self::MutGuard<'_> {
+        self.write_ignoring_poison().unwrap_or_else(|| {
+            panic!(
+                "Gd<T>::bind_mut() failed, already bound; obj = {}.\n  \
+                     Make sure there is no &T or &mut T live at the time.\n  \
+                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
+                self.base,
+            )
+        })
+    }
+
+    fn get_lifecycle(&self) -> Lifecycle {
+        self.lifecycle.get()
+    }
+
+    fn set_lifecycle(&self, lifecycle: Lifecycle) {
+        self.lifecycle.set(lifecycle)
+    }
+}
+
+impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
+    fn godot_ref_count(&self) -> u32 {
+        self.godot_ref_count.load(Ordering::Relaxed)
+    }
+
+    fn on_inc_ref(&self) {
+        self.godot_ref_count.fetch_add(1, Ordering::Relaxed);
+        out!(
+            "    Storage::on_inc_ref (rc={})     <{:?}>",
+            self.godot_ref_count(),
+            self.base,
+        );
+    }
+
+    fn on_dec_ref(&self) {
+        self.godot_ref_count.fetch_sub(1, Ordering::Relaxed);
+        out!(
+            "  | Storage::on_dec_ref (rc={})     <{:?}>",
+            self.godot_ref_count(),
+            self.base,
+        );
+    }
+}
+
+// TODO make InstanceStorage<T> Sync
+// This type can be accessed concurrently from multiple threads, so it should be Sync. That implies however that T must be Sync too
+// (and possibly Send, because with `&mut` access, a `T` can be extracted as a value using mem::take() etc.).
+// Which again means that we need to infest half the codebase with T: Sync + Send bounds, *and* make it all conditional on
+// `#[cfg(feature = "experimental-threads")]`.
+//
+// A better design would be a distinct Gds<T: Sync> pointer, which requires synchronized.
+// This needs more design on the multi-threading front (#18).
+//
+// The following code + __static_type_check() above would make sure that InstanceStorage is Sync.
+// Make sure storage is Sync in multi-threaded case, as it can be concurrently accessed through aliased Gd<T> pointers.
+// fn enforce_sync<T: Sync>() {}
diff --git a/godot-core/src/storage/single_threaded.rs b/godot-core/src/storage/single_threaded.rs
new file mode 100644
index 000000000..48cdcb6db
--- /dev/null
+++ b/godot-core/src/storage/single_threaded.rs
@@ -0,0 +1,107 @@
+use std::any::type_name;
+use std::cell;
+
+use crate::obj::{Base, GodotClass};
+use crate::out;
+
+use super::Lifecycle;
+
+/// Manages storage and lifecycle of user's extension class instances.
+pub struct InstanceStorage<T: GodotClass> {
+    user_instance: cell::RefCell<T>,
+    pub(super) base: Base<T::Base>,
+
+    // Declared after `user_instance`, is dropped last
+    pub(super) lifecycle: cell::Cell<Lifecycle>,
+    godot_ref_count: cell::Cell<u32>,
+}
+
+impl<T: GodotClass> super::Storage for InstanceStorage<T> {
+    type Instance = T;
+
+    type RefGuard<'a> = cell::Ref<'a, T>;
+
+    type MutGuard<'a> = cell::RefMut<'a, T>;
+
+    fn construct(
+        user_instance: Self::Instance,
+        base: Base<<Self::Instance as GodotClass>::Base>,
+    ) -> Self {
+        out!("    Storage::construct             <{}>", type_name::<T>());
+
+        Self {
+            user_instance: cell::RefCell::new(user_instance),
+            base,
+            lifecycle: cell::Cell::new(Lifecycle::Alive),
+            godot_ref_count: cell::Cell::new(1),
+        }
+    }
+
+    fn is_bound(&self) -> bool {
+        // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
+        self.user_instance.try_borrow_mut().is_err()
+    }
+
+    fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base> {
+        &self.base
+    }
+
+    fn get(&self) -> Self::RefGuard<'_> {
+        self.user_instance.try_borrow().unwrap_or_else(|_e| {
+            panic!(
+                "Gd<T>::bind() failed, already bound; T = {}.\n  \
+                     Make sure there is no &mut T live at the time.\n  \
+                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
+                type_name::<T>()
+            )
+        })
+    }
+
+    fn get_mut(&self) -> Self::MutGuard<'_> {
+        self.user_instance.try_borrow_mut().unwrap_or_else(|_e| {
+            panic!(
+                "Gd<T>::bind_mut() failed, already bound; T = {}.\n  \
+                     Make sure there is no &T or &mut T live at the time.\n  \
+                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
+                type_name::<T>()
+            )
+        })
+    }
+
+    fn get_lifecycle(&self) -> Lifecycle {
+        self.lifecycle.get()
+    }
+
+    fn set_lifecycle(&self, lifecycle: Lifecycle) {
+        self.lifecycle.set(lifecycle)
+    }
+}
+impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
+    fn godot_ref_count(&self) -> u32 {
+        self.godot_ref_count.get()
+    }
+
+    fn on_inc_ref(&self) {
+        let refc = self.godot_ref_count.get() + 1;
+        self.godot_ref_count.set(refc);
+
+        out!(
+            "    Storage::on_inc_ref (rc={})     <{}>", // -- {:?}",
+            refc,
+            type_name::<T>(),
+            //self.user_instance
+        );
+    }
+
+    fn on_dec_ref(&self) {
+        let refc = self.godot_ref_count.get() - 1;
+        self.godot_ref_count.set(refc);
+
+        out!(
+            "  | Storage::on_dec_ref (rc={})     <{}>", // -- {:?}",
+            refc,
+            type_name::<T>(),
+            //self.user_instance
+        );
+    }
+}
diff --git a/godot-macros/src/class/data_models/func.rs b/godot-macros/src/class/data_models/func.rs
index 434cc5630..f51d53ded 100644
--- a/godot-macros/src/class/data_models/func.rs
+++ b/godot-macros/src/class/data_models/func.rs
@@ -186,10 +186,10 @@ fn make_forwarding_closure(
 
     let instance_decl = match &signature_info.receiver_type {
         ReceiverType::Ref => quote! {
-            let instance = storage.get();
+            let instance = ::godot::private::Storage::get(storage);
         },
         ReceiverType::Mut => quote! {
-            let mut instance = storage.get_mut();
+            let mut instance = ::godot::private::Storage::get_mut(storage);
         },
         _ => quote! {},
     };
@@ -236,7 +236,7 @@ fn make_forwarding_closure(
                         unsafe { ::godot::private::as_storage::<#class_name>(instance_ptr) };
 
                     #before_method_call
-                    <#class_name>::#method_name(storage.get_gd(), #(#params),*)
+                    <#class_name>::#method_name(::godot::private::Storage::get_gd(storage), #(#params),*)
                 }
             }
         }

From 8d350e6fbdfdc2a6eca8cb49c23ad5b81659e837 Mon Sep 17 00:00:00 2001
From: Lili Zoey Zyli <sayaks1@gmail.com>
Date: Sun, 26 Nov 2023 20:10:03 +0100
Subject: [PATCH 3/7] Add godot-cell Implement reentrant instance storage

---
 .github/workflows/full-ci.yml                 |  25 +
 Cargo.toml                                    |   1 +
 godot-cell/Cargo.toml                         |   7 +
 godot-cell/src/borrow_state.rs                | 649 ++++++++++++++++++
 godot-cell/src/guards.rs                      | 185 +++++
 godot-cell/src/lib.rs                         | 328 +++++++++
 godot-cell/tests/mock.rs                      | 315 +++++++++
 godot-core/Cargo.toml                         |   1 +
 godot-core/src/obj/base.rs                    |   2 +
 godot-core/src/obj/guards.rs                  |  54 +-
 godot-core/src/obj/raw.rs                     |  25 +
 godot-core/src/obj/traits.rs                  | 160 ++++-
 godot-core/src/storage.rs                     | 122 +++-
 godot-core/src/storage/multi_threaded.rs      | 171 ++---
 godot-core/src/storage/single_threaded.rs     |  97 ++-
 godot-macros/src/class/derive_godot_class.rs  |   2 +-
 itest/rust/Cargo.toml                         |   2 +-
 itest/rust/src/object_tests/mod.rs            |   1 +
 itest/rust/src/object_tests/reentrant_test.rs |  82 +++
 19 files changed, 2062 insertions(+), 167 deletions(-)
 create mode 100644 godot-cell/Cargo.toml
 create mode 100644 godot-cell/src/borrow_state.rs
 create mode 100644 godot-cell/src/guards.rs
 create mode 100644 godot-cell/src/lib.rs
 create mode 100644 godot-cell/tests/mock.rs
 create mode 100644 itest/rust/src/object_tests/reentrant_test.rs

diff --git a/.github/workflows/full-ci.yml b/.github/workflows/full-ci.yml
index a76402b76..d84951bdc 100644
--- a/.github/workflows/full-ci.yml
+++ b/.github/workflows/full-ci.yml
@@ -154,6 +154,31 @@ jobs:
         run: cargo test $GDEXT_FEATURES ${{ matrix.rust-extra-args }}
 
 
+  miri-test:
+    name: miri-test
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: "Install Rust"
+        uses: ./.github/composite/rust
+      
+      - name: "Install Miri"
+        run: |
+          rustup toolchain install nightly --component miri
+          rustup override set nightly
+          cargo miri setup
+
+      - name: "Compile tests"
+        run: cargo +nightly miri test -p godot-cell --no-run
+
+      - name: "Test stacked borrows"
+        run: cargo +nightly miri test -p godot-cell
+      
+      - name: "Test tree borrows"
+        run: MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test -p godot-cell
+
+
   # For complex matrix workflow, see https://stackoverflow.com/a/65434401
   godot-itest:
     name: godot-itest (${{ matrix.name }})
diff --git a/Cargo.toml b/Cargo.toml
index 013295caa..9a406597f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -6,6 +6,7 @@ members = [
     "godot-ffi",
     "godot-core",
     "godot-macros",
+    "godot-cell",
     "godot",
 
     # Godot integration
diff --git a/godot-cell/Cargo.toml b/godot-cell/Cargo.toml
new file mode 100644
index 000000000..2cb8aebb5
--- /dev/null
+++ b/godot-cell/Cargo.toml
@@ -0,0 +1,7 @@
+[package]
+name = "godot-cell"
+version = "0.1.0"
+edition = "2021"
+
+[dev-dependencies]
+proptest = "1.4.0"
diff --git a/godot-cell/src/borrow_state.rs b/godot-cell/src/borrow_state.rs
new file mode 100644
index 000000000..fa549ad37
--- /dev/null
+++ b/godot-cell/src/borrow_state.rs
@@ -0,0 +1,649 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+/// A type that tracks the state of borrows for a [`GdCell`].
+///
+/// This state upholds these invariants:
+/// - You can only take a shared borrow when there is no aliasing mutable borrow.
+/// - You can only take a mutable borrow when there is neither an aliasing mutable borrow, nor a shared
+/// borrow.
+/// - You can only set a mutable borrow as non-aliasing when an aliasing mutable borrow exists.
+/// - You can only unset a mutable borrow as non-aliasing when there is no aliasing mutable borrow and no
+/// shared borrows.  
+///
+/// If a catastrophic error occurs, then the state will be poisoned. If the state is poisoned then that's
+/// almost certainly an implementation bug, and should never happen. But in an abundance of caution it is
+/// included to be safe.
+#[derive(Debug, Clone, PartialEq)]
+pub struct BorrowState {
+    /// The number of `&T` references that are tracked.
+    shared_count: usize,
+    /// The number of `&mut T` references that are tracked.
+    mut_count: usize,
+    /// The number of `&mut T` references that cannot be aliased.
+    non_aliasing_count: usize,
+    /// `true` if the borrow state has reached an erroneous or unreliable state.
+    poisoned: bool,
+}
+
+impl BorrowState {
+    /// Create a new borrow state representing no borrows.
+    pub fn new() -> Self {
+        Self {
+            shared_count: 0,
+            mut_count: 0,
+            non_aliasing_count: 0,
+            poisoned: false,
+        }
+    }
+
+    /// Returns `true` if there may be an aliasing mutable reference.
+    pub fn has_possibly_aliasing(&self) -> bool {
+        let count = self.mut_count - self.non_aliasing_count;
+
+        assert!(
+            count <= 1,
+            "there should never be more than 1 aliasing reference"
+        );
+
+        count == 1
+    }
+
+    /// Returns the number of tracked shared references.
+    ///
+    /// Any amount of shared references will prevent [`Self::increment_mut`] from succeeding.
+    pub fn shared_count(&self) -> usize {
+        self.shared_count
+    }
+
+    /// Returns the number of tracked mutable references.
+    pub fn mut_count(&self) -> usize {
+        self.mut_count
+    }
+
+    /// Returns `true` if the state has reached an erroneous or unreliable state.
+    pub fn is_poisoned(&self) -> bool {
+        self.poisoned
+    }
+
+    /// Set self as having reached an erroneous or unreliable state.
+    ///
+    /// Always returns [`BorrowStateErr::Poisoned`].
+    fn poison(&mut self, err: impl Into<String>) -> Result<(), BorrowStateErr> {
+        self.poisoned = true;
+
+        Err(BorrowStateErr::Poisoned(err.into()))
+    }
+
+    fn ensure_not_poisoned(&self) -> Result<(), BorrowStateErr> {
+        if self.is_poisoned() {
+            return Err(BorrowStateErr::IsPoisoned);
+        }
+
+        Ok(())
+    }
+
+    fn ensure_can_ref(&self) -> Result<(), BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        if self.has_possibly_aliasing() {
+            return Err("cannot borrow while possibly aliasing borrow exists".into());
+        }
+
+        Ok(())
+    }
+
+    fn ensure_can_mut_ref(&self) -> Result<(), BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        if self.has_possibly_aliasing() {
+            return Err("cannot borrow while possibly aliasing borrow exists".into());
+        }
+
+        if self.shared_count != 0 {
+            return Err("cannot borrow mutable while shared borrow exists".into());
+        }
+
+        Ok(())
+    }
+
+    /// Track a new shared reference.
+    ///
+    /// Returns the new total number of shared references.
+    ///
+    /// This fails when:
+    /// - There exists a possibly aliasing mutable reference.
+    /// - There exist `usize::MAX` shared references.
+    pub fn increment_shared(&mut self) -> Result<usize, BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        self.ensure_can_ref()?;
+
+        self.shared_count = self
+            .shared_count
+            .checked_add(1)
+            .ok_or("could not increment shared count")?;
+
+        Ok(self.shared_count)
+    }
+
+    /// Untrack an existing shared reference.
+    ///
+    /// Returns the new total number of shared references.
+    ///
+    /// This fails when:
+    /// - There are currently no tracked shared references.
+    pub fn decrement_shared(&mut self) -> Result<usize, BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        if self.shared_count == 0 {
+            return Err("cannot decrement shared counter when no shared reference exists".into());
+        }
+
+        if self.has_possibly_aliasing() {
+            self.poison("shared reference tracked while aliasing mutable reference exists")?;
+        }
+
+        // We know `shared_count` isn't 0.
+        self.shared_count -= 1;
+
+        Ok(self.shared_count)
+    }
+
+    /// Track a new mutable reference.
+    ///
+    /// Returns the new total number of mutable references.
+    ///
+    /// This fails when:
+    /// - There exists a possibly aliasing mutable reference.
+    /// - There exists a shared reference.
+    /// - There are `usize::MAX` tracked mutable references.
+    ///
+    /// Any amount of shared references will prevent [`Self::increment_non_aliasing`] from succeeding.
+    pub fn increment_mut(&mut self) -> Result<usize, BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        self.ensure_can_mut_ref()?;
+
+        self.mut_count = self
+            .mut_count
+            .checked_add(1)
+            .ok_or("could not increment mut count")?;
+
+        Ok(self.mut_count)
+    }
+
+    /// Untrack an existing mutable reference.
+    ///
+    /// Returns the new total number of mutable references.
+    ///
+    /// This fails when:
+    /// - There are currently no mutable references.
+    /// - There is a mutable reference, but it's guaranteed to be non-aliasing.
+    pub fn decrement_mut(&mut self) -> Result<usize, BorrowStateErr> {
+        self.ensure_not_poisoned()?;
+
+        if self.mut_count == 0 {
+            return Err("cannot decrement mutable counter when no mutable reference exists".into());
+        }
+
+        if self.mut_count == self.non_aliasing_count {
+            return Err(
+                "cannot decrement mutable counter when current mutable reference is non-aliasing"
+                    .into(),
+            );
+        }
+
+        if self.mut_count - 1 != self.non_aliasing_count {
+            self.poison("`non_aliasing_count` does not fit its invariant")?;
+        }
+
+        // We know `mut_count` isn't 0.
+        self.mut_count -= 1;
+
+        Ok(self.mut_count)
+    }
+
+    /// Set the current mutable reference as non-aliasing.
+    ///
+    /// Returns the new total of non-aliasing mutable references.
+    ///
+    /// Fails when:
+    /// - There is no current
+    pub fn set_non_aliasing(&mut self) -> Result<usize, BorrowStateErr> {
+        if !self.has_possibly_aliasing() {
+            return Err(
+                "cannot set current reference as non-aliasing when no possibly aliasing reference exists"
+                    .into(),
+            );
+        }
+
+        self.non_aliasing_count = self
+            .non_aliasing_count
+            .checked_add(1)
+            .ok_or("could not increment non-aliasing count")?;
+
+        Ok(self.non_aliasing_count)
+    }
+
+    pub fn unset_non_aliasing(&mut self) -> Result<usize, BorrowStateErr> {
+        if self.has_possibly_aliasing() {
+            return Err("cannot set current reference as possibly aliasing when possibly aliasing reference already exists".into());
+        }
+
+        if self.shared_count() > 0 {
+            return Err(
+                "cannot set current reference as possibly aliasing when a shared reference exists"
+                    .into(),
+            );
+        }
+
+        if self.non_aliasing_count == 0 {
+            return Err(
+                "cannot mark mut pointer as aliasing when there are no possibly aliasing pointers"
+                    .into(),
+            );
+        }
+
+        self.non_aliasing_count = self
+            .non_aliasing_count
+            .checked_sub(1)
+            .ok_or("could not decrement non-aliasing count")?;
+
+        Ok(self.non_aliasing_count)
+    }
+}
+
+impl Default for BorrowState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BorrowStateErr {
+    Poisoned(String),
+    IsPoisoned,
+    Custom(String),
+}
+
+impl std::fmt::Display for BorrowStateErr {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            BorrowStateErr::Poisoned(err) => write!(f, "the borrow state was poisoned: {err}"),
+            BorrowStateErr::IsPoisoned => write!(f, "the borrow state is poisoned"),
+            BorrowStateErr::Custom(err) => f.write_str(err),
+        }
+    }
+}
+
+impl std::error::Error for BorrowStateErr {}
+
+impl<'a> From<&'a str> for BorrowStateErr {
+    fn from(value: &'a str) -> Self {
+        Self::Custom(value.into())
+    }
+}
+
+impl From<String> for BorrowStateErr {
+    fn from(value: String) -> Self {
+        Self::Custom(value)
+    }
+}
+
+#[cfg(all(test, not(miri)))]
+mod test {
+    use super::*;
+    use proptest::{arbitrary::Arbitrary, collection::vec, prelude::*};
+
+    impl BorrowState {
+        fn has_shared_reference(&self) -> bool {
+            self.shared_count > 0
+        }
+    }
+
+    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+    enum Operation {
+        IncShared,
+        DecShared,
+        IncMut,
+        DecMut,
+        SetNoAlias,
+        UnsetNoAlias,
+    }
+
+    impl Operation {
+        fn execute(&self, state: &mut BorrowState) -> Result<(), BorrowStateErr> {
+            use Operation as Op;
+
+            let result = match self {
+                Op::IncShared => state.increment_shared(),
+                Op::DecShared => state.decrement_shared(),
+                Op::IncMut => state.increment_mut(),
+                Op::DecMut => state.decrement_mut(),
+                Op::SetNoAlias => state.set_non_aliasing(),
+                Op::UnsetNoAlias => state.unset_non_aliasing(),
+            };
+
+            result.map(|_| ())
+        }
+    }
+
+    prop_compose! {
+        fn arbitrary_op()(id in 0..6) -> Operation {
+            use Operation as Op;
+
+            match id {
+                0 => Op::IncShared,
+                1 => Op::DecShared,
+                2 => Op::IncMut,
+                3 => Op::DecMut,
+                4 => Op::SetNoAlias,
+                5 => Op::UnsetNoAlias,
+                _ => unreachable!()
+            }
+        }
+    }
+
+    impl Arbitrary for Operation {
+        type Parameters = ();
+
+        type Strategy = BoxedStrategy<Self>;
+
+        fn arbitrary_with(_: Self::Parameters) -> Self::Strategy {
+            Strategy::boxed(arbitrary_op())
+        }
+    }
+
+    #[derive(Debug, Clone, PartialEq, Eq)]
+    struct OperationExecutor {
+        vec: Vec<Operation>,
+    }
+
+    impl OperationExecutor {
+        fn execute_all(&self, state: &mut BorrowState) {
+            for op in self.vec.iter() {
+                _ = op.execute(state);
+            }
+        }
+
+        fn remove_shared_inc_dec_pairs(mut self) -> Self {
+            loop {
+                let mut inc_index = None;
+                let mut just_saw_inc = false;
+
+                for (i, op) in self.vec.iter().enumerate() {
+                    match op {
+                        Operation::IncShared => just_saw_inc = true,
+                        Operation::DecShared if just_saw_inc => {
+                            inc_index = Some(i - 1);
+                            break;
+                        }
+                        _ => just_saw_inc = false,
+                    }
+                }
+
+                match inc_index {
+                    Some(i) => {
+                        self.vec.remove(i + 1);
+                        self.vec.remove(i);
+                    }
+                    None => break,
+                }
+            }
+
+            self
+        }
+    }
+
+    impl From<Vec<Operation>> for OperationExecutor {
+        fn from(vec: Vec<Operation>) -> Self {
+            Self { vec }
+        }
+    }
+
+    prop_compose! {
+        fn arbitrary_ops(max_len: usize)(len in 0..max_len)(operations in vec(any::<Operation>(), len)) -> Vec<Operation> {
+            operations
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn operations_do_only_whats_expected_or_nothing(operations in arbitrary_ops(50)) {
+            use Operation as Op;
+            let mut state = BorrowState::new();
+            for op in operations {
+                let expected_on_success = match op {
+                    Op::IncShared => |mut original: BorrowState| {
+                        original.shared_count += 1;
+                        original
+                    },
+                    Op::DecShared => |mut original: BorrowState| {
+                        original.shared_count -= 1;
+                        original
+                    },
+                    Op::IncMut => |mut original: BorrowState| {
+                        original.mut_count += 1;
+                        original
+                    },
+                    Op::DecMut => |mut original: BorrowState| {
+                        original.mut_count -= 1;
+                        original
+                    },
+                    Op::SetNoAlias => |mut original: BorrowState| {
+                        original.non_aliasing_count += 1;
+                        original
+                    },
+                    Op::UnsetNoAlias => |mut original: BorrowState| {
+                        original.non_aliasing_count -= 1;
+                        original
+                    },
+                };
+
+                let original = state.clone();
+                if op.execute(&mut state).is_ok() {
+                    assert_eq!(state, expected_on_success(original));
+                } else {
+                    assert_eq!(state, original);
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn no_poison(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+            for op in operations {
+                if let Err(err) = op.execute(&mut state) {
+                    assert_ne!(err, BorrowStateErr::IsPoisoned);
+                    assert!(!matches!(err, BorrowStateErr::Poisoned(_)));
+                }
+
+                assert!(!state.is_poisoned());
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn no_shared_and_mut(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_shared_reference() {
+                    assert!(!state.has_possibly_aliasing())
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn can_borrow_shared_when_borrowed_shared(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_shared_reference() {
+                    assert!(state.increment_shared().is_ok());
+                    assert!(state.decrement_shared().is_ok());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn cannot_borrow_shared_when_borrowed_aliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_possibly_aliasing() {
+                    assert!(state.increment_shared().is_err());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn can_borrow_shared_when_not_borrowed_aliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if !state.has_possibly_aliasing() {
+                    assert!(state.increment_shared().is_ok());
+                    assert!(state.decrement_shared().is_ok());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn can_borrow_mut_when_no_shared_and_no_aliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if !state.has_possibly_aliasing() && !state.has_shared_reference() {
+                    assert!(state.increment_mut().is_ok());
+                    assert!(state.decrement_mut().is_ok());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn cannot_borrow_mut_when_shared(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_shared_reference() {
+                    assert!(state.increment_mut().is_err());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn cannot_borrow_mut_when_has_aliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_possibly_aliasing() {
+                    assert!(state.increment_mut().is_err());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn can_set_nonaliasing_when_aliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_possibly_aliasing() {
+                    assert!(state.set_non_aliasing().is_ok());
+                    assert!(state.unset_non_aliasing().is_ok());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn cannot_set_nonaliasing_when_shared(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if state.has_shared_reference() {
+                    assert!(state.set_non_aliasing().is_err());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn cannot_set_nonaliasing_when_nonaliasing(operations in arbitrary_ops(50)) {
+            let mut state = BorrowState::new();
+
+            for op in operations {
+                _ = op.execute(&mut state);
+                if !state.has_possibly_aliasing() {
+                    assert!(state.set_non_aliasing().is_err());
+                }
+            }
+        }
+    }
+
+    proptest! {
+        #[test]
+        fn remove_shared_inc_dec_pairs_is_noop(operations in arbitrary_ops(50)) {
+            let mut state_all = BorrowState::new();
+            let executor_all = OperationExecutor::from(operations);
+            executor_all.execute_all(&mut state_all);
+
+            let mut state_no_shared_pairs = BorrowState::new();
+            let executor_no_shared_pairs = executor_all.clone().remove_shared_inc_dec_pairs();
+            executor_no_shared_pairs.execute_all(&mut state_no_shared_pairs);
+
+            assert_eq!(state_all, state_no_shared_pairs);
+        }
+    }
+
+    #[test]
+    fn poisoned_unset_shared_ref() {
+        let mut state = BorrowState::new();
+        assert!(!state.is_poisoned());
+
+        _ = state.increment_mut();
+        assert!(!state.is_poisoned());
+        _ = state.set_non_aliasing();
+        assert!(!state.is_poisoned());
+        _ = state.increment_shared();
+        assert!(!state.is_poisoned());
+        _ = state.unset_non_aliasing();
+        assert!(!state.is_poisoned());
+        _ = state.increment_shared();
+        assert!(!state.is_poisoned());
+        _ = state.decrement_shared();
+        assert!(!state.is_poisoned());
+    }
+}
diff --git a/godot-cell/src/guards.rs b/godot-cell/src/guards.rs
new file mode 100644
index 000000000..2c77f2ff9
--- /dev/null
+++ b/godot-cell/src/guards.rs
@@ -0,0 +1,185 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use std::ops::{Deref, DerefMut};
+use std::ptr::NonNull;
+use std::sync::Mutex;
+
+use crate::CellState;
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Wraps a shared borrowed value of type `T`.
+///
+/// No other mutable borrows to the same value will be created while this guard exists.
+#[derive(Debug)]
+pub struct RefGuard<'a, T> {
+    state: &'a Mutex<CellState<T>>,
+    value: NonNull<T>,
+}
+
+impl<'a, T> RefGuard<'a, T> {
+    /// Create a new `GdRef` guard which can be immutably dereferenced.
+    ///
+    /// # Safety
+    ///
+    /// It must be safe to call [`as_ref()`](NonNull::as_ref) on `value` for as long as the guard is not
+    /// dropped.
+    ///
+    /// In particular you must ensure that:
+    ///
+    /// - The value behind the `value` pointer must be accessible for as long as the guard is not dropped.
+    /// - No new mutable references to the same value can be created.
+    /// - If there exist any other mutable references, then `value` must be derived from those references.
+    /// - Any existing mutable references must stop accessing this value while this guard exists.
+    pub(crate) unsafe fn new(state: &'a Mutex<CellState<T>>, value: NonNull<T>) -> Self {
+        Self { state, value }
+    }
+}
+
+impl<'a, T> Deref for RefGuard<'a, T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: It is safe to call `as_ref()` on value because of the safety invariants of `new`.
+        unsafe { self.value.as_ref() }
+    }
+}
+
+impl<'a, T> Drop for RefGuard<'a, T> {
+    fn drop(&mut self) {
+        self.state
+            .lock()
+            .unwrap()
+            .borrow_state
+            .decrement_shared()
+            .unwrap();
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Wraps a mutably borrowed value of type `T`.
+///
+/// This prevents all other borrows of `value`, unless the `&mut` reference handed out from this guard is set
+/// as non-aliasing by a call to [`GdCell::set_non_aliasing()`](crate::GdCell::set_non_aliasing).
+#[derive(Debug)]
+pub struct MutGuard<'a, T> {
+    state: &'a Mutex<CellState<T>>,
+    count: usize,
+    value: NonNull<T>,
+}
+
+impl<'a, T> MutGuard<'a, T> {
+    /// Create a new `GdMut` guard which can be mutably dereferenced.
+    ///
+    /// # Safety
+    ///
+    /// For as long as the guard lives:
+    ///
+    /// - It must be safe to call [`as_ref()`](NonNull::as_ref) on `value` when you have a shared reference to
+    ///   the guard.
+    /// - It must be safe to call [`as_mut()`](NonNull::as_mut) on `value` when you have a mutable reference
+    ///   to the guard.
+    ///
+    /// In particular you must ensure that until the guard is set as non-aliasing via a call to
+    /// [`GdCell::set_non_aliasing()`](crate::GdCell::set_non_aliasing), then:
+    ///
+    /// - The value behind the `value` pointer must be accessible for as long as the guard is not dropped.
+    /// - No new references to `value` may be created.
+    /// - If there exist any other mutable references, then `value` must be derived from those references.
+    /// - Any existing mutable references must stop accessing this value while this guard exists.
+    ///
+    /// When the guard is set as non-aliasing, then:
+    ///
+    /// - Any references handed out by this guard must stop accessing the value.
+    ///
+    /// This can be satisfied by using `deref_mut` to get a `&mut T` to the value, then making that reference
+    /// inaccessible for the duration that this guard is marked as non-aliasing. As the rust borrow checker
+    /// will prevent anyone from then using this guard until that reference is dropped.
+    pub(crate) unsafe fn new(
+        state: &'a Mutex<CellState<T>>,
+        count: usize,
+        value: NonNull<T>,
+    ) -> Self {
+        Self {
+            state,
+            count,
+            value,
+        }
+    }
+}
+
+impl<'a, T> Deref for MutGuard<'a, T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        let count = self.state.lock().unwrap().borrow_state.mut_count();
+        // This is just a best-effort error check. It should never be triggered.
+        assert_eq!(
+            self.count, count,
+            "attempted to access the non-current mutable borrow. **this is a bug, please report it**"
+        );
+        // SAFETY:
+        // It is safe to call `as_ref()` on value when we have a `&self` reference because of the safety
+        // invariants of `new`.
+        unsafe { self.value.as_ref() }
+    }
+}
+
+impl<'a, T> DerefMut for MutGuard<'a, T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        let count = self.state.lock().unwrap().borrow_state.mut_count();
+        // This is just a best-effort error check. It should never be triggered.
+        assert_eq!(
+            self.count, count,
+            "attempted to access the non-current mutable borrow. **this is a bug, please report it**"
+        );
+
+        // SAFETY:
+        // It is safe to call `as_mut()` on value when we have a `&mut self` reference because of the safety
+        // invariants of `new`.
+        unsafe { self.value.as_mut() }
+    }
+}
+
+impl<'a, T> Drop for MutGuard<'a, T> {
+    fn drop(&mut self) {
+        self.state
+            .lock()
+            .unwrap()
+            .borrow_state
+            .decrement_mut()
+            .unwrap();
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// A guard that ensures a mutable reference is kept inaccessible until it is dropped. At which point the
+/// borrow-state is set to prevent aliasing for the most recent borrow and the pointer in state is set to the
+/// previous pointer.
+#[derive(Debug)]
+pub struct NonAliasingGuard<'a, T> {
+    state: &'a Mutex<CellState<T>>,
+    prev_ptr: NonNull<T>,
+}
+
+impl<'a, T> NonAliasingGuard<'a, T> {
+    /// Create a new non-aliasing guard for `state`.
+    pub(crate) fn new(state: &'a Mutex<CellState<T>>, prev_ptr: NonNull<T>) -> Self {
+        Self { state, prev_ptr }
+    }
+}
+
+impl<'a, T> Drop for NonAliasingGuard<'a, T> {
+    fn drop(&mut self) {
+        let mut state = self.state.lock().unwrap();
+        state.borrow_state.unset_non_aliasing().unwrap();
+        state.set_ptr(self.prev_ptr);
+    }
+}
diff --git a/godot-cell/src/lib.rs b/godot-cell/src/lib.rs
new file mode 100644
index 000000000..2f9ec9e5d
--- /dev/null
+++ b/godot-cell/src/lib.rs
@@ -0,0 +1,328 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+//! A re-entrant cell implementation which allows for `&mut` references to be re-taken even while `&mut`
+//! references still exist.
+//!
+//! This is done by ensuring any existing `&mut` references cannot alias the new reference, and that the new
+//! reference is derived from the previous one.
+
+mod borrow_state;
+mod guards;
+
+use std::cell::UnsafeCell;
+use std::error::Error;
+use std::marker::PhantomPinned;
+use std::pin::Pin;
+use std::ptr::NonNull;
+use std::sync::Mutex;
+
+use borrow_state::BorrowState;
+pub use guards::{MutGuard, NonAliasingGuard, RefGuard};
+
+/// A cell which can hand out new `&mut` references to it's value even when one already exists, as long as
+/// any pre-existing such references have been handed back to the cell first, and no shared references exist.
+///
+/// This cell must be pinned to be usable, as it stores self-referential pointers.
+// TODO: consider not using `Mutex`
+#[derive(Debug)]
+pub struct GdCell<T> {
+    /// The mutable state of this cell.
+    state: Mutex<CellState<T>>,
+    /// The actual value we're handing out references to, uses `UnsafeCell` as we're passing out `&mut`
+    /// references to its contents even when we only have a `&` reference to the cell.
+    value: UnsafeCell<T>,
+    /// We dont want to be able to take `GdCell` out of a pin, so `GdCell` cannot implement `Unpin`.
+    _pin: PhantomPinned,
+}
+
+impl<T> GdCell<T> {
+    /// Creates a new cell storing `value`.
+    pub fn new(value: T) -> Pin<Box<Self>> {
+        let cell = Box::pin(Self {
+            state: Mutex::new(CellState::new()),
+            value: UnsafeCell::new(value),
+            _pin: PhantomPinned,
+        });
+
+        cell.state.lock().unwrap().initialize_ptr(&cell.value);
+
+        cell
+    }
+
+    /// Returns a new shared reference to the contents of the cell.
+    ///
+    /// Fails if an aliasing mutable reference exists.
+    pub fn borrow(self: Pin<&Self>) -> Result<RefGuard<'_, T>, Box<dyn Error>> {
+        let mut state = self.state.lock().unwrap();
+        state.borrow_state.increment_shared()?;
+
+        // SAFETY:
+        // `increment_shared` succeeded, therefore there cannot currently be any aliasing mutable references.
+        unsafe { Ok(RefGuard::new(&self.get_ref().state, state.get_ptr())) }
+    }
+
+    /// Returns a new shared reference to the contents of the cell.
+    ///
+    /// Fails if an aliasing mutable reference exists, or a shared reference exists.
+    pub fn borrow_mut(self: Pin<&Self>) -> Result<MutGuard<'_, T>, Box<dyn Error>> {
+        let mut state = self.state.lock().unwrap();
+        state.borrow_state.increment_mut()?;
+        let count = state.borrow_state.mut_count();
+        let value = state.get_ptr();
+
+        // SAFETY:
+        // `increment_mut` succeeded, therefore any existing mutable references do not alias, and no new
+        // references may be made unless this one is guaranteed not to alias those.
+        //
+        // This is the case because the only way for a new `GdMut` or `GdRef` to be made after this, is for
+        // either this guard to be dropped or `set_non_aliasing` to be called.
+        //
+        // If this guard is dropped, then we dont need to worry.
+        //
+        // If `set_non_aliasing` is called, then either a mutable reference from this guard is passed in.
+        // In which case, we cannot use this guard again until the resulting non-aliasing guard is dropped.
+        //
+        // We cannot pass in a different mutable reference, since `set_non_aliasing` ensures any references
+        // matches the ones this one would return. And only one mutable reference to the same value can exist
+        // since we cannot have any other aliasing mutable references around to pass in.
+        unsafe { Ok(MutGuard::new(&self.get_ref().state, count, value)) }
+    }
+
+    /// Set the current mutable borrow as not aliasing any other references.
+    ///
+    /// Will error if there is no current possibly aliasing mutable borrow, or if there are any shared
+    /// references.
+    pub fn set_non_aliasing<'a, 'b>(
+        self: Pin<&'a Self>,
+        current_ref: &'b mut T,
+    ) -> Result<NonAliasingGuard<'b, T>, Box<dyn Error>>
+    where
+        'a: 'b,
+    {
+        let mut state = self.state.lock().unwrap();
+        let current_ptr = state.get_ptr();
+        let ptr = NonNull::from(current_ref);
+
+        if current_ptr != ptr {
+            // it is likely not unsound for this to happen, but it's unexpected
+            return Err("wrong reference passed in".into());
+        }
+
+        state.borrow_state.set_non_aliasing()?;
+        let old_ptr = state.get_ptr();
+        state.set_ptr(ptr);
+
+        Ok(NonAliasingGuard::new(&self.get_ref().state, old_ptr))
+    }
+
+    /// Returns `true` if there are any mutable or shared references, regardless of whether the mutable
+    /// references are aliasing or not.
+    ///
+    /// In particular this means that it is safe to destroy this cell and the value contained within, as no
+    /// references can exist that can reference this cell.
+    ///
+    /// Keep in mind that in multithreaded code it is still possible for this to return true, and then the
+    /// cell hands out a new borrow before it is destroyed. So we still need to ensure that this cannot
+    /// happen at the same time.
+    pub fn is_currently_bound(self: Pin<&Self>) -> bool {
+        let state = self.state.lock().unwrap();
+
+        state.borrow_state.shared_count() > 0 || state.borrow_state.mut_count() > 0
+    }
+}
+
+// SAFETY:
+// `T` is sync so we can return references to it on different threads.
+// Additionally all internal state is synchronized via a mutex, so we wont have race conditions when trying
+// to use it from multiple threads.
+unsafe impl<T: Sync> Sync for GdCell<T> {}
+
+/// Mutable state of the `GdCell`, bundled together to make it easier to avoid deadlocks when locking the
+/// mutex.
+#[derive(Debug)]
+struct CellState<T> {
+    /// Tracking the borrows this cell has. This ensures relevant invariants are upheld.
+    borrow_state: BorrowState,
+    /// Current pointer to the value.
+    ///
+    /// This is initialized upon first usage, as we cannot construct the cell pinned in general.
+    ///
+    /// When a reference is handed to a cell to enable re-entrancy, then this pointer is set to that
+    /// reference.
+    ///
+    /// We always generate new pointer based off of the reference currently in this field, to ensure any new
+    /// references are derived from the most recent `&mut` reference.
+    ptr: Option<NonNull<T>>,
+}
+
+impl<T> CellState<T> {
+    /// Create a new uninitialized state. Use [`initialize_ptr()`](CellState::initialize_ptr()) to initialize
+    /// it.
+    fn new() -> Self {
+        Self {
+            borrow_state: BorrowState::new(),
+            ptr: None,
+        }
+    }
+
+    /// Initialize the pointer if it is `None`.
+    fn initialize_ptr(&mut self, value: &UnsafeCell<T>) {
+        if self.ptr.is_none() {
+            self.set_ptr(NonNull::new(value.get()).unwrap());
+        } else {
+            panic!("Cannot initialize pointer as it is already initialized.")
+        }
+    }
+
+    /// Returns the current pointer. Panics if uninitialized.
+    fn get_ptr(&self) -> NonNull<T> {
+        self.ptr.unwrap()
+    }
+
+    /// Set the current pointer to the new pointer.
+    fn set_ptr(&mut self, new_ptr: NonNull<T>) {
+        self.ptr = Some(new_ptr);
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn prevent_mut_mut() {
+        const VAL: i32 = -451431556;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+        let guard1 = cell.borrow_mut().unwrap();
+        let guard2 = cell.borrow_mut();
+
+        assert_eq!(*guard1, VAL);
+        assert!(guard2.is_err());
+        std::mem::drop(guard1);
+    }
+
+    #[test]
+    fn prevent_mut_shared() {
+        const VAL: i32 = 13512;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+        let guard1 = cell.borrow_mut().unwrap();
+        let guard2 = cell.borrow();
+
+        assert_eq!(*guard1, VAL);
+        assert!(guard2.is_err());
+        std::mem::drop(guard1);
+    }
+
+    #[test]
+    fn prevent_shared_mut() {
+        const VAL: i32 = 99;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+        let guard1 = cell.borrow().unwrap();
+        let guard2 = cell.borrow_mut();
+
+        assert_eq!(*guard1, VAL);
+        assert!(guard2.is_err());
+        std::mem::drop(guard1);
+    }
+
+    #[test]
+    fn allow_shared_shared() {
+        const VAL: i32 = 10;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+        let guard1 = cell.borrow().unwrap();
+        let guard2 = cell.borrow().unwrap();
+
+        assert_eq!(*guard1, VAL);
+        assert_eq!(*guard2, VAL);
+        std::mem::drop(guard1);
+    }
+
+    #[test]
+    fn allow_non_aliasing_mut_mut() {
+        const VAL: i32 = 23456;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+
+        let mut guard1 = cell.borrow_mut().unwrap();
+        let mut1 = &mut *guard1;
+        assert_eq!(*mut1, VAL);
+        *mut1 = VAL + 50;
+
+        let no_alias_guard = cell.set_non_aliasing(mut1).unwrap();
+
+        let mut guard2 = cell.borrow_mut().unwrap();
+        let mut2 = &mut *guard2;
+        assert_eq!(*mut2, VAL + 50);
+        *mut2 = VAL - 30;
+        drop(guard2);
+
+        drop(no_alias_guard);
+
+        assert_eq!(*mut1, VAL - 30);
+        *mut1 = VAL - 5;
+
+        drop(guard1);
+
+        let guard3 = cell.borrow().unwrap();
+        assert_eq!(*guard3, VAL - 5);
+    }
+
+    #[test]
+    fn prevent_mut_mut_without_non_aliasing() {
+        const VAL: i32 = 23456;
+        let cell = GdCell::new(VAL);
+        let cell = cell.as_ref();
+
+        let mut guard1 = cell.borrow_mut().unwrap();
+        let mut1 = &mut *guard1;
+        assert_eq!(*mut1, VAL);
+        *mut1 = VAL + 50;
+
+        // let no_alias_guard = cell.set_non_aliasing(mut1).unwrap();
+
+        cell.borrow_mut()
+            .expect_err("reference may be aliasing so should be prevented");
+
+        drop(guard1);
+    }
+
+    #[test]
+    fn different_non_aliasing() {
+        const VAL1: i32 = 23456;
+        const VAL2: i32 = 11111;
+        let cell1 = GdCell::new(VAL1);
+        let cell1 = cell1.as_ref();
+        let cell2 = GdCell::new(VAL2);
+        let cell2 = cell2.as_ref();
+
+        let mut guard1 = cell1.borrow_mut().unwrap();
+        let mut1 = &mut *guard1;
+
+        assert_eq!(*mut1, VAL1);
+        *mut1 = VAL1 + 10;
+
+        let mut guard2 = cell2.borrow_mut().unwrap();
+        let mut2 = &mut *guard2;
+
+        assert_eq!(*mut2, VAL2);
+        *mut2 = VAL2 + 10;
+
+        let no_alias_guard = cell1
+            .set_non_aliasing(mut2)
+            .expect_err("should not allow different references");
+
+        drop(no_alias_guard);
+
+        drop(guard1);
+        drop(guard2);
+    }
+}
diff --git a/godot-cell/tests/mock.rs b/godot-cell/tests/mock.rs
new file mode 100644
index 000000000..e3907bd33
--- /dev/null
+++ b/godot-cell/tests/mock.rs
@@ -0,0 +1,315 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+//! A mock implementation of our instance-binding pattern in pure rust.
+//!
+//! Used so we can run miri on this, which we cannot when we are running in itest against Godot.
+
+use std::collections::HashMap;
+use std::error::Error;
+use std::marker::PhantomData;
+use std::pin::Pin;
+use std::sync::{atomic::AtomicUsize, Mutex, OnceLock};
+
+use godot_cell::{GdCell, NonAliasingGuard};
+
+struct InstanceBinding(*mut ());
+
+unsafe impl Sync for InstanceBinding {}
+unsafe impl Send for InstanceBinding {}
+
+static INSTANCE_BINDINGS: OnceLock<Mutex<HashMap<usize, InstanceBinding>>> = OnceLock::new();
+
+struct InstanceStorage<T> {
+    cell: Pin<Box<GdCell<T>>>,
+}
+
+fn binding() -> &'static Mutex<HashMap<usize, InstanceBinding>> {
+    INSTANCE_BINDINGS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn register_instance<T>(instance: T) -> usize {
+    static COUNTER: AtomicUsize = AtomicUsize::new(0);
+
+    let binding = binding();
+
+    let mut guard = binding.lock().unwrap();
+
+    let key = COUNTER.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
+
+    assert!(!guard.contains_key(&key));
+
+    let cell = GdCell::new(instance);
+    let storage = Box::new(InstanceStorage { cell });
+    let ptr = Box::into_raw(storage) as *mut ();
+
+    guard.insert(key, InstanceBinding(ptr));
+    key
+}
+/*
+unsafe fn free_instance<T>(key: usize) {
+    let binding = binding();
+    let mut guard = binding.lock().unwrap();
+
+    let InstanceBinding(ptr) = guard.remove(&key).unwrap();
+
+    let ptr: *mut InstanceStorage<T> = ptr as *mut _;
+
+    let storage = unsafe { Box::from_raw(ptr) };
+}
+*/
+unsafe fn get_instance<'a, T>(key: usize) -> &'a InstanceStorage<T> {
+    let binding = binding();
+    let guard = binding.lock().unwrap();
+
+    let instance = guard.get(&key).unwrap();
+
+    let ptr: *mut InstanceStorage<T> = instance.0 as *mut _;
+
+    &*ptr
+}
+
+unsafe fn call_immut_method<T>(key: usize, method: fn(&T)) -> Result<(), Box<dyn Error>> {
+    let storage = get_instance::<T>(key);
+
+    let instance = storage.cell.as_ref().borrow()?;
+    method(&*instance);
+
+    Ok(())
+}
+
+unsafe fn call_mut_method<T>(key: usize, method: fn(&mut T)) -> Result<(), Box<dyn Error>> {
+    let storage = get_instance::<T>(key);
+
+    let mut instance = storage.cell.as_ref().borrow_mut()?;
+    method(&mut *instance);
+
+    Ok(())
+}
+
+struct Base<T> {
+    instance_id: usize,
+    _p: PhantomData<T>,
+}
+
+impl<T> Base<T> {
+    fn cell<'a, 'b: 'a>(&'a self) -> Pin<&'b GdCell<T>> {
+        let storage = unsafe { get_instance::<T>(self.instance_id) };
+        storage.cell.as_ref()
+    }
+}
+
+struct BaseGuard<'a, T> {
+    instance_id: usize,
+    _non_aliasing_guard: NonAliasingGuard<'a, T>,
+}
+
+impl<'a, T> BaseGuard<'a, T> {
+    fn new(instance_id: usize, non_aliasing_guard: NonAliasingGuard<'a, T>) -> Self {
+        Self {
+            instance_id,
+            _non_aliasing_guard: non_aliasing_guard,
+        }
+    }
+
+    fn call_immut(&self, f: fn(&T)) {
+        unsafe { call_immut_method(self.instance_id, f).unwrap() }
+    }
+
+    fn call_mut(&self, f: fn(&mut T)) {
+        unsafe { call_mut_method(self.instance_id, f).unwrap() }
+    }
+}
+
+struct MyClass {
+    base: Base<MyClass>,
+    int: i64,
+}
+
+impl MyClass {
+    fn init() -> usize {
+        let this = Self {
+            base: Base {
+                instance_id: 0,
+                _p: PhantomData,
+            },
+            int: 0,
+        };
+        let key = register_instance(this);
+
+        let instance = unsafe { get_instance::<Self>(key) };
+        instance
+            .cell
+            .as_ref()
+            .borrow_mut()
+            .unwrap()
+            .base
+            .instance_id = key;
+        key
+    }
+
+    fn immut_method(&self) {
+        println!("immut #1: int is {}", self.int);
+    }
+
+    fn mut_method(&mut self) {
+        println!("mut #1: int is {}", self.int);
+        self.int += 1;
+        println!("mut #2: int is now {}", self.int);
+    }
+
+    fn mut_method_calls_immut(&mut self) {
+        println!("mut_calls_immut #1: int is {}", self.int);
+        self.int += 1;
+        println!("mut_calls_immut #2: int is now {}", self.int);
+        self.base().call_immut(Self::immut_method);
+        println!("mut_calls_immut #3: int is now {}", self.int);
+    }
+
+    fn mut_method_calls_mut(&mut self) {
+        println!("mut_calls_mut #1: int is {}", self.int);
+        self.int += 1;
+        println!("mut_calls_mut #2: int is now {}", self.int);
+        self.base().call_mut(Self::mut_method);
+        println!("mut_calls_mut #3: int is now {}", self.int);
+    }
+
+    fn mut_method_calls_twice(&mut self) {
+        println!("mut_calls_twice #1: int is {}", self.int);
+        self.int += 1;
+        println!("mut_calls_twice #2: int is now {}", self.int);
+        self.base().call_mut(Self::mut_method_calls_immut);
+        println!("mut_calls_twice #3: int is now {}", self.int);
+    }
+
+    fn mut_method_calls_twice_mut(&mut self) {
+        println!("mut_calls_twice_mut #1: int is {}", self.int);
+        self.int += 1;
+        println!("mut_calls_twice_mut #2: int is now {}", self.int);
+        self.base().call_mut(Self::mut_method_calls_mut);
+        println!("mut_calls_twice_mut #3: int is now {}", self.int);
+    }
+
+    fn immut_calls_immut_directly(&self) {
+        println!("immut_calls_directly #1: int is {}", self.int);
+        unsafe { call_immut_method(self.base.instance_id, Self::immut_method).unwrap() }
+    }
+
+    fn base(&mut self) -> BaseGuard<'_, Self> {
+        let cell = self.base.cell();
+        BaseGuard::new(self.base.instance_id, cell.set_non_aliasing(self).unwrap())
+    }
+}
+
+#[test]
+fn call_works() {
+    let instance_id = MyClass::init();
+
+    unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
+}
+
+#[test]
+fn all_calls_work() {
+    let instance_id = MyClass::init();
+
+    fn assert_int_is(instance_id: usize, target: i64) {
+        let storage = unsafe { get_instance::<MyClass>(instance_id) };
+        let bind = storage.cell.as_ref().borrow().unwrap();
+        assert_eq!(bind.int, target);
+    }
+
+    assert_int_is(instance_id, 0);
+    unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
+    assert_int_is(instance_id, 0);
+    unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() };
+    assert_int_is(instance_id, 1);
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap() };
+    assert_int_is(instance_id, 2);
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap() };
+    assert_int_is(instance_id, 4);
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap() };
+    assert_int_is(instance_id, 6);
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap() };
+    assert_int_is(instance_id, 9);
+    unsafe { call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap() };
+    assert_int_is(instance_id, 9);
+}
+
+#[test]
+fn calls_different_thread() {
+    use std::thread;
+
+    let instance_id = MyClass::init();
+    fn assert_int_is(instance_id: usize, target: i64) {
+        let storage = unsafe { get_instance::<MyClass>(instance_id) };
+        let bind = storage.cell.as_ref().borrow().unwrap();
+        assert_eq!(bind.int, target);
+    }
+
+    assert_int_is(instance_id, 0);
+
+    unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
+    assert_int_is(instance_id, 0);
+    thread::spawn(move || unsafe {
+        call_immut_method(instance_id, MyClass::immut_method).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 0);
+
+    unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() };
+    assert_int_is(instance_id, 1);
+    thread::spawn(move || unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() })
+        .join()
+        .unwrap();
+    assert_int_is(instance_id, 2);
+
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap() };
+    assert_int_is(instance_id, 3);
+    thread::spawn(move || unsafe {
+        call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 4);
+
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap() };
+    assert_int_is(instance_id, 6);
+    thread::spawn(move || unsafe {
+        call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 8);
+
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap() };
+    assert_int_is(instance_id, 10);
+    thread::spawn(move || unsafe {
+        call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 12);
+
+    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap() };
+    assert_int_is(instance_id, 15);
+    thread::spawn(move || unsafe {
+        call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 18);
+
+    unsafe { call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap() };
+    assert_int_is(instance_id, 18);
+    thread::spawn(move || unsafe {
+        call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap()
+    })
+    .join()
+    .unwrap();
+    assert_int_is(instance_id, 18);
+}
diff --git a/godot-core/Cargo.toml b/godot-core/Cargo.toml
index 67d25c978..88f03ff13 100644
--- a/godot-core/Cargo.toml
+++ b/godot-core/Cargo.toml
@@ -27,6 +27,7 @@ godot-ffi = { path = "../godot-ffi" }
 # See https://docs.rs/glam/latest/glam/index.html#feature-gates
 glam = { version = "0.23", features = ["debug-glam-assert"] }
 serde = { version = "1", features = ["derive"], optional = true }
+godot-cell = { path = "../godot-cell" }
 
 # Reverse dev dependencies so doctests can use `godot::` prefix
 [dev-dependencies]
diff --git a/godot-core/src/obj/base.rs b/godot-core/src/obj/base.rs
index ec8b0100d..9ee6a891a 100644
--- a/godot-core/src/obj/base.rs
+++ b/godot-core/src/obj/base.rs
@@ -66,6 +66,7 @@ impl<T: GodotClass> Base<T> {
     ///
     /// Using this method to call methods on the base field of a Rust object is discouraged, instead use the
     /// methods from [`WithBaseField`](super::WithBaseField) when possible.
+    #[doc(hidden)]
     pub fn to_gd(&self) -> Gd<T> {
         (*self.obj).clone()
     }
@@ -74,6 +75,7 @@ impl<T: GodotClass> Base<T> {
     ///
     /// Using this method to call methods on the base field of a Rust object is discouraged, instead use the
     /// methods from [`WithBaseField`](super::WithBaseField) when possible.
+    #[doc(hidden)]
     pub fn as_gd(&self) -> &Gd<T> {
         &self.obj
     }
diff --git a/godot-core/src/obj/guards.rs b/godot-core/src/obj/guards.rs
index d366db29a..98935e8a7 100644
--- a/godot-core/src/obj/guards.rs
+++ b/godot-core/src/obj/guards.rs
@@ -8,10 +8,9 @@
 use godot_ffi::out;
 
 use std::fmt::Debug;
-use std::marker::PhantomData;
 use std::ops::{Deref, DerefMut};
 
-use crate::storage::{MutGuard, RefGuard};
+use crate::storage::{BaseMutGuard, MutGuard, RefGuard};
 
 use super::{Gd, GodotClass};
 
@@ -81,34 +80,67 @@ impl<T: GodotClass> Drop for GdMut<'_, T> {
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Shared reference guard for a [`Base`](crate::obj::Base) pointer.
+///
+/// This can be used to call methods on the base object of a rust object that take `&self` as the receiver.
+///
+/// See [`WithBaseField::base()`](super::WithBaseField::base()) for usage.
 pub struct BaseRef<'a, T: GodotClass> {
-    pub(crate) gd: Gd<T>,
-    pub(crate) _p: PhantomData<&'a ()>,
+    gd: Gd<T::Base>,
+    _instance: &'a T,
+}
+
+impl<'a, T: GodotClass> BaseRef<'a, T> {
+    pub(crate) fn new(gd: Gd<T::Base>, instance: &'a T) -> Self {
+        Self {
+            gd,
+            _instance: instance,
+        }
+    }
 }
 
 impl<T: GodotClass> Deref for BaseRef<'_, T> {
-    type Target = Gd<T>;
+    type Target = Gd<T::Base>;
 
-    fn deref(&self) -> &Gd<T> {
+    fn deref(&self) -> &Gd<T::Base> {
         &self.gd
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Mutable/exclusive reference guard for a [`Base`](crate::obj::Base) pointer.
+///
+/// This can be used to call methods on the base object of a rust object that take `&self` or `&mut self` as
+/// the receiver.
+///
+/// See [`WithBaseField::base_mut()`](super::WithBaseField::base_mut()) for usage.
 pub struct BaseMut<'a, T: GodotClass> {
-    pub(crate) gd: Gd<T>,
-    pub(crate) _p: PhantomData<&'a mut ()>,
+    gd: Gd<T::Base>,
+    _base_mut_guard: BaseMutGuard<'a, T>,
+}
+
+impl<'a, T: GodotClass> BaseMut<'a, T> {
+    pub(crate) fn new(gd: Gd<T::Base>, base_mut_guard: BaseMutGuard<'a, T>) -> Self {
+        Self {
+            gd,
+            _base_mut_guard: base_mut_guard,
+        }
+    }
 }
 
 impl<T: GodotClass> Deref for BaseMut<'_, T> {
-    type Target = Gd<T>;
+    type Target = Gd<T::Base>;
 
-    fn deref(&self) -> &Gd<T> {
+    fn deref(&self) -> &Gd<T::Base> {
         &self.gd
     }
 }
 
 impl<T: GodotClass> DerefMut for BaseMut<'_, T> {
-    fn deref_mut(&mut self) -> &mut Gd<T> {
+    fn deref_mut(&mut self) -> &mut Gd<T::Base> {
         &mut self.gd
     }
 }
diff --git a/godot-core/src/obj/raw.rs b/godot-core/src/obj/raw.rs
index 5cd65613d..4c98ab5d7 100644
--- a/godot-core/src/obj/raw.rs
+++ b/godot-core/src/obj/raw.rs
@@ -320,8 +320,32 @@ where
     ///
     /// Returns `None` if self is null.
     pub(crate) fn storage(&self) -> Option<&InstanceStorage<T>> {
+        // SAFETY:
+        // - We have a `&self`, so the storage must already have been created.
+        // - The storage cannot be destroyed while we have a `&self` reference, so it will not be
+        //   destroyed for the duration of `'a`.
+        unsafe { self.storage_unbounded() }
+    }
+
+    /// Storage object associated with the extension instance.
+    ///
+    /// Returns `None` if self is null.
+    ///
+    /// # Safety
+    ///
+    /// This method provides a reference to the storage with an arbitrarily long lifetime `'b`. The reference
+    /// must actually be live for the duration of this lifetime.
+    ///
+    /// The only time when a `&mut` reference can be taken to a `InstanceStorage` is when it is constructed
+    /// or destroyed. So it is sufficient to ensure that the storage is not created or destroyed during the
+    /// lifetime `'b`.
+    pub(crate) unsafe fn storage_unbounded<'b>(&self) -> Option<&'b InstanceStorage<T>> {
         // SAFETY: instance pointer belongs to this instance. We only get a shared reference, no exclusive access, so even
         // calling this from multiple Gd pointers is safe.
+        //
+        // The caller is responsible for ensuring that the storage is live for the duration of the lifetime
+        // `'b`.
+        //
         // Potential issue is a concurrent free() in multi-threaded access; but that would need to be guarded against inside free().
         unsafe {
             let binding = self.resolve_instance_ptr();
@@ -329,6 +353,7 @@ where
         }
     }
 
+    // TODO: document unsafety in this function, and double check that it actually needs to be unsafe.
     unsafe fn resolve_instance_ptr(&self) -> sys::GDExtensionClassInstancePtr {
         if self.is_null() {
             return ptr::null_mut();
diff --git a/godot-core/src/obj/traits.rs b/godot-core/src/obj/traits.rs
index 14f4cd08d..8d60ffa5c 100644
--- a/godot-core/src/obj/traits.rs
+++ b/godot-core/src/obj/traits.rs
@@ -5,13 +5,11 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use std::marker::PhantomData;
-
-use crate::builder::ClassBuilder;
 use crate::builtin::meta::ClassName;
 use crate::builtin::GString;
 use crate::init::InitLevel;
 use crate::obj::Gd;
+use crate::{builder::ClassBuilder, storage::Storage};
 
 use godot_ffi as sys;
 
@@ -239,7 +237,7 @@ pub trait IndexEnum: EngineEnum {
 ///
 /// Gives direct access to the containing `Gd<Self>` from `Self`.
 // Possible alternative for builder APIs, although even less ergonomic: Base<T> could be Base<T, Self> and return Gd<Self>.
-pub trait WithBaseField: GodotClass {
+pub trait WithBaseField: GodotClass<Declarer = dom::UserDomain> {
     /// Returns the `Gd` pointer containing this object.
     ///
     /// This is intended to be stored or passed to engine methods. You cannot call `bind()` or `bind_mut()` on it, while the method
@@ -250,19 +248,153 @@ pub trait WithBaseField: GodotClass {
     fn base_field(&self) -> &Base<Self::Base>;
 
     /// Returns a shared reference suitable for calling engine methods on this object.
-    fn base(&self) -> BaseRef<'_, Self::Base> {
-        BaseRef {
-            gd: self.base_field().to_gd(),
-            _p: PhantomData,
-        }
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use godot::prelude::*;
+    ///
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct MyClass {
+    ///     #[base]
+    ///     base: Base<Node>,
+    /// }
+    ///
+    /// #[godot_api]
+    /// impl INode for MyClass {
+    ///     fn process(&mut self, _delta: f64) {
+    ///         let name = self.base().get_name();
+    ///         godot_print!("name is {name}");
+    ///     }
+    /// }
+    ///
+    /// # pub struct Test;
+    ///
+    /// # #[gdextension]
+    /// # unsafe impl ExtensionLibrary for Test {}
+    /// ```
+    ///
+    /// However we cannot call methods that require `&mut Base`, such as
+    /// [`Node::add_child()`](crate::engine::Node::add_child).
+    ///
+    /// ```compile_fail
+    /// use godot::prelude::*;
+    ///
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct MyClass {
+    ///     #[base]
+    ///     base: Base<Node>,
+    /// }
+    ///
+    /// #[godot_api]
+    /// impl INode for MyClass {
+    ///     fn process(&mut self, _delta: f64) {
+    ///         let node = Node::new_alloc();
+    ///         // fails because `add_child` requires a mutable reference.
+    ///         self.base().add_child(node);
+    ///     }
+    /// }
+    ///
+    /// # pub struct Test;
+    ///
+    /// # #[gdextension]
+    /// # unsafe impl ExtensionLibrary for Test {}
+    /// ```
+    ///
+    /// For this, use [`base_mut()`](WithBaseField::base_mut()) instead.
+    fn base(&self) -> BaseRef<'_, Self> {
+        let gd = self.base_field().to_gd();
+
+        BaseRef::new(gd, self)
     }
 
     /// Returns a mutable reference suitable for calling engine methods on this object.
-    fn base_mut(&mut self) -> BaseMut<'_, Self::Base> {
-        BaseMut {
-            gd: self.base_field().to_gd(),
-            _p: PhantomData,
-        }
+    ///
+    /// This method will allow you to call back into the same object from Godot, unlike what would happen
+    /// if you used [`to_gd()`](WithBaseField::to_gd).
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use godot::prelude::*;
+    ///
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct MyClass {
+    ///     #[base]
+    ///     base: Base<Node>,
+    /// }
+    ///
+    /// #[godot_api]
+    /// impl INode for MyClass {
+    ///     fn process(&mut self, _delta: f64) {
+    ///         let node = Node::new_alloc();
+    ///         self.base_mut().add_child(node);
+    ///     }
+    /// }
+    ///
+    /// # pub struct Test;
+    ///
+    /// # #[gdextension]
+    /// # unsafe impl ExtensionLibrary for Test {}
+    /// ```
+    ///
+    /// We can call back into `self` through Godot:
+    ///
+    /// ```
+    /// use godot::prelude::*;
+    ///
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct MyClass {
+    ///     #[base]
+    ///     base: Base<Node>,
+    /// }
+    ///
+    /// #[godot_api]
+    /// impl INode for MyClass {
+    ///     fn process(&mut self, _delta: f64) {
+    ///         self.base_mut().call("other_method".into(), &[]);
+    ///     }
+    /// }
+    ///
+    /// #[godot_api]
+    /// impl MyClass {
+    ///     #[func]
+    ///     fn other_method(&mut self) {}
+    /// }
+    ///
+    /// # pub struct Test;
+    ///
+    /// # #[gdextension]
+    /// # unsafe impl ExtensionLibrary for Test {}
+    /// ```
+    #[allow(clippy::let_unit_value)]
+    fn base_mut(&mut self) -> BaseMut<'_, Self> {
+        let base_gd = self.base_field().to_gd();
+
+        let gd = self.to_gd();
+        // SAFETY:
+        // - We have a `Gd<Self>` so, provided that `storage_unbounded` succeeds, the associated instance
+        //   storage has been created.
+        //
+        // - Since we can get a `&'a Base<Self::Base>` from `&'a self`, that must mean we have a Rust object
+        //   somewhere that has this base object. The only way to have such a base object is by being the
+        //   Rust object referenced by that base object. I.e this storage's user-instance is that Rust
+        //   object. That means this storage cannot be destroyed for the lifetime of that Rust object. And
+        //   since we have a reference to the base object derived from that Rust object, then that Rust
+        //   object must outlive `'a`. And so the storage cannot be destroyed during the lifetime `'a`.
+        let storage = unsafe {
+            gd.raw
+                .storage_unbounded()
+                .expect("we have a `Gd<Self>` so the raw should not be null")
+        };
+
+        let guard = storage.get_base_mut(self);
+
+        BaseMut::new(base_gd, guard)
     }
 }
 
diff --git a/godot-core/src/storage.rs b/godot-core/src/storage.rs
index 87a83d08a..bf785357c 100644
--- a/godot-core/src/storage.rs
+++ b/godot-core/src/storage.rs
@@ -18,38 +18,118 @@ pub enum Lifecycle {
     Destroying,
 }
 
+#[cfg_attr(not(feature = "experimental-threads"), allow(dead_code))]
+pub struct AtomicLifecycle {
+    atomic: std::sync::atomic::AtomicU32,
+}
+
+#[cfg_attr(not(feature = "experimental-threads"), allow(dead_code))]
+impl AtomicLifecycle {
+    pub fn new(value: Lifecycle) -> Self {
+        Self {
+            atomic: std::sync::atomic::AtomicU32::new(value as u32),
+        }
+    }
+
+    pub fn get(&self) -> Lifecycle {
+        match self.atomic.load(std::sync::atomic::Ordering::Relaxed) {
+            0 => Lifecycle::Alive,
+            1 => Lifecycle::Destroying,
+            other => panic!("invalid lifecycle {other}"),
+        }
+    }
+
+    pub fn set(&self, lifecycle: Lifecycle) {
+        let value = match lifecycle {
+            Lifecycle::Alive => 0,
+            Lifecycle::Destroying => 1,
+        };
+
+        self.atomic
+            .store(value, std::sync::atomic::Ordering::Relaxed);
+    }
+}
+
 #[cfg_attr(feature = "experimental-threads", allow(dead_code))]
 mod single_threaded;
 
 #[cfg_attr(not(feature = "experimental-threads"), allow(dead_code))]
 mod multi_threaded;
 
-pub trait Storage {
+/// A storage for an instance binding.
+///
+/// # Safety
+///
+/// [`is_bound()`](Storage::is_bound()) must return `true` if any references to the stored user instance
+/// exists.
+///
+/// It must be safe to drop this storage if we have a `&mut` reference to the storage and  
+/// [`is_bound()`](Storage::is_bound()) returns `false`.
+pub unsafe trait Storage {
+    /// The type of instances stored by this storage.
     type Instance: GodotClass;
+
+    /// The type of guards returned when a shared reference is taken.
     type RefGuard<'a>: Deref<Target = Self::Instance>
     where
         Self: 'a;
+
+    /// The type of guards returned when a mutable reference is taken.
     type MutGuard<'a>: Deref<Target = Self::Instance> + DerefMut
     where
         Self: 'a;
 
+    /// The type of guards returned when we know that a mutable reference can be safely ignored for purposes
+    /// of taking mutable references.
+    type BaseMutGuard<'a>
+    where
+        Self: 'a;
+
+    /// Constructs a new storage for an instance binding referencing `user_instance`.
     fn construct(
         user_instance: Self::Instance,
         base: Base<<Self::Instance as GodotClass>::Base>,
     ) -> Self;
 
+    /// Returns `true` when there are any outstanding references to this storage's instance.
     fn is_bound(&self) -> bool;
 
+    /// The base object that this storage contains.
     fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base>;
 
+    /// Returns a shared reference to this storage's instance.
+    ///
+    /// This will ensure Rust's rules surrounding references are upheld. Possibly panicking at runtime if
+    /// they are violated.
     fn get(&self) -> Self::RefGuard<'_>;
 
+    /// Returns a mutable/exclusive reference to this storage's instance.
+    ///
+    /// This will ensure Rust's rules surrounding references are upheld. Possibly panicking at runtime if
+    /// they are violated.
     fn get_mut(&self) -> Self::MutGuard<'_>;
 
+    /// Returns a guard that allows calling methods on `Gd<Base>` that take `&mut self`.
+    ///
+    /// This can use the provided `instance` to provide extra safety guarantees such as allowing reentrant
+    /// code to create new mutable references.
+    fn get_base_mut<'a: 'b, 'b>(
+        &'a self,
+        instance: &'b mut Self::Instance,
+    ) -> Self::BaseMutGuard<'b>;
+
+    /// Returns whether this storage is currently alive or being destroyed.
+    ///
+    /// This is purely informational and cannot be relied on for safety.
     fn get_lifecycle(&self) -> Lifecycle;
 
+    /// Mark this storage as currently alive or being destroyed.
+    ///
+    /// This is purely informational and thus is safe to set to whatever value, but it should still be set as
+    /// expected.
     fn set_lifecycle(&self, lifecycle: Lifecycle);
 
+    /// Get a `Gd` referencing this storage's instance.
     fn get_gd(&self) -> Gd<Self::Instance>
     where
         Self::Instance: Inherits<<Self::Instance as GodotClass>::Base>,
@@ -57,12 +137,9 @@ pub trait Storage {
         self.base().to_gd().cast()
     }
 
-    fn debug_info(&self) -> String {
-        // Unlike get_gd(), this doesn't require special trait bounds.
-
-        format!("{:?}", self.base())
-    }
-
+    /// Puts self onto the heap and returns a pointer to this new heap-allocation.
+    ///
+    /// This will leak memory and so the caller is responsible for manually managing the memory.
     #[must_use]
     fn into_raw(self) -> *mut Self
     where
@@ -97,6 +174,7 @@ pub trait Storage {
     }
 }
 
+/// An internal trait for keeping track of reference counts for a storage.
 pub(crate) trait StorageRefCounted: Storage {
     fn godot_ref_count(&self) -> u32;
 
@@ -107,23 +185,18 @@ pub(crate) trait StorageRefCounted: Storage {
 
 #[cfg(not(feature = "experimental-threads"))]
 pub type InstanceStorage<T> = single_threaded::InstanceStorage<T>;
+
 #[cfg(feature = "experimental-threads")]
 pub type InstanceStorage<T> = multi_threaded::InstanceStorage<T>;
 
 pub type RefGuard<'a, T> = <InstanceStorage<T> as Storage>::RefGuard<'a>;
 pub type MutGuard<'a, T> = <InstanceStorage<T> as Storage>::MutGuard<'a>;
+pub type BaseMutGuard<'a, T> = <InstanceStorage<T> as Storage>::BaseMutGuard<'a>;
 
-impl<T: GodotClass> Drop for InstanceStorage<T> {
-    fn drop(&mut self) {
-        out!(
-            "    Storage::drop (rc={})           <{:?}>",
-            self.godot_ref_count(),
-            self.base(),
-        );
-        //let _ = mem::take(&mut self.user_instance);
-        //out!("    Storage::drop end              <{:?}>", self.base);
-    }
-}
+const fn _assert_implements_storage<T: Storage + StorageRefCounted>() {}
+
+const _INSTANCE_STORAGE_IMPLEMENTS_STORAGE: () =
+    _assert_implements_storage::<InstanceStorage<crate::engine::Object>>();
 
 /// Interprets the opaque pointer as pointing to `InstanceStorage<T>`.
 ///
@@ -131,6 +204,7 @@ impl<T: GodotClass> Drop for InstanceStorage<T> {
 ///
 /// # Safety
 /// `instance_ptr` is assumed to point to a valid instance.
+/// The returned reference must be live for the duration of `'u`.
 // Note: unbounded ref AND &mut out of thin air is not very beautiful, but it's  -- consider using with_storage(ptr, closure) and drop_storage(ptr)
 pub unsafe fn as_storage<'u, T: GodotClass>(
     instance_ptr: sys::GDExtensionClassInstancePtr,
@@ -165,8 +239,8 @@ pub unsafe fn destroy_storage<T: GodotClass>(instance_ptr: sys::GDExtensionClass
             "Destroyed an object from Godot side, while a bind() or bind_mut() call was active.\n  \
             This is a bug in your code that may cause UB and logic errors. Make sure that objects are not\n  \
             destroyed while you still hold a Rust reference to them, or use Gd::free() which is safe.\n  \
-            object: {}",
-            (*raw).debug_info()
+            object: {:?}",
+            (*raw).base()
         );
 
         // In Debug mode, crash which may trigger breakpoint.
@@ -180,7 +254,13 @@ pub unsafe fn destroy_storage<T: GodotClass>(instance_ptr: sys::GDExtensionClass
     }
 
     if !leak_rust_object {
-        let _drop = Box::from_raw(raw);
+        // SAFETY:
+        // `leak_rust_object` is false, meaning that `is_bound()` returned `false`. Because if it were `true`
+        // then the process would either be aborted, or we set `leak_rust_object = true`.
+        //
+        // Therefore we can safely drop this storage as per the safety contract of `Storage`. Which we know
+        // `InstanceStorage<T>` implements because of `_INSTANCE_STORAGE_IMPLEMENTS_STORAGE`.
+        let _drop = unsafe { Box::from_raw(raw) };
     }
 }
 
diff --git a/godot-core/src/storage/multi_threaded.rs b/godot-core/src/storage/multi_threaded.rs
index 903167dd4..3b034c768 100644
--- a/godot-core/src/storage/multi_threaded.rs
+++ b/godot-core/src/storage/multi_threaded.rs
@@ -1,43 +1,21 @@
-use std::sync;
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use std::any::type_name;
+use std::pin::Pin;
 use std::sync::atomic::{AtomicU32, Ordering};
 
 use crate::obj::{Base, GodotClass};
 use crate::out;
 
-use super::Lifecycle;
+use super::{AtomicLifecycle, Lifecycle, Storage, StorageRefCounted};
 
-pub struct AtomicLifecycle {
-    atomic: AtomicU32,
-}
-
-impl AtomicLifecycle {
-    pub fn new(value: Lifecycle) -> Self {
-        Self {
-            atomic: AtomicU32::new(value as u32),
-        }
-    }
-
-    pub fn get(&self) -> Lifecycle {
-        match self.atomic.load(Ordering::Relaxed) {
-            0 => Lifecycle::Alive,
-            1 => Lifecycle::Destroying,
-            other => panic!("invalid lifecycle {other}"),
-        }
-    }
-
-    pub fn set(&self, lifecycle: Lifecycle) {
-        let value = match lifecycle {
-            Lifecycle::Alive => 0,
-            Lifecycle::Destroying => 1,
-        };
-
-        self.atomic.store(value, Ordering::Relaxed);
-    }
-}
-
-/// Manages storage and lifecycle of user's extension class instances.
 pub struct InstanceStorage<T: GodotClass> {
-    user_instance: sync::RwLock<T>,
+    user_instance: Pin<Box<godot_cell::GdCell<T>>>,
     pub(super) base: Base<T::Base>,
 
     // Declared after `user_instance`, is dropped last
@@ -45,50 +23,30 @@ pub struct InstanceStorage<T: GodotClass> {
     godot_ref_count: AtomicU32,
 }
 
-/// For all Godot extension classes
-impl<T: GodotClass> InstanceStorage<T> {
-    /// Returns a write guard (even if poisoned), or `None` when the lock is held by another thread.
-    /// This might need adjustment if threads should await locks.
-    #[must_use]
-    fn write_ignoring_poison(&self) -> Option<sync::RwLockWriteGuard<T>> {
-        match self.user_instance.try_write() {
-            Ok(guard) => Some(guard),
-            Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
-            Err(sync::TryLockError::WouldBlock) => None,
-        }
-    }
-
-    /// Returns a read guard (even if poisoned), or `None` when the lock is held by another writing thread.
-    /// This might need adjustment if threads should await locks.
-    #[must_use]
-    fn read_ignoring_poison(&self) -> Option<sync::RwLockReadGuard<T>> {
-        match self.user_instance.try_read() {
-            Ok(guard) => Some(guard),
-            Err(sync::TryLockError::Poisoned(poison_error)) => Some(poison_error.into_inner()),
-            Err(sync::TryLockError::WouldBlock) => None,
-        }
-    }
-
-    // fn __static_type_check() {
-    //     enforce_sync::<InstanceStorage<T>>();
-    // }
-}
-
-impl<T: GodotClass> super::Storage for InstanceStorage<T> {
+// SAFETY:
+// The only way to get a reference to the user instance is by going through the `GdCell` in `user_instance`.
+// If this `GdCell` has returned any references, then `self.user_instance.as_ref().is_currently_bound()` will
+// return true. So `is_bound` will return true when a reference to the user instance exists.
+//
+// If `is_bound` is false, then there are no references to the user instance in this storage. And if a `&mut`
+// reference to the storage exists then no other references to data in this storage can exist. So we can
+// safely drop it.
+unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     type Instance = T;
 
-    type RefGuard<'a> = sync::RwLockReadGuard<'a, T>;
+    type RefGuard<'a> = godot_cell::RefGuard<'a, T>;
+
+    type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
 
-    type MutGuard<'a> = sync::RwLockWriteGuard<'a, T>;
+    type BaseMutGuard<'a> = godot_cell::NonAliasingGuard<'a, T>;
 
     fn construct(
         user_instance: Self::Instance,
         base: Base<<Self::Instance as GodotClass>::Base>,
     ) -> Self {
-        out!("    Storage::construct             <{:?}>", base);
-
+        out!("    Storage::construct             <{}>", type_name::<T>());
         Self {
-            user_instance: sync::RwLock::new(user_instance),
+            user_instance: godot_cell::GdCell::new(user_instance),
             base,
             lifecycle: AtomicLifecycle::new(Lifecycle::Alive),
             godot_ref_count: AtomicU32::new(1),
@@ -96,8 +54,7 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
     }
 
     fn is_bound(&self) -> bool {
-        // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
-        self.write_ignoring_poison().is_none()
+        self.user_instance.as_ref().is_currently_bound()
     }
 
     fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base> {
@@ -105,25 +62,50 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
     }
 
     fn get(&self) -> Self::RefGuard<'_> {
-        self.read_ignoring_poison().unwrap_or_else(|| {
+        self.user_instance.as_ref().borrow().unwrap_or_else(|err| {
             panic!(
-                "Gd<T>::bind() failed, already bound; obj = {}.\n  \
-                     Make sure there is no &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                self.base,
+                "\
+                    Gd<T>::bind() failed, already bound; T = {}.\n  \
+                    Make sure to use `self.base_mut()` or `self.base()` instead of `self.to_gd()` when possible.\n  \
+                    Details: {err}.\
+                ",
+                type_name::<T>()
             )
         })
     }
 
     fn get_mut(&self) -> Self::MutGuard<'_> {
-        self.write_ignoring_poison().unwrap_or_else(|| {
-            panic!(
-                "Gd<T>::bind_mut() failed, already bound; obj = {}.\n  \
-                     Make sure there is no &T or &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                self.base,
-            )
-        })
+        self.user_instance
+            .as_ref()
+            .borrow_mut()
+            .unwrap_or_else(|err| {
+                panic!(
+                    "\
+                    Gd<T>::bind_mut() failed, already bound; T = {}.\n  \
+                    Make sure to use `self.base_mut()` instead of `self.to_gd()` when possible.\n  \
+                    Details: {err}.\
+                ",
+                    type_name::<T>()
+                )
+            })
+    }
+
+    fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
+        self.user_instance
+            .as_ref()
+            .set_non_aliasing(value)
+            .unwrap_or_else(|err| {
+                // We should never hit this, except maybe in extreme cases like having more than
+                // `usize::MAX` borrows.
+                panic!(
+                    "\
+                        `base_mut()` failed for type T = {}.\n  \
+                        This is most likely a bug, please report it.\n  \
+                        Details: {err}.\
+                    ",
+                    type_name::<T>()
+                )
+            })
     }
 
     fn get_lifecycle(&self) -> Lifecycle {
@@ -135,7 +117,7 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
     }
 }
 
-impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
+impl<T: GodotClass> StorageRefCounted for InstanceStorage<T> {
     fn godot_ref_count(&self) -> u32 {
         self.godot_ref_count.load(Ordering::Relaxed)
     }
@@ -159,15 +141,12 @@ impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
     }
 }
 
-// TODO make InstanceStorage<T> Sync
-// This type can be accessed concurrently from multiple threads, so it should be Sync. That implies however that T must be Sync too
-// (and possibly Send, because with `&mut` access, a `T` can be extracted as a value using mem::take() etc.).
-// Which again means that we need to infest half the codebase with T: Sync + Send bounds, *and* make it all conditional on
-// `#[cfg(feature = "experimental-threads")]`.
-//
-// A better design would be a distinct Gds<T: Sync> pointer, which requires synchronized.
-// This needs more design on the multi-threading front (#18).
-//
-// The following code + __static_type_check() above would make sure that InstanceStorage is Sync.
-// Make sure storage is Sync in multi-threaded case, as it can be concurrently accessed through aliased Gd<T> pointers.
-// fn enforce_sync<T: Sync>() {}
+impl<T: GodotClass> Drop for InstanceStorage<T> {
+    fn drop(&mut self) {
+        out!(
+            "    Storage::drop (rc={})           <{:?}>",
+            self.godot_ref_count(),
+            self.base(),
+        );
+    }
+}
diff --git a/godot-core/src/storage/single_threaded.rs b/godot-core/src/storage/single_threaded.rs
index 48cdcb6db..6042b6c12 100644
--- a/godot-core/src/storage/single_threaded.rs
+++ b/godot-core/src/storage/single_threaded.rs
@@ -1,14 +1,21 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
 use std::any::type_name;
 use std::cell;
+use std::pin::Pin;
 
 use crate::obj::{Base, GodotClass};
 use crate::out;
 
-use super::Lifecycle;
+use super::{Lifecycle, Storage, StorageRefCounted};
 
-/// Manages storage and lifecycle of user's extension class instances.
 pub struct InstanceStorage<T: GodotClass> {
-    user_instance: cell::RefCell<T>,
+    user_instance: Pin<Box<godot_cell::GdCell<T>>>,
     pub(super) base: Base<T::Base>,
 
     // Declared after `user_instance`, is dropped last
@@ -16,21 +23,30 @@ pub struct InstanceStorage<T: GodotClass> {
     godot_ref_count: cell::Cell<u32>,
 }
 
-impl<T: GodotClass> super::Storage for InstanceStorage<T> {
+// SAFETY:
+// The only way to get a reference to the user instance is by going through the `GdCell` in `user_instance`.
+// If this `GdCell` has returned any references, then `self.user_instance.as_ref().is_currently_bound()` will
+// return true. So `is_bound` will return true when a reference to the user instance exists.
+//
+// If `is_bound` is false, then there are no references to the user instance in this storage. And if a `&mut`
+// reference to the storage exists then no other references to data in this storage can exist. So we can
+// safely drop it.
+unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     type Instance = T;
 
-    type RefGuard<'a> = cell::Ref<'a, T>;
+    type RefGuard<'a> = godot_cell::RefGuard<'a, T>;
+
+    type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
 
-    type MutGuard<'a> = cell::RefMut<'a, T>;
+    type BaseMutGuard<'a> = godot_cell::NonAliasingGuard<'a, T>;
 
     fn construct(
         user_instance: Self::Instance,
         base: Base<<Self::Instance as GodotClass>::Base>,
     ) -> Self {
         out!("    Storage::construct             <{}>", type_name::<T>());
-
         Self {
-            user_instance: cell::RefCell::new(user_instance),
+            user_instance: godot_cell::GdCell::new(user_instance),
             base,
             lifecycle: cell::Cell::new(Lifecycle::Alive),
             godot_ref_count: cell::Cell::new(1),
@@ -38,8 +54,7 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
     }
 
     fn is_bound(&self) -> bool {
-        // Needs to borrow mutably, otherwise it succeeds if shared borrows are alive.
-        self.user_instance.try_borrow_mut().is_err()
+        self.user_instance.as_ref().is_currently_bound()
     }
 
     fn base(&self) -> &Base<<Self::Instance as GodotClass>::Base> {
@@ -47,25 +62,50 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
     }
 
     fn get(&self) -> Self::RefGuard<'_> {
-        self.user_instance.try_borrow().unwrap_or_else(|_e| {
+        self.user_instance.as_ref().borrow().unwrap_or_else(|err| {
             panic!(
-                "Gd<T>::bind() failed, already bound; T = {}.\n  \
-                     Make sure there is no &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
+                "\
+                    Gd<T>::bind() failed, already bound; T = {}.\n  \
+                    Make sure to use `self.base_mut()` or `self.base()` instead of `self.to_gd()` when possible.\n  \
+                    Details: {err}.\
+                ",
                 type_name::<T>()
             )
         })
     }
 
     fn get_mut(&self) -> Self::MutGuard<'_> {
-        self.user_instance.try_borrow_mut().unwrap_or_else(|_e| {
-            panic!(
-                "Gd<T>::bind_mut() failed, already bound; T = {}.\n  \
-                     Make sure there is no &T or &mut T live at the time.\n  \
-                     This often occurs when calling a GDScript function/signal from Rust, which then calls again Rust code.",
-                type_name::<T>()
-            )
-        })
+        self.user_instance
+            .as_ref()
+            .borrow_mut()
+            .unwrap_or_else(|err| {
+                panic!(
+                    "\
+                    Gd<T>::bind_mut() failed, already bound; T = {}.\n  \
+                    Make sure to use `self.base_mut()` instead of `self.to_gd()` when possible.\n  \
+                    Details: {err}.\
+                ",
+                    type_name::<T>()
+                )
+            })
+    }
+
+    fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
+        self.user_instance
+            .as_ref()
+            .set_non_aliasing(value)
+            .unwrap_or_else(|err| {
+                // We should never hit this, except maybe in extreme cases like having more than
+                // `usize::MAX` borrows.
+                panic!(
+                    "\
+                        `base_mut()` failed for type T = {}.\n  \
+                        This is most likely a bug, please report it.\n  \
+                        Details: {err}.\
+                    ",
+                    type_name::<T>()
+                )
+            })
     }
 
     fn get_lifecycle(&self) -> Lifecycle {
@@ -76,7 +116,8 @@ impl<T: GodotClass> super::Storage for InstanceStorage<T> {
         self.lifecycle.set(lifecycle)
     }
 }
-impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
+
+impl<T: GodotClass> StorageRefCounted for InstanceStorage<T> {
     fn godot_ref_count(&self) -> u32 {
         self.godot_ref_count.get()
     }
@@ -105,3 +146,13 @@ impl<T: GodotClass> super::StorageRefCounted for InstanceStorage<T> {
         );
     }
 }
+
+impl<T: GodotClass> Drop for InstanceStorage<T> {
+    fn drop(&mut self) {
+        out!(
+            "    Storage::drop (rc={})           <{:?}>",
+            self.godot_ref_count(),
+            self.base(),
+        );
+    }
+}
diff --git a/godot-macros/src/class/derive_godot_class.rs b/godot-macros/src/class/derive_godot_class.rs
index 140f05265..6c777e892 100644
--- a/godot-macros/src/class/derive_godot_class.rs
+++ b/godot-macros/src/class/derive_godot_class.rs
@@ -58,7 +58,7 @@ pub fn derive_godot_class(decl: Declaration) -> ParseResult<TokenStream> {
         quote! {
             impl ::godot::obj::WithBaseField for #class_name {
                 fn to_gd(&self) -> ::godot::obj::Gd<Self> {
-                    ::godot::obj::Gd::clone(&*self.#name).cast()
+                    self.#name.to_gd().cast()
                 }
 
                 fn base_field(&self) -> &::godot::obj::Base<<Self as ::godot::obj::GodotClass>::Base> {
diff --git a/itest/rust/Cargo.toml b/itest/rust/Cargo.toml
index 007ab836a..50d3ea14a 100644
--- a/itest/rust/Cargo.toml
+++ b/itest/rust/Cargo.toml
@@ -15,6 +15,7 @@ serde = ["dep:serde", "dep:serde_json", "godot/serde"]
 # Do not add features here that are 1:1 forwarded to the `godot` crate.
 # Instead, compile itest with `--features godot/my-feature`.
 
+
 [dependencies]
 godot = { path = "../../godot", default-features = false }
 serde = { version = "1", features = ["derive"], optional = true }
@@ -25,4 +26,3 @@ godot-bindings = { path = "../../godot-bindings" } # emit_godot_version_cfg
 # Minimum versions compatible with -Zminimal-versions
 proc-macro2 = "1.0.63"
 quote = "1.0.29"
-
diff --git a/itest/rust/src/object_tests/mod.rs b/itest/rust/src/object_tests/mod.rs
index 8169aec51..94d4c8c65 100644
--- a/itest/rust/src/object_tests/mod.rs
+++ b/itest/rust/src/object_tests/mod.rs
@@ -12,5 +12,6 @@ mod object_test;
 mod onready_test;
 mod property_template_test;
 mod property_test;
+mod reentrant_test;
 mod singleton_test;
 mod virtual_methods_test;
diff --git a/itest/rust/src/object_tests/reentrant_test.rs b/itest/rust/src/object_tests/reentrant_test.rs
new file mode 100644
index 000000000..20e59bcf6
--- /dev/null
+++ b/itest/rust/src/object_tests/reentrant_test.rs
@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use crate::framework::itest;
+use godot::prelude::*;
+
+#[derive(GodotClass)]
+#[class(init, base = Object)]
+pub struct MyClass {
+    #[base]
+    base: Base<Object>,
+
+    first_called_pre: bool,
+    first_called_post: bool,
+    second_called: bool,
+}
+
+#[godot_api]
+impl MyClass {
+    #[signal]
+    fn some_signal();
+
+    #[func]
+    fn first_calls(&mut self) {
+        self.first_called_pre = true;
+        self.base_mut().call("second".into(), &[]);
+        self.first_called_post = true;
+    }
+
+    #[func]
+    fn first_signal(&mut self) {
+        self.first_called_pre = true;
+        self.base_mut().emit_signal("some_signal".into(), &[]);
+        self.first_called_post = true;
+    }
+
+    #[func]
+    fn second(&mut self) {
+        self.second_called = true;
+    }
+}
+
+#[itest]
+fn reentrant_call_succeeds() {
+    let mut class = MyClass::alloc_gd();
+
+    assert!(!class.bind().first_called_pre);
+    assert!(!class.bind().first_called_post);
+    assert!(!class.bind().second_called);
+
+    class.call("first_calls".into(), &[]);
+
+    assert!(class.bind().first_called_pre);
+    assert!(class.bind().first_called_post);
+    assert!(class.bind().second_called);
+
+    class.free()
+}
+
+#[itest]
+fn reentrant_emit_succeeds() {
+    let mut class = MyClass::alloc_gd();
+
+    let callable = class.callable("second");
+    class.connect("some_signal".into(), callable);
+
+    assert!(!class.bind().first_called_pre);
+    assert!(!class.bind().first_called_post);
+    assert!(!class.bind().second_called);
+
+    class.call("first_signal".into(), &[]);
+
+    assert!(class.bind().first_called_pre);
+    assert!(class.bind().first_called_post);
+    assert!(class.bind().second_called);
+
+    class.free()
+}

From 2245154bf23e46b7ee089d0f2461cf930a863f51 Mon Sep 17 00:00:00 2001
From: Lili Zoey Zyli <sayaks1@gmail.com>
Date: Sun, 17 Dec 2023 20:48:19 +0100
Subject: [PATCH 4/7] Change from using `aliasing` to `accessible` terminology
 in `godot-cell`.

---
 .github/workflows/full-ci.yml             |  18 +--
 godot-cell/src/borrow_state.rs            | 156 +++++++++++-----------
 godot-cell/src/guards.rs                  | 103 +++++++++-----
 godot-cell/src/lib.rs                     | 104 ++++++---------
 godot-cell/tests/mock.rs                  |  10 +-
 godot-core/src/storage/multi_threaded.rs  |   4 +-
 godot-core/src/storage/single_threaded.rs |   4 +-
 7 files changed, 207 insertions(+), 192 deletions(-)

diff --git a/.github/workflows/full-ci.yml b/.github/workflows/full-ci.yml
index d84951bdc..231ee2398 100644
--- a/.github/workflows/full-ci.yml
+++ b/.github/workflows/full-ci.yml
@@ -158,25 +158,25 @@ jobs:
     name: miri-test
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: "Install Rust"
         uses: ./.github/composite/rust
+        with:
+          rust: nightly
+          components: miri
       
-      - name: "Install Miri"
-        run: |
-          rustup toolchain install nightly --component miri
-          rustup override set nightly
-          cargo miri setup
+      - name: "Setup Miri"
+        run: cargo miri setup
 
       - name: "Compile tests"
-        run: cargo +nightly miri test -p godot-cell --no-run
+        run: cargo miri test -p godot-cell --no-run
 
       - name: "Test stacked borrows"
-        run: cargo +nightly miri test -p godot-cell
+        run: cargo miri test -p godot-cell
       
       - name: "Test tree borrows"
-        run: MIRIFLAGS="-Zmiri-tree-borrows" cargo +nightly miri test -p godot-cell
+        run: MIRIFLAGS="-Zmiri-tree-borrows" cargo miri test -p godot-cell
 
 
   # For complex matrix workflow, see https://stackoverflow.com/a/65434401
diff --git a/godot-cell/src/borrow_state.rs b/godot-cell/src/borrow_state.rs
index fa549ad37..5fed93fe7 100644
--- a/godot-cell/src/borrow_state.rs
+++ b/godot-cell/src/borrow_state.rs
@@ -8,11 +8,11 @@
 /// A type that tracks the state of borrows for a [`GdCell`].
 ///
 /// This state upholds these invariants:
-/// - You can only take a shared borrow when there is no aliasing mutable borrow.
-/// - You can only take a mutable borrow when there is neither an aliasing mutable borrow, nor a shared
+/// - You can only take a shared borrow when there is no accessible mutable borrow.
+/// - You can only take a mutable borrow when there is neither an accessible mutable borrow, nor a shared
 /// borrow.
-/// - You can only set a mutable borrow as non-aliasing when an aliasing mutable borrow exists.
-/// - You can only unset a mutable borrow as non-aliasing when there is no aliasing mutable borrow and no
+/// - You can only set a mutable borrow as inaccessible when an accessible mutable borrow exists.
+/// - You can only unset a mutable borrow as inaccessible when there is no accessible mutable borrow and no
 /// shared borrows.  
 ///
 /// If a catastrophic error occurs, then the state will be poisoned. If the state is poisoned then that's
@@ -24,8 +24,8 @@ pub struct BorrowState {
     shared_count: usize,
     /// The number of `&mut T` references that are tracked.
     mut_count: usize,
-    /// The number of `&mut T` references that cannot be aliased.
-    non_aliasing_count: usize,
+    /// The number of `&mut T` references that are inaccessible.
+    inaccessible_count: usize,
     /// `true` if the borrow state has reached an erroneous or unreliable state.
     poisoned: bool,
 }
@@ -36,18 +36,18 @@ impl BorrowState {
         Self {
             shared_count: 0,
             mut_count: 0,
-            non_aliasing_count: 0,
+            inaccessible_count: 0,
             poisoned: false,
         }
     }
 
-    /// Returns `true` if there may be an aliasing mutable reference.
-    pub fn has_possibly_aliasing(&self) -> bool {
-        let count = self.mut_count - self.non_aliasing_count;
+    /// Returns `true` if there are any accessible mutable references.
+    pub fn has_accessible(&self) -> bool {
+        let count = self.mut_count - self.inaccessible_count;
 
         assert!(
             count <= 1,
-            "there should never be more than 1 aliasing reference"
+            "there should never be more than 1 accessible mutable reference"
         );
 
         count == 1
@@ -90,8 +90,8 @@ impl BorrowState {
     fn ensure_can_ref(&self) -> Result<(), BorrowStateErr> {
         self.ensure_not_poisoned()?;
 
-        if self.has_possibly_aliasing() {
-            return Err("cannot borrow while possibly aliasing borrow exists".into());
+        if self.has_accessible() {
+            return Err("cannot borrow while accessible mutable borrow exists".into());
         }
 
         Ok(())
@@ -100,8 +100,8 @@ impl BorrowState {
     fn ensure_can_mut_ref(&self) -> Result<(), BorrowStateErr> {
         self.ensure_not_poisoned()?;
 
-        if self.has_possibly_aliasing() {
-            return Err("cannot borrow while possibly aliasing borrow exists".into());
+        if self.has_accessible() {
+            return Err("cannot borrow while accessible mutable borrow exists".into());
         }
 
         if self.shared_count != 0 {
@@ -116,7 +116,7 @@ impl BorrowState {
     /// Returns the new total number of shared references.
     ///
     /// This fails when:
-    /// - There exists a possibly aliasing mutable reference.
+    /// - There exists an accessible mutable reference.
     /// - There exist `usize::MAX` shared references.
     pub fn increment_shared(&mut self) -> Result<usize, BorrowStateErr> {
         self.ensure_not_poisoned()?;
@@ -144,8 +144,8 @@ impl BorrowState {
             return Err("cannot decrement shared counter when no shared reference exists".into());
         }
 
-        if self.has_possibly_aliasing() {
-            self.poison("shared reference tracked while aliasing mutable reference exists")?;
+        if self.has_accessible() {
+            self.poison("shared reference tracked while accessible mutable reference exists")?;
         }
 
         // We know `shared_count` isn't 0.
@@ -159,11 +159,11 @@ impl BorrowState {
     /// Returns the new total number of mutable references.
     ///
     /// This fails when:
-    /// - There exists a possibly aliasing mutable reference.
+    /// - There exists an accessible mutable reference.
     /// - There exists a shared reference.
     /// - There are `usize::MAX` tracked mutable references.
     ///
-    /// Any amount of shared references will prevent [`Self::increment_non_aliasing`] from succeeding.
+    /// Any amount of shared references will prevent [`Self::increment_inaccessible`] from succeeding.
     pub fn increment_mut(&mut self) -> Result<usize, BorrowStateErr> {
         self.ensure_not_poisoned()?;
 
@@ -183,7 +183,7 @@ impl BorrowState {
     ///
     /// This fails when:
     /// - There are currently no mutable references.
-    /// - There is a mutable reference, but it's guaranteed to be non-aliasing.
+    /// - There is a mutable reference, but it's inaccessible.
     pub fn decrement_mut(&mut self) -> Result<usize, BorrowStateErr> {
         self.ensure_not_poisoned()?;
 
@@ -191,15 +191,15 @@ impl BorrowState {
             return Err("cannot decrement mutable counter when no mutable reference exists".into());
         }
 
-        if self.mut_count == self.non_aliasing_count {
+        if self.mut_count == self.inaccessible_count {
             return Err(
-                "cannot decrement mutable counter when current mutable reference is non-aliasing"
+                "cannot decrement mutable counter when current mutable reference is inaccessible"
                     .into(),
             );
         }
 
-        if self.mut_count - 1 != self.non_aliasing_count {
-            self.poison("`non_aliasing_count` does not fit its invariant")?;
+        if self.mut_count - 1 != self.inaccessible_count {
+            self.poison("`inaccessible_count` does not fit its invariant")?;
         }
 
         // We know `mut_count` isn't 0.
@@ -208,53 +208,52 @@ impl BorrowState {
         Ok(self.mut_count)
     }
 
-    /// Set the current mutable reference as non-aliasing.
+    /// Set the current mutable reference as inaccessible.
     ///
-    /// Returns the new total of non-aliasing mutable references.
+    /// Returns the new total of inaccessible mutable references.
     ///
     /// Fails when:
     /// - There is no current
-    pub fn set_non_aliasing(&mut self) -> Result<usize, BorrowStateErr> {
-        if !self.has_possibly_aliasing() {
+    pub fn set_inaccessible(&mut self) -> Result<usize, BorrowStateErr> {
+        if !self.has_accessible() {
             return Err(
-                "cannot set current reference as non-aliasing when no possibly aliasing reference exists"
+                "cannot set current reference as inaccessible when no accessible reference exists"
                     .into(),
             );
         }
 
-        self.non_aliasing_count = self
-            .non_aliasing_count
+        self.inaccessible_count = self
+            .inaccessible_count
             .checked_add(1)
-            .ok_or("could not increment non-aliasing count")?;
+            .ok_or("could not increment inaccessible count")?;
 
-        Ok(self.non_aliasing_count)
+        Ok(self.inaccessible_count)
     }
 
-    pub fn unset_non_aliasing(&mut self) -> Result<usize, BorrowStateErr> {
-        if self.has_possibly_aliasing() {
-            return Err("cannot set current reference as possibly aliasing when possibly aliasing reference already exists".into());
+    pub fn unset_inaccessible(&mut self) -> Result<usize, BorrowStateErr> {
+        if self.has_accessible() {
+            return Err("cannot set current reference as accessible when an accessible mutable reference already exists".into());
         }
 
         if self.shared_count() > 0 {
             return Err(
-                "cannot set current reference as possibly aliasing when a shared reference exists"
-                    .into(),
+                "cannot set current reference as accessible when a shared reference exists".into(),
             );
         }
 
-        if self.non_aliasing_count == 0 {
+        if self.inaccessible_count == 0 {
             return Err(
-                "cannot mark mut pointer as aliasing when there are no possibly aliasing pointers"
+                "cannot mark mut pointer as accessible when there are no inaccessible pointers"
                     .into(),
             );
         }
 
-        self.non_aliasing_count = self
-            .non_aliasing_count
+        self.inaccessible_count = self
+            .inaccessible_count
             .checked_sub(1)
-            .ok_or("could not decrement non-aliasing count")?;
+            .ok_or("could not decrement inaccessible count")?;
 
-        Ok(self.non_aliasing_count)
+        Ok(self.inaccessible_count)
     }
 }
 
@@ -296,7 +295,7 @@ impl From<String> for BorrowStateErr {
 }
 
 #[cfg(all(test, not(miri)))]
-mod test {
+mod proptests {
     use super::*;
     use proptest::{arbitrary::Arbitrary, collection::vec, prelude::*};
 
@@ -312,8 +311,8 @@ mod test {
         DecShared,
         IncMut,
         DecMut,
-        SetNoAlias,
-        UnsetNoAlias,
+        SetInaccessible,
+        UnsetInaccessible,
     }
 
     impl Operation {
@@ -325,8 +324,8 @@ mod test {
                 Op::DecShared => state.decrement_shared(),
                 Op::IncMut => state.increment_mut(),
                 Op::DecMut => state.decrement_mut(),
-                Op::SetNoAlias => state.set_non_aliasing(),
-                Op::UnsetNoAlias => state.unset_non_aliasing(),
+                Op::SetInaccessible => state.set_inaccessible(),
+                Op::UnsetInaccessible => state.unset_inaccessible(),
             };
 
             result.map(|_| ())
@@ -342,8 +341,8 @@ mod test {
                 1 => Op::DecShared,
                 2 => Op::IncMut,
                 3 => Op::DecMut,
-                4 => Op::SetNoAlias,
-                5 => Op::UnsetNoAlias,
+                4 => Op::SetInaccessible,
+                5 => Op::UnsetInaccessible,
                 _ => unreachable!()
             }
         }
@@ -435,12 +434,12 @@ mod test {
                         original.mut_count -= 1;
                         original
                     },
-                    Op::SetNoAlias => |mut original: BorrowState| {
-                        original.non_aliasing_count += 1;
+                    Op::SetInaccessible => |mut original: BorrowState| {
+                        original.inaccessible_count += 1;
                         original
                     },
-                    Op::UnsetNoAlias => |mut original: BorrowState| {
-                        original.non_aliasing_count -= 1;
+                    Op::UnsetInaccessible => |mut original: BorrowState| {
+                        original.inaccessible_count -= 1;
                         original
                     },
                 };
@@ -477,7 +476,7 @@ mod test {
             for op in operations {
                 _ = op.execute(&mut state);
                 if state.has_shared_reference() {
-                    assert!(!state.has_possibly_aliasing())
+                    assert!(!state.has_accessible())
                 }
             }
         }
@@ -500,12 +499,12 @@ mod test {
 
     proptest! {
         #[test]
-        fn cannot_borrow_shared_when_borrowed_aliasing(operations in arbitrary_ops(50)) {
+        fn cannot_borrow_shared_when_borrowed_accessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if state.has_possibly_aliasing() {
+                if state.has_accessible() {
                     assert!(state.increment_shared().is_err());
                 }
             }
@@ -514,12 +513,12 @@ mod test {
 
     proptest! {
         #[test]
-        fn can_borrow_shared_when_not_borrowed_aliasing(operations in arbitrary_ops(50)) {
+        fn can_borrow_shared_when_not_borrowed_accessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if !state.has_possibly_aliasing() {
+                if !state.has_accessible() {
                     assert!(state.increment_shared().is_ok());
                     assert!(state.decrement_shared().is_ok());
                 }
@@ -529,12 +528,12 @@ mod test {
 
     proptest! {
         #[test]
-        fn can_borrow_mut_when_no_shared_and_no_aliasing(operations in arbitrary_ops(50)) {
+        fn can_borrow_mut_when_no_shared_and_no_accessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if !state.has_possibly_aliasing() && !state.has_shared_reference() {
+                if !state.has_accessible() && !state.has_shared_reference() {
                     assert!(state.increment_mut().is_ok());
                     assert!(state.decrement_mut().is_ok());
                 }
@@ -558,12 +557,12 @@ mod test {
 
     proptest! {
         #[test]
-        fn cannot_borrow_mut_when_has_aliasing(operations in arbitrary_ops(50)) {
+        fn cannot_borrow_mut_when_has_accessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if state.has_possibly_aliasing() {
+                if state.has_accessible() {
                     assert!(state.increment_mut().is_err());
                 }
             }
@@ -572,14 +571,14 @@ mod test {
 
     proptest! {
         #[test]
-        fn can_set_nonaliasing_when_aliasing(operations in arbitrary_ops(50)) {
+        fn can_set_inaccessible_when_accessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if state.has_possibly_aliasing() {
-                    assert!(state.set_non_aliasing().is_ok());
-                    assert!(state.unset_non_aliasing().is_ok());
+                if state.has_accessible() {
+                    assert!(state.set_inaccessible().is_ok());
+                    assert!(state.unset_inaccessible().is_ok());
                 }
             }
         }
@@ -587,13 +586,13 @@ mod test {
 
     proptest! {
         #[test]
-        fn cannot_set_nonaliasing_when_shared(operations in arbitrary_ops(50)) {
+        fn cannot_set_inaccessible_when_shared(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
                 if state.has_shared_reference() {
-                    assert!(state.set_non_aliasing().is_err());
+                    assert!(state.set_inaccessible().is_err());
                 }
             }
         }
@@ -601,13 +600,13 @@ mod test {
 
     proptest! {
         #[test]
-        fn cannot_set_nonaliasing_when_nonaliasing(operations in arbitrary_ops(50)) {
+        fn cannot_set_inaccessible_when_inaccessible(operations in arbitrary_ops(50)) {
             let mut state = BorrowState::new();
 
             for op in operations {
                 _ = op.execute(&mut state);
-                if !state.has_possibly_aliasing() {
-                    assert!(state.set_non_aliasing().is_err());
+                if !state.has_accessible() {
+                    assert!(state.set_inaccessible().is_err());
                 }
             }
         }
@@ -627,6 +626,11 @@ mod test {
             assert_eq!(state_all, state_no_shared_pairs);
         }
     }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
 
     #[test]
     fn poisoned_unset_shared_ref() {
@@ -635,11 +639,11 @@ mod test {
 
         _ = state.increment_mut();
         assert!(!state.is_poisoned());
-        _ = state.set_non_aliasing();
+        _ = state.set_inaccessible();
         assert!(!state.is_poisoned());
         _ = state.increment_shared();
         assert!(!state.is_poisoned());
-        _ = state.unset_non_aliasing();
+        _ = state.unset_inaccessible();
         assert!(!state.is_poisoned());
         _ = state.increment_shared();
         assert!(!state.is_poisoned());
diff --git a/godot-cell/src/guards.rs b/godot-cell/src/guards.rs
index 2c77f2ff9..c947ecc07 100644
--- a/godot-cell/src/guards.rs
+++ b/godot-cell/src/guards.rs
@@ -15,10 +15,13 @@ use crate::CellState;
 
 /// Wraps a shared borrowed value of type `T`.
 ///
-/// No other mutable borrows to the same value will be created while this guard exists.
+/// No mutable borrows to the same value can be created while this guard exists.
 #[derive(Debug)]
 pub struct RefGuard<'a, T> {
+    /// The current state of borrows to the borrowed value.
     state: &'a Mutex<CellState<T>>,
+
+    /// A pointer to the borrowed value.
     value: NonNull<T>,
 }
 
@@ -27,15 +30,16 @@ impl<'a, T> RefGuard<'a, T> {
     ///
     /// # Safety
     ///
-    /// It must be safe to call [`as_ref()`](NonNull::as_ref) on `value` for as long as the guard is not
-    /// dropped.
-    ///
-    /// In particular you must ensure that:
+    /// While the returned guard exists you must ensure that:
     ///
-    /// - The value behind the `value` pointer must be accessible for as long as the guard is not dropped.
+    /// - It is safe to access the value behind the `value` pointer through a shared reference derived from
+    ///   the `value` pointer.
     /// - No new mutable references to the same value can be created.
     /// - If there exist any other mutable references, then `value` must be derived from those references.
     /// - Any existing mutable references must stop accessing this value while this guard exists.
+    ///
+    /// These conditions ensure that it is safe to call [`as_ref()`](NonNull::as_ref) on `value` for as long
+    /// as the returned guard exists.
     pub(crate) unsafe fn new(state: &'a Mutex<CellState<T>>, value: NonNull<T>) -> Self {
         Self { state, value }
     }
@@ -65,8 +69,8 @@ impl<'a, T> Drop for RefGuard<'a, T> {
 
 /// Wraps a mutably borrowed value of type `T`.
 ///
-/// This prevents all other borrows of `value`, unless the `&mut` reference handed out from this guard is set
-/// as non-aliasing by a call to [`GdCell::set_non_aliasing()`](crate::GdCell::set_non_aliasing).
+/// This prevents all other borrows of `value`, unless the `&mut` reference handed out from this guard is
+/// made inaccessible by a call to [`GdCell::make_inaccessible()`](crate::GdCell::make_inaccessible).
 #[derive(Debug)]
 pub struct MutGuard<'a, T> {
     state: &'a Mutex<CellState<T>>,
@@ -75,32 +79,35 @@ pub struct MutGuard<'a, T> {
 }
 
 impl<'a, T> MutGuard<'a, T> {
-    /// Create a new `GdMut` guard which can be mutably dereferenced.
+    /// Create a new `MutGuard` guard which can be mutably dereferenced.
     ///
     /// # Safety
     ///
-    /// For as long as the guard lives:
-    ///
-    /// - It must be safe to call [`as_ref()`](NonNull::as_ref) on `value` when you have a shared reference to
-    ///   the guard.
-    /// - It must be safe to call [`as_mut()`](NonNull::as_mut) on `value` when you have a mutable reference
-    ///   to the guard.
+    /// While the returned guard exists and is accessible you must ensure that:
     ///
-    /// In particular you must ensure that until the guard is set as non-aliasing via a call to
-    /// [`GdCell::set_non_aliasing()`](crate::GdCell::set_non_aliasing), then:
-    ///
-    /// - The value behind the `value` pointer must be accessible for as long as the guard is not dropped.
+    /// - It is safe to access the value behind the `value` pointer through a shared or mutable reference
+    ///   derived from the `value` pointer.
     /// - No new references to `value` may be created.
     /// - If there exist any other mutable references, then `value` must be derived from those references.
     /// - Any existing mutable references must stop accessing this value while this guard exists.
     ///
-    /// When the guard is set as non-aliasing, then:
+    /// To make a `MutGuard` inaccessible, you must pass a `&mut T` reference from this guard to
+    /// [`GdCell::make_inaccessible()`](crate::GdCell::make_inaccessible).
     ///
-    /// - Any references handed out by this guard must stop accessing the value.
+    /// Together, these conditions ensure that it is safe to call [`as_ref()`](NonNull::as_ref) and
+    /// [`as_mut()`](NonNull::as_mut) on `value` whenever we have a `&self` or `&mut self` reference to the
+    /// guard.
     ///
-    /// This can be satisfied by using `deref_mut` to get a `&mut T` to the value, then making that reference
-    /// inaccessible for the duration that this guard is marked as non-aliasing. As the rust borrow checker
-    /// will prevent anyone from then using this guard until that reference is dropped.
+    /// This is the case because:
+    /// - [`GdCell`](super::GdCell) will not create any new references while this guard exists and is
+    ///   accessible.
+    /// - When it is marked as inaccessible it is impossible to have any `&self` or `&mut self` references to
+    ///   this guard that can be used. Because we take in a `&mut self` reference with a lifetime `'a` and
+    ///   return an [`InaccessibleGuard`] with a lifetime `'b` where `'a: 'b` which ensure that the
+    ///   `&mut self` outlives that guard and cannot be used until the guard is dropped. And the rust
+    ///   borrow-checker will prevent any new references from being made.
+    /// - When it is made inaccessible, [`GdCell`](super::GdCell) will also ensure that any new references
+    ///   are derived from this guard's `value` pointer, thus preventing `value` from being invalidated.
     pub(crate) unsafe fn new(
         state: &'a Mutex<CellState<T>>,
         count: usize,
@@ -124,6 +131,7 @@ impl<'a, T> Deref for MutGuard<'a, T> {
             self.count, count,
             "attempted to access the non-current mutable borrow. **this is a bug, please report it**"
         );
+
         // SAFETY:
         // It is safe to call `as_ref()` on value when we have a `&self` reference because of the safety
         // invariants of `new`.
@@ -160,26 +168,53 @@ impl<'a, T> Drop for MutGuard<'a, T> {
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
-/// A guard that ensures a mutable reference is kept inaccessible until it is dropped. At which point the
-/// borrow-state is set to prevent aliasing for the most recent borrow and the pointer in state is set to the
-/// previous pointer.
+/// A guard that ensures a mutable reference is kept inaccessible until it is dropped.
+///
+/// The current reference is stored in the guard and we push a new reference to `state` on creation. We then
+/// undo this upon dropping the guard.
+///
+/// This ensure that any new references are derived from the new reference we pass in, and when this guard is
+/// dropped we reset it to the previous reference.
 #[derive(Debug)]
-pub struct NonAliasingGuard<'a, T> {
+pub struct InaccessibleGuard<'a, T> {
     state: &'a Mutex<CellState<T>>,
     prev_ptr: NonNull<T>,
 }
 
-impl<'a, T> NonAliasingGuard<'a, T> {
-    /// Create a new non-aliasing guard for `state`.
-    pub(crate) fn new(state: &'a Mutex<CellState<T>>, prev_ptr: NonNull<T>) -> Self {
-        Self { state, prev_ptr }
+impl<'a, T> InaccessibleGuard<'a, T> {
+    /// Create a new inaccessible guard for `state`.
+    ///
+    /// Since `'b` must outlive `'a`, we cannot have any other references aliasing `new_ref` while this
+    /// guard exists.
+    pub(crate) fn new<'b>(
+        state: &'a Mutex<CellState<T>>,
+        new_ref: &'b mut T,
+    ) -> Result<Self, Box<dyn std::error::Error>>
+    where
+        'a: 'b,
+    {
+        let mut guard = state.lock().unwrap();
+
+        let current_ptr = guard.get_ptr();
+        let new_ptr = NonNull::from(new_ref);
+
+        if current_ptr != new_ptr {
+            // it is likely not unsound for this to happen, but it's unexpected
+            return Err("wrong reference passed in".into());
+        }
+
+        guard.borrow_state.set_inaccessible()?;
+        let prev_ptr = guard.get_ptr();
+        guard.set_ptr(new_ptr);
+
+        Ok(Self { state, prev_ptr })
     }
 }
 
-impl<'a, T> Drop for NonAliasingGuard<'a, T> {
+impl<'a, T> Drop for InaccessibleGuard<'a, T> {
     fn drop(&mut self) {
         let mut state = self.state.lock().unwrap();
-        state.borrow_state.unset_non_aliasing().unwrap();
+        state.borrow_state.unset_inaccessible().unwrap();
         state.set_ptr(self.prev_ptr);
     }
 }
diff --git a/godot-cell/src/lib.rs b/godot-cell/src/lib.rs
index 2f9ec9e5d..0d6f264a2 100644
--- a/godot-cell/src/lib.rs
+++ b/godot-cell/src/lib.rs
@@ -5,11 +5,21 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-//! A re-entrant cell implementation which allows for `&mut` references to be re-taken even while `&mut`
+//! A re-entrant cell implementation which allows for `&mut` references to be re-borrowed even while `&mut`
 //! references still exist.
 //!
 //! This is done by ensuring any existing `&mut` references cannot alias the new reference, and that the new
 //! reference is derived from the previous one.
+//!
+//! This emulates rust's system for function calls. i.e `my_func(&mut borrowed)` creates a second `&mut`
+//! reference inside the function.
+//!
+//! Instead of directly using the concept of `aliasing` pointers, we use the term `accessible` instead. A
+//! reference (or other pointer) to some value is considered accessible when it is possible to either read
+//! from or write to the value it points to without using `unsafe`. Importantly, if we know that a reference
+//! `a` is inaccessible, and then we create a new reference `b` to the same value, then we know for sure that
+//! `b` wont alias `a`. This is because aliasing in rust is based on accesses, and if we never access `a`
+//! then we cannot ever violate aliasing for `a` and `b`.
 
 mod borrow_state;
 mod guards;
@@ -22,10 +32,10 @@ use std::ptr::NonNull;
 use std::sync::Mutex;
 
 use borrow_state::BorrowState;
-pub use guards::{MutGuard, NonAliasingGuard, RefGuard};
+pub use guards::{InaccessibleGuard, MutGuard, RefGuard};
 
-/// A cell which can hand out new `&mut` references to it's value even when one already exists, as long as
-/// any pre-existing such references have been handed back to the cell first, and no shared references exist.
+/// A cell which can hand out new `&mut` references to its value even when one already exists, as long as
+/// any such pre-existing references have been handed back to the cell first, and no shared references exist.
 ///
 /// This cell must be pinned to be usable, as it stores self-referential pointers.
 // TODO: consider not using `Mutex`
@@ -56,19 +66,19 @@ impl<T> GdCell<T> {
 
     /// Returns a new shared reference to the contents of the cell.
     ///
-    /// Fails if an aliasing mutable reference exists.
+    /// Fails if an accessible mutable reference exists.
     pub fn borrow(self: Pin<&Self>) -> Result<RefGuard<'_, T>, Box<dyn Error>> {
         let mut state = self.state.lock().unwrap();
         state.borrow_state.increment_shared()?;
 
         // SAFETY:
-        // `increment_shared` succeeded, therefore there cannot currently be any aliasing mutable references.
+        // `increment_shared` succeeded, therefore there cannot currently be any accessible mutable references.
         unsafe { Ok(RefGuard::new(&self.get_ref().state, state.get_ptr())) }
     }
 
-    /// Returns a new shared reference to the contents of the cell.
+    /// Returns a new mutable reference to the contents of the cell.
     ///
-    /// Fails if an aliasing mutable reference exists, or a shared reference exists.
+    /// Fails if an accessible mutable reference exists, or a shared reference exists.
     pub fn borrow_mut(self: Pin<&Self>) -> Result<MutGuard<'_, T>, Box<dyn Error>> {
         let mut state = self.state.lock().unwrap();
         state.borrow_state.increment_mut()?;
@@ -76,52 +86,36 @@ impl<T> GdCell<T> {
         let value = state.get_ptr();
 
         // SAFETY:
-        // `increment_mut` succeeded, therefore any existing mutable references do not alias, and no new
-        // references may be made unless this one is guaranteed not to alias those.
+        // `increment_mut` succeeded, therefore any existing mutable references are inaccessible.
+        // Additionally no new references can be created, unless the returned guard is made inaccessible.
         //
         // This is the case because the only way for a new `GdMut` or `GdRef` to be made after this, is for
-        // either this guard to be dropped or `set_non_aliasing` to be called.
+        // either this guard to be dropped or `make_inaccessible` to be called.
         //
         // If this guard is dropped, then we dont need to worry.
         //
-        // If `set_non_aliasing` is called, then either a mutable reference from this guard is passed in.
-        // In which case, we cannot use this guard again until the resulting non-aliasing guard is dropped.
+        // If `make_inaccessible` is called, then either a mutable reference from this guard is passed in.
+        // In which case, we cannot use this guard again until the resulting inaccessible guard is dropped.
         //
-        // We cannot pass in a different mutable reference, since `set_non_aliasing` ensures any references
+        // We cannot pass in a different mutable reference, since `make_inaccessible` ensures any references
         // matches the ones this one would return. And only one mutable reference to the same value can exist
         // since we cannot have any other aliasing mutable references around to pass in.
         unsafe { Ok(MutGuard::new(&self.get_ref().state, count, value)) }
     }
 
-    /// Set the current mutable borrow as not aliasing any other references.
+    /// Make the current mutable borrow inaccessible, thus freeing the value up to be reborrowed again.
     ///
-    /// Will error if there is no current possibly aliasing mutable borrow, or if there are any shared
+    /// Will error if there is no current accessible mutable borrow, or if there are any shared
     /// references.
-    pub fn set_non_aliasing<'a, 'b>(
+    pub fn make_inaccessible<'a: 'b, 'b>(
         self: Pin<&'a Self>,
         current_ref: &'b mut T,
-    ) -> Result<NonAliasingGuard<'b, T>, Box<dyn Error>>
-    where
-        'a: 'b,
-    {
-        let mut state = self.state.lock().unwrap();
-        let current_ptr = state.get_ptr();
-        let ptr = NonNull::from(current_ref);
-
-        if current_ptr != ptr {
-            // it is likely not unsound for this to happen, but it's unexpected
-            return Err("wrong reference passed in".into());
-        }
-
-        state.borrow_state.set_non_aliasing()?;
-        let old_ptr = state.get_ptr();
-        state.set_ptr(ptr);
-
-        Ok(NonAliasingGuard::new(&self.get_ref().state, old_ptr))
+    ) -> Result<InaccessibleGuard<'b, T>, Box<dyn Error>> {
+        InaccessibleGuard::new(&self.get_ref().state, current_ref)
     }
 
     /// Returns `true` if there are any mutable or shared references, regardless of whether the mutable
-    /// references are aliasing or not.
+    /// references are accessible or not.
     ///
     /// In particular this means that it is safe to destroy this cell and the value contained within, as no
     /// references can exist that can reference this cell.
@@ -148,14 +142,15 @@ unsafe impl<T: Sync> Sync for GdCell<T> {}
 struct CellState<T> {
     /// Tracking the borrows this cell has. This ensures relevant invariants are upheld.
     borrow_state: BorrowState,
+
     /// Current pointer to the value.
     ///
-    /// This is initialized upon first usage, as we cannot construct the cell pinned in general.
+    /// This is an `Option` as we must initialize the value after pinning it.
     ///
     /// When a reference is handed to a cell to enable re-entrancy, then this pointer is set to that
     /// reference.
     ///
-    /// We always generate new pointer based off of the reference currently in this field, to ensure any new
+    /// We always generate new pointer based off of the pointer currently in this field, to ensure any new
     /// references are derived from the most recent `&mut` reference.
     ptr: Option<NonNull<T>>,
 }
@@ -247,7 +242,7 @@ mod test {
     }
 
     #[test]
-    fn allow_non_aliasing_mut_mut() {
+    fn allow_inaccessible_mut_mut() {
         const VAL: i32 = 23456;
         let cell = GdCell::new(VAL);
         let cell = cell.as_ref();
@@ -257,7 +252,7 @@ mod test {
         assert_eq!(*mut1, VAL);
         *mut1 = VAL + 50;
 
-        let no_alias_guard = cell.set_non_aliasing(mut1).unwrap();
+        let inaccessible_guard = cell.make_inaccessible(mut1).unwrap();
 
         let mut guard2 = cell.borrow_mut().unwrap();
         let mut2 = &mut *guard2;
@@ -265,7 +260,7 @@ mod test {
         *mut2 = VAL - 30;
         drop(guard2);
 
-        drop(no_alias_guard);
+        drop(inaccessible_guard);
 
         assert_eq!(*mut1, VAL - 30);
         *mut1 = VAL - 5;
@@ -277,26 +272,7 @@ mod test {
     }
 
     #[test]
-    fn prevent_mut_mut_without_non_aliasing() {
-        const VAL: i32 = 23456;
-        let cell = GdCell::new(VAL);
-        let cell = cell.as_ref();
-
-        let mut guard1 = cell.borrow_mut().unwrap();
-        let mut1 = &mut *guard1;
-        assert_eq!(*mut1, VAL);
-        *mut1 = VAL + 50;
-
-        // let no_alias_guard = cell.set_non_aliasing(mut1).unwrap();
-
-        cell.borrow_mut()
-            .expect_err("reference may be aliasing so should be prevented");
-
-        drop(guard1);
-    }
-
-    #[test]
-    fn different_non_aliasing() {
+    fn different_inaccessible() {
         const VAL1: i32 = 23456;
         const VAL2: i32 = 11111;
         let cell1 = GdCell::new(VAL1);
@@ -316,11 +292,11 @@ mod test {
         assert_eq!(*mut2, VAL2);
         *mut2 = VAL2 + 10;
 
-        let no_alias_guard = cell1
-            .set_non_aliasing(mut2)
+        let inaccessible_guard = cell1
+            .make_inaccessible(mut2)
             .expect_err("should not allow different references");
 
-        drop(no_alias_guard);
+        drop(inaccessible_guard);
 
         drop(guard1);
         drop(guard2);
diff --git a/godot-cell/tests/mock.rs b/godot-cell/tests/mock.rs
index e3907bd33..c991054a7 100644
--- a/godot-cell/tests/mock.rs
+++ b/godot-cell/tests/mock.rs
@@ -15,7 +15,7 @@ use std::marker::PhantomData;
 use std::pin::Pin;
 use std::sync::{atomic::AtomicUsize, Mutex, OnceLock};
 
-use godot_cell::{GdCell, NonAliasingGuard};
+use godot_cell::{GdCell, InaccessibleGuard};
 
 struct InstanceBinding(*mut ());
 
@@ -105,14 +105,14 @@ impl<T> Base<T> {
 
 struct BaseGuard<'a, T> {
     instance_id: usize,
-    _non_aliasing_guard: NonAliasingGuard<'a, T>,
+    _inaccessible_guard: InaccessibleGuard<'a, T>,
 }
 
 impl<'a, T> BaseGuard<'a, T> {
-    fn new(instance_id: usize, non_aliasing_guard: NonAliasingGuard<'a, T>) -> Self {
+    fn new(instance_id: usize, inaccessible_guard: InaccessibleGuard<'a, T>) -> Self {
         Self {
             instance_id,
-            _non_aliasing_guard: non_aliasing_guard,
+            _inaccessible_guard: inaccessible_guard,
         }
     }
 
@@ -201,7 +201,7 @@ impl MyClass {
 
     fn base(&mut self) -> BaseGuard<'_, Self> {
         let cell = self.base.cell();
-        BaseGuard::new(self.base.instance_id, cell.set_non_aliasing(self).unwrap())
+        BaseGuard::new(self.base.instance_id, cell.make_inaccessible(self).unwrap())
     }
 }
 
diff --git a/godot-core/src/storage/multi_threaded.rs b/godot-core/src/storage/multi_threaded.rs
index 3b034c768..480788e86 100644
--- a/godot-core/src/storage/multi_threaded.rs
+++ b/godot-core/src/storage/multi_threaded.rs
@@ -38,7 +38,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
 
     type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
 
-    type BaseMutGuard<'a> = godot_cell::NonAliasingGuard<'a, T>;
+    type BaseMutGuard<'a> = godot_cell::InaccessibleGuard<'a, T>;
 
     fn construct(
         user_instance: Self::Instance,
@@ -93,7 +93,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
         self.user_instance
             .as_ref()
-            .set_non_aliasing(value)
+            .make_inaccessible(value)
             .unwrap_or_else(|err| {
                 // We should never hit this, except maybe in extreme cases like having more than
                 // `usize::MAX` borrows.
diff --git a/godot-core/src/storage/single_threaded.rs b/godot-core/src/storage/single_threaded.rs
index 6042b6c12..329578def 100644
--- a/godot-core/src/storage/single_threaded.rs
+++ b/godot-core/src/storage/single_threaded.rs
@@ -38,7 +38,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
 
     type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
 
-    type BaseMutGuard<'a> = godot_cell::NonAliasingGuard<'a, T>;
+    type BaseMutGuard<'a> = godot_cell::InaccessibleGuard<'a, T>;
 
     fn construct(
         user_instance: Self::Instance,
@@ -93,7 +93,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
         self.user_instance
             .as_ref()
-            .set_non_aliasing(value)
+            .make_inaccessible(value)
             .unwrap_or_else(|err| {
                 // We should never hit this, except maybe in extreme cases like having more than
                 // `usize::MAX` borrows.

From 684251db723ff58d2fa9997ec0876fcee0dec324 Mon Sep 17 00:00:00 2001
From: Lili Zoey Zyli <sayaks1@gmail.com>
Date: Tue, 2 Jan 2024 17:52:56 +0100
Subject: [PATCH 5/7] - Make `proptest` a conditional dependency - Add
 multi-threaded tests for godot-cell - Add blocking drop method for
 InaccessibleGuard - Fix UB when InaccessibleGuard is blocking dropped in the
 wrong order in multi-threaded code

---
 .github/workflows/full-ci.yml             |  14 +
 godot-cell/Cargo.toml                     |   7 +-
 godot-cell/src/borrow_state.rs            |   8 +-
 godot-cell/src/guards.rs                  | 116 ++++++--
 godot-cell/src/lib.rs                     |  86 +++---
 godot-cell/tests/mock.rs                  | 312 +++++++++++++++-------
 godot-core/src/obj/guards.rs              |   9 +-
 godot-core/src/obj/traits.rs              |   2 +-
 godot-core/src/storage.rs                 |  30 +--
 godot-core/src/storage/multi_threaded.rs  |  15 +-
 godot-core/src/storage/single_threaded.rs |  15 +-
 11 files changed, 405 insertions(+), 209 deletions(-)

diff --git a/.github/workflows/full-ci.yml b/.github/workflows/full-ci.yml
index 231ee2398..5e61f224c 100644
--- a/.github/workflows/full-ci.yml
+++ b/.github/workflows/full-ci.yml
@@ -178,6 +178,20 @@ jobs:
       - name: "Test tree borrows"
         run: MIRIFLAGS="-Zmiri-tree-borrows" cargo miri test -p godot-cell
 
+  proptest:
+    name: proptest
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Install Rust"
+        uses: ./.github/composite/rust
+
+      - name: "Compile tests"
+        run: cargo test -p godot-cell --features="proptest" --no-run
+
+      - name: "Test"
+        run: cargo test -p godot-cell --features="proptest"
 
   # For complex matrix workflow, see https://stackoverflow.com/a/65434401
   godot-itest:
diff --git a/godot-cell/Cargo.toml b/godot-cell/Cargo.toml
index 2cb8aebb5..d94592469 100644
--- a/godot-cell/Cargo.toml
+++ b/godot-cell/Cargo.toml
@@ -3,5 +3,8 @@ name = "godot-cell"
 version = "0.1.0"
 edition = "2021"
 
-[dev-dependencies]
-proptest = "1.4.0"
+[features]
+proptest = ["dep:proptest"]
+
+[dependencies]
+proptest = { version = "1.4.0", optional = true }
diff --git a/godot-cell/src/borrow_state.rs b/godot-cell/src/borrow_state.rs
index 5fed93fe7..a4545eeb9 100644
--- a/godot-cell/src/borrow_state.rs
+++ b/godot-cell/src/borrow_state.rs
@@ -73,7 +73,7 @@ impl BorrowState {
     /// Set self as having reached an erroneous or unreliable state.
     ///
     /// Always returns [`BorrowStateErr::Poisoned`].
-    fn poison(&mut self, err: impl Into<String>) -> Result<(), BorrowStateErr> {
+    pub(crate) fn poison(&mut self, err: impl Into<String>) -> Result<(), BorrowStateErr> {
         self.poisoned = true;
 
         Err(BorrowStateErr::Poisoned(err.into()))
@@ -230,6 +230,10 @@ impl BorrowState {
         Ok(self.inaccessible_count)
     }
 
+    pub(crate) fn may_unset_inaccessible(&self) -> bool {
+        !self.has_accessible() && self.shared_count() == 0 && self.inaccessible_count > 0
+    }
+
     pub fn unset_inaccessible(&mut self) -> Result<usize, BorrowStateErr> {
         if self.has_accessible() {
             return Err("cannot set current reference as accessible when an accessible mutable reference already exists".into());
@@ -294,7 +298,7 @@ impl From<String> for BorrowStateErr {
     }
 }
 
-#[cfg(all(test, not(miri)))]
+#[cfg(all(test, feature = "proptest"))]
 mod proptests {
     use super::*;
     use proptest::{arbitrary::Arbitrary, collection::vec, prelude::*};
diff --git a/godot-cell/src/guards.rs b/godot-cell/src/guards.rs
index c947ecc07..815c136bd 100644
--- a/godot-cell/src/guards.rs
+++ b/godot-cell/src/guards.rs
@@ -7,7 +7,7 @@
 
 use std::ops::{Deref, DerefMut};
 use std::ptr::NonNull;
-use std::sync::Mutex;
+use std::sync::{Mutex, MutexGuard};
 
 use crate::CellState;
 
@@ -69,8 +69,9 @@ impl<'a, T> Drop for RefGuard<'a, T> {
 
 /// Wraps a mutably borrowed value of type `T`.
 ///
-/// This prevents all other borrows of `value`, unless the `&mut` reference handed out from this guard is
-/// made inaccessible by a call to [`GdCell::make_inaccessible()`](crate::GdCell::make_inaccessible).
+/// This prevents all other borrows of `value` while this guard is accessible. To make this guard
+/// inaccessible, use [`GdCell::make_inaccessible()`](crate::GdCell::make_inaccessible) on a mutable
+/// reference handed out by this guard.
 #[derive(Debug)]
 pub struct MutGuard<'a, T> {
     state: &'a Mutex<CellState<T>>,
@@ -101,11 +102,11 @@ impl<'a, T> MutGuard<'a, T> {
     /// This is the case because:
     /// - [`GdCell`](super::GdCell) will not create any new references while this guard exists and is
     ///   accessible.
-    /// - When it is marked as inaccessible it is impossible to have any `&self` or `&mut self` references to
-    ///   this guard that can be used. Because we take in a `&mut self` reference with a lifetime `'a` and
-    ///   return an [`InaccessibleGuard`] with a lifetime `'b` where `'a: 'b` which ensure that the
-    ///   `&mut self` outlives that guard and cannot be used until the guard is dropped. And the rust
-    ///   borrow-checker will prevent any new references from being made.
+    /// - When it is made inaccessible it is impossible to have any `&self` or `&mut self` references to this
+    ///   guard that can be used. Because we take in a `&mut self` reference with a lifetime `'a` and return
+    ///   an [`InaccessibleGuard`] with a lifetime `'b` where `'a: 'b` which ensure that the `&mut self`
+    ///   outlives that guard and cannot be used until the guard is dropped. And the rust borrow-checker will
+    ///   prevent any new references from being made.
     /// - When it is made inaccessible, [`GdCell`](super::GdCell) will also ensure that any new references
     ///   are derived from this guard's `value` pointer, thus preventing `value` from being invalidated.
     pub(crate) unsafe fn new(
@@ -128,13 +129,23 @@ impl<'a, T> Deref for MutGuard<'a, T> {
         let count = self.state.lock().unwrap().borrow_state.mut_count();
         // This is just a best-effort error check. It should never be triggered.
         assert_eq!(
-            self.count, count,
-            "attempted to access the non-current mutable borrow. **this is a bug, please report it**"
+            self.count,
+            count,
+            "\
+            attempted to access a non-current mutable borrow of type: `{}`. \n\
+            current count: {}\n\
+            value pointer: {:p}\n\
+            attempted access count: {}\n\
+            **this is a bug, please report it**\
+            ",
+            std::any::type_name::<T>(),
+            self.count,
+            self.value,
+            count
         );
 
-        // SAFETY:
-        // It is safe to call `as_ref()` on value when we have a `&self` reference because of the safety
-        // invariants of `new`.
+        // SAFETY: It is safe to call `as_ref()` on value when we have a `&self` reference because of the
+        // safety invariants of `new`.
         unsafe { self.value.as_ref() }
     }
 }
@@ -144,8 +155,19 @@ impl<'a, T> DerefMut for MutGuard<'a, T> {
         let count = self.state.lock().unwrap().borrow_state.mut_count();
         // This is just a best-effort error check. It should never be triggered.
         assert_eq!(
-            self.count, count,
-            "attempted to access the non-current mutable borrow. **this is a bug, please report it**"
+            self.count,
+            count,
+            "\
+            attempted to access a non-current mutable borrow of type: `{}`. \n\
+            current count: {}\n\
+            value pointer: {:p}\n\
+            attempted access count: {}\n\
+            **this is a bug, please report it**\
+            ",
+            std::any::type_name::<T>(),
+            self.count,
+            self.value,
+            count
         );
 
         // SAFETY:
@@ -170,14 +192,15 @@ impl<'a, T> Drop for MutGuard<'a, T> {
 
 /// A guard that ensures a mutable reference is kept inaccessible until it is dropped.
 ///
-/// The current reference is stored in the guard and we push a new reference to `state` on creation. We then
-/// undo this upon dropping the guard.
+/// We store the current reference in the guard upon creation, and push a new reference to `state` on
+/// creation. When the guard is dropped, `state`'s pointer is reset to the original pointer.
 ///
-/// This ensure that any new references are derived from the new reference we pass in, and when this guard is
-/// dropped we reset it to the previous reference.
+/// This ensures that any new references are derived from the new reference we pass in, and when this guard
+/// is dropped the state is reset to what it was before, as if this guard never existed.
 #[derive(Debug)]
 pub struct InaccessibleGuard<'a, T> {
     state: &'a Mutex<CellState<T>>,
+    stack_depth: usize,
     prev_ptr: NonNull<T>,
 }
 
@@ -185,7 +208,13 @@ impl<'a, T> InaccessibleGuard<'a, T> {
     /// Create a new inaccessible guard for `state`.
     ///
     /// Since `'b` must outlive `'a`, we cannot have any other references aliasing `new_ref` while this
-    /// guard exists.
+    /// guard exists. So this guard ensures that the guard that handed out `new_ref` is inaccessible while
+    /// this guard exists.
+    ///
+    /// Will error if:
+    /// - There is currently no accessible mutable borrow.
+    /// - There are any shared references.
+    /// - `new_ref` is not equal to the pointer in `state`.
     pub(crate) fn new<'b>(
         state: &'a Mutex<CellState<T>>,
         new_ref: &'b mut T,
@@ -205,16 +234,53 @@ impl<'a, T> InaccessibleGuard<'a, T> {
 
         guard.borrow_state.set_inaccessible()?;
         let prev_ptr = guard.get_ptr();
-        guard.set_ptr(new_ptr);
+        let stack_depth = guard.push_ptr(new_ptr);
+
+        Ok(Self {
+            state,
+            stack_depth,
+            prev_ptr,
+        })
+    }
 
-        Ok(Self { state, prev_ptr })
+    /// Single implementation of drop-logic for use in both drop implementations.
+    fn perform_drop(
+        mut state: MutexGuard<'_, CellState<T>>,
+        prev_ptr: NonNull<T>,
+        stack_depth: usize,
+    ) {
+        if state.stack_depth != stack_depth {
+            state
+                .borrow_state
+                .poison("cannot drop inaccessible guards in the wrong order")
+                .unwrap();
+        }
+        state.borrow_state.unset_inaccessible().unwrap();
+        state.pop_ptr(prev_ptr);
+    }
+
+    /// Drop self if possible, otherwise returns self again.
+    ///
+    /// Used currently in the mock-tests, as we need a thread safe way to drop self. Using the normal drop
+    /// logic may poison state, however it should not cause any UB either way.
+    #[doc(hidden)]
+    pub fn try_drop(self) -> Result<(), std::mem::ManuallyDrop<Self>> {
+        let manual = std::mem::ManuallyDrop::new(self);
+        let state = manual.state.lock().unwrap();
+        if !state.borrow_state.may_unset_inaccessible() || state.stack_depth != manual.stack_depth {
+            return Err(manual);
+        }
+        Self::perform_drop(state, manual.prev_ptr, manual.stack_depth);
+
+        Ok(())
     }
 }
 
 impl<'a, T> Drop for InaccessibleGuard<'a, T> {
     fn drop(&mut self) {
-        let mut state = self.state.lock().unwrap();
-        state.borrow_state.unset_inaccessible().unwrap();
-        state.set_ptr(self.prev_ptr);
+        // Default behavior of drop-logic simply panics and poisons the cell on failure. This is appropriate
+        // for single-threaded code where no errors should happen here.
+        let state = self.state.lock().unwrap();
+        Self::perform_drop(state, self.prev_ptr, self.stack_depth);
     }
 }
diff --git a/godot-cell/src/lib.rs b/godot-cell/src/lib.rs
index 0d6f264a2..1677454e0 100644
--- a/godot-cell/src/lib.rs
+++ b/godot-cell/src/lib.rs
@@ -5,7 +5,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-//! A re-entrant cell implementation which allows for `&mut` references to be re-borrowed even while `&mut`
+//! A re-entrant cell implementation which allows for `&mut` references to be reborrowed even while `&mut`
 //! references still exist.
 //!
 //! This is done by ensuring any existing `&mut` references cannot alias the new reference, and that the new
@@ -17,9 +17,11 @@
 //! Instead of directly using the concept of `aliasing` pointers, we use the term `accessible` instead. A
 //! reference (or other pointer) to some value is considered accessible when it is possible to either read
 //! from or write to the value it points to without using `unsafe`. Importantly, if we know that a reference
-//! `a` is inaccessible, and then we create a new reference `b` to the same value, then we know for sure that
-//! `b` wont alias `a`. This is because aliasing in rust is based on accesses, and if we never access `a`
-//! then we cannot ever violate aliasing for `a` and `b`.
+//! `a` is inaccessible, and then we create a new reference `b` derived from `a` to the same value, then we
+//! know for sure that `b` wont alias `a`. This is because aliasing in rust is based on accesses, and if we
+//! never access `a` then we cannot ever violate aliasing for `a` and `b`. And since `b` is derived from `a`
+//! (that is, `b` was created from `a` somehow such as by casting `a` to a raw pointer then to a reference
+//! `b`), then `a` wont get invalidated by accesses to `b`.
 
 mod borrow_state;
 mod guards;
@@ -34,7 +36,7 @@ use std::sync::Mutex;
 use borrow_state::BorrowState;
 pub use guards::{InaccessibleGuard, MutGuard, RefGuard};
 
-/// A cell which can hand out new `&mut` references to its value even when one already exists, as long as
+/// A cell which can hand out new `&mut` references to its value even when one already exists. As long as
 /// any such pre-existing references have been handed back to the cell first, and no shared references exist.
 ///
 /// This cell must be pinned to be usable, as it stores self-referential pointers.
@@ -71,8 +73,8 @@ impl<T> GdCell<T> {
         let mut state = self.state.lock().unwrap();
         state.borrow_state.increment_shared()?;
 
-        // SAFETY:
-        // `increment_shared` succeeded, therefore there cannot currently be any accessible mutable references.
+        // SAFETY: `increment_shared` succeeded, therefore there cannot currently be any accessible mutable
+        // references.
         unsafe { Ok(RefGuard::new(&self.get_ref().state, state.get_ptr())) }
     }
 
@@ -85,32 +87,30 @@ impl<T> GdCell<T> {
         let count = state.borrow_state.mut_count();
         let value = state.get_ptr();
 
-        // SAFETY:
-        // `increment_mut` succeeded, therefore any existing mutable references are inaccessible.
+        // SAFETY: `increment_mut` succeeded, therefore any existing mutable references are inaccessible.
         // Additionally no new references can be created, unless the returned guard is made inaccessible.
         //
-        // This is the case because the only way for a new `GdMut` or `GdRef` to be made after this, is for
-        // either this guard to be dropped or `make_inaccessible` to be called.
+        // This is the case because the only way for a new `GdMut` or `GdRef` to be made after this is for
+        // either this guard to be dropped or `make_inaccessible` to be called and succeed.
         //
         // If this guard is dropped, then we dont need to worry.
         //
-        // If `make_inaccessible` is called, then either a mutable reference from this guard is passed in.
-        // In which case, we cannot use this guard again until the resulting inaccessible guard is dropped.
-        //
-        // We cannot pass in a different mutable reference, since `make_inaccessible` ensures any references
-        // matches the ones this one would return. And only one mutable reference to the same value can exist
-        // since we cannot have any other aliasing mutable references around to pass in.
+        // If `make_inaccessible` is called and succeeds, then a mutable reference from this guard is passed
+        // in. In which case, we cannot use this guard again until the resulting inaccessible guard is
+        // dropped.
         unsafe { Ok(MutGuard::new(&self.get_ref().state, count, value)) }
     }
 
     /// Make the current mutable borrow inaccessible, thus freeing the value up to be reborrowed again.
     ///
-    /// Will error if there is no current accessible mutable borrow, or if there are any shared
-    /// references.
-    pub fn make_inaccessible<'a: 'b, 'b>(
-        self: Pin<&'a Self>,
-        current_ref: &'b mut T,
-    ) -> Result<InaccessibleGuard<'b, T>, Box<dyn Error>> {
+    /// Will error if:
+    /// - There is currently no accessible mutable borrow.
+    /// - There are any shared references.
+    /// - `current_ref` is not equal to the pointer in `self.state`.
+    pub fn make_inaccessible<'cell: 'val, 'val>(
+        self: Pin<&'cell Self>,
+        current_ref: &'val mut T,
+    ) -> Result<InaccessibleGuard<'val, T>, Box<dyn Error>> {
         InaccessibleGuard::new(&self.get_ref().state, current_ref)
     }
 
@@ -130,8 +130,7 @@ impl<T> GdCell<T> {
     }
 }
 
-// SAFETY:
-// `T` is sync so we can return references to it on different threads.
+// SAFETY: `T` is sync so we can return references to it on different threads.
 // Additionally all internal state is synchronized via a mutex, so we wont have race conditions when trying
 // to use it from multiple threads.
 unsafe impl<T: Sync> Sync for GdCell<T> {}
@@ -145,14 +144,20 @@ struct CellState<T> {
 
     /// Current pointer to the value.
     ///
-    /// This is an `Option` as we must initialize the value after pinning it.
+    /// This will always be non-null after initialization.
     ///
-    /// When a reference is handed to a cell to enable re-entrancy, then this pointer is set to that
+    /// When a reference is handed to a cell to enable reborrowing, then this pointer is set to that
     /// reference.
     ///
     /// We always generate new pointer based off of the pointer currently in this field, to ensure any new
     /// references are derived from the most recent `&mut` reference.
-    ptr: Option<NonNull<T>>,
+    // TODO: Consider using `NonNull<T>` instead.
+    ptr: *mut T,
+
+    /// How many pointers have been handed out.
+    ///
+    /// This is used to ensure that the pointers are not replaced in the wrong order.
+    stack_depth: usize,
 }
 
 impl<T> CellState<T> {
@@ -161,14 +166,16 @@ impl<T> CellState<T> {
     fn new() -> Self {
         Self {
             borrow_state: BorrowState::new(),
-            ptr: None,
+            ptr: std::ptr::null_mut(),
+            stack_depth: 0,
         }
     }
 
     /// Initialize the pointer if it is `None`.
     fn initialize_ptr(&mut self, value: &UnsafeCell<T>) {
-        if self.ptr.is_none() {
-            self.set_ptr(NonNull::new(value.get()).unwrap());
+        if self.ptr.is_null() {
+            self.ptr = value.get();
+            assert!(!self.ptr.is_null());
         } else {
             panic!("Cannot initialize pointer as it is already initialized.")
         }
@@ -176,12 +183,21 @@ impl<T> CellState<T> {
 
     /// Returns the current pointer. Panics if uninitialized.
     fn get_ptr(&self) -> NonNull<T> {
-        self.ptr.unwrap()
+        NonNull::new(self.ptr).unwrap()
+    }
+
+    /// Push a pointer to this state..
+    fn push_ptr(&mut self, new_ptr: NonNull<T>) -> usize {
+        self.ptr = new_ptr.as_ptr();
+        self.stack_depth += 1;
+        self.stack_depth
     }
 
-    /// Set the current pointer to the new pointer.
-    fn set_ptr(&mut self, new_ptr: NonNull<T>) {
-        self.ptr = Some(new_ptr);
+    /// Pop a pointer to this state, resetting it to the given old pointer.
+    fn pop_ptr(&mut self, old_ptr: NonNull<T>) -> usize {
+        self.ptr = old_ptr.as_ptr();
+        self.stack_depth -= 1;
+        self.stack_depth
     }
 }
 
diff --git a/godot-cell/tests/mock.rs b/godot-cell/tests/mock.rs
index c991054a7..ec9df6342 100644
--- a/godot-cell/tests/mock.rs
+++ b/godot-cell/tests/mock.rs
@@ -35,12 +35,12 @@ fn binding() -> &'static Mutex<HashMap<usize, InstanceBinding>> {
 fn register_instance<T>(instance: T) -> usize {
     static COUNTER: AtomicUsize = AtomicUsize::new(0);
 
+    let key = COUNTER.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
+
     let binding = binding();
 
     let mut guard = binding.lock().unwrap();
 
-    let key = COUNTER.fetch_add(1, std::sync::atomic::Ordering::AcqRel);
-
     assert!(!guard.contains_key(&key));
 
     let cell = GdCell::new(instance);
@@ -105,23 +105,42 @@ impl<T> Base<T> {
 
 struct BaseGuard<'a, T> {
     instance_id: usize,
-    _inaccessible_guard: InaccessibleGuard<'a, T>,
+    inaccessible_guard: Option<InaccessibleGuard<'a, T>>,
 }
 
 impl<'a, T> BaseGuard<'a, T> {
     fn new(instance_id: usize, inaccessible_guard: InaccessibleGuard<'a, T>) -> Self {
         Self {
             instance_id,
-            _inaccessible_guard: inaccessible_guard,
+            inaccessible_guard: Some(inaccessible_guard),
         }
     }
 
-    fn call_immut(&self, f: fn(&T)) {
-        unsafe { call_immut_method(self.instance_id, f).unwrap() }
+    fn call_immut(&self, f: fn(&T)) -> Result<(), Box<dyn Error>> {
+        unsafe { call_immut_method(self.instance_id, f) }
     }
 
-    fn call_mut(&self, f: fn(&mut T)) {
-        unsafe { call_mut_method(self.instance_id, f).unwrap() }
+    fn call_mut(&self, f: fn(&mut T)) -> Result<(), Box<dyn Error>> {
+        unsafe { call_mut_method(self.instance_id, f) }
+    }
+}
+
+impl<'a, T> Drop for BaseGuard<'a, T> {
+    fn drop(&mut self) {
+        // Block while waiting for the guard to be droppable.
+        // This is only needed to make multi-threaded code work nicely, the default drop-impl for
+        // `InaccessibleGuard` may panic and get poisoned in multi-threaded code, which is non-ideal but
+        // still safe behavior.
+        let mut guard_opt = Some(std::mem::ManuallyDrop::new(
+            self.inaccessible_guard.take().unwrap(),
+        ));
+
+        while let Some(guard) = guard_opt.take() {
+            if let Err(new_guard) = std::mem::ManuallyDrop::into_inner(guard).try_drop() {
+                guard_opt = Some(new_guard);
+                std::hint::spin_loop()
+            }
+        }
     }
 }
 
@@ -166,7 +185,7 @@ impl MyClass {
         println!("mut_calls_immut #1: int is {}", self.int);
         self.int += 1;
         println!("mut_calls_immut #2: int is now {}", self.int);
-        self.base().call_immut(Self::immut_method);
+        _ = self.base().call_immut(Self::immut_method);
         println!("mut_calls_immut #3: int is now {}", self.int);
     }
 
@@ -174,7 +193,7 @@ impl MyClass {
         println!("mut_calls_mut #1: int is {}", self.int);
         self.int += 1;
         println!("mut_calls_mut #2: int is now {}", self.int);
-        self.base().call_mut(Self::mut_method);
+        _ = self.base().call_mut(Self::mut_method);
         println!("mut_calls_mut #3: int is now {}", self.int);
     }
 
@@ -182,7 +201,7 @@ impl MyClass {
         println!("mut_calls_twice #1: int is {}", self.int);
         self.int += 1;
         println!("mut_calls_twice #2: int is now {}", self.int);
-        self.base().call_mut(Self::mut_method_calls_immut);
+        _ = self.base().call_mut(Self::mut_method_calls_immut);
         println!("mut_calls_twice #3: int is now {}", self.int);
     }
 
@@ -190,7 +209,7 @@ impl MyClass {
         println!("mut_calls_twice_mut #1: int is {}", self.int);
         self.int += 1;
         println!("mut_calls_twice_mut #2: int is now {}", self.int);
-        self.base().call_mut(Self::mut_method_calls_mut);
+        _ = self.base().call_mut(Self::mut_method_calls_mut);
         println!("mut_calls_twice_mut #3: int is now {}", self.int);
     }
 
@@ -212,104 +231,207 @@ fn call_works() {
     unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
 }
 
+/// `instance_id` must be the key of a `MyClass`.
+unsafe fn get_int(instance_id: usize) -> i64 {
+    let storage = unsafe { get_instance::<MyClass>(instance_id) };
+    let bind = storage.cell.as_ref().borrow().unwrap();
+    bind.int
+}
+
+/// `instance_id` must be the key of a `MyClass`.
+unsafe fn assert_id_is(instance_id: usize, target: i64) {
+    let storage = unsafe { get_instance::<MyClass>(instance_id) };
+    let bind = storage.cell.as_ref().borrow().unwrap();
+    assert_eq!(bind.int, target);
+}
+
+type MethodCall = unsafe fn(usize) -> Result<(), Box<dyn Error>>;
+
+/// A list of each calls to each method of `MyClass`. The numbers are the minimum and maximum increment
+/// of the method call.
+static CALLS: &[(MethodCall, i64, i64)] = &[
+    (
+        |id| unsafe { call_immut_method(id, MyClass::immut_method) },
+        0,
+        0,
+    ),
+    (
+        |id| unsafe { call_mut_method(id, MyClass::mut_method) },
+        1,
+        1,
+    ),
+    (
+        |id| unsafe { call_mut_method(id, MyClass::mut_method_calls_immut) },
+        1,
+        1,
+    ),
+    (
+        |id| unsafe { call_mut_method(id, MyClass::mut_method_calls_mut) },
+        1,
+        2,
+    ),
+    (
+        |id| unsafe { call_mut_method(id, MyClass::mut_method_calls_twice) },
+        1,
+        2,
+    ),
+    (
+        |id| unsafe { call_mut_method(id, MyClass::mut_method_calls_twice_mut) },
+        1,
+        3,
+    ),
+    (
+        |id| unsafe { call_immut_method(id, MyClass::immut_calls_immut_directly) },
+        0,
+        0,
+    ),
+];
+
+/// Run each test once ensuring the integer changes as expected.
 #[test]
 fn all_calls_work() {
     let instance_id = MyClass::init();
 
-    fn assert_int_is(instance_id: usize, target: i64) {
-        let storage = unsafe { get_instance::<MyClass>(instance_id) };
-        let bind = storage.cell.as_ref().borrow().unwrap();
-        assert_eq!(bind.int, target);
+    unsafe {
+        assert_id_is(instance_id, 0);
     }
 
-    assert_int_is(instance_id, 0);
-    unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
-    assert_int_is(instance_id, 0);
-    unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() };
-    assert_int_is(instance_id, 1);
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap() };
-    assert_int_is(instance_id, 2);
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap() };
-    assert_int_is(instance_id, 4);
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap() };
-    assert_int_is(instance_id, 6);
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap() };
-    assert_int_is(instance_id, 9);
-    unsafe { call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap() };
-    assert_int_is(instance_id, 9);
+    // We're not running in parallel, so it will never fail to increment completely.
+    for (f, _, expected_increment) in CALLS {
+        let start = unsafe { get_int(instance_id) };
+        unsafe {
+            f(instance_id).unwrap();
+        }
+        unsafe {
+            assert_id_is(instance_id, start + *expected_increment);
+        }
+    }
 }
 
+/// Run each method both from the main thread and a newly created thread.
 #[test]
 fn calls_different_thread() {
     use std::thread;
 
     let instance_id = MyClass::init();
-    fn assert_int_is(instance_id: usize, target: i64) {
-        let storage = unsafe { get_instance::<MyClass>(instance_id) };
-        let bind = storage.cell.as_ref().borrow().unwrap();
-        assert_eq!(bind.int, target);
+
+    // We're not running in parallel, so it will never fail to increment completely.
+    for (f, _, expected_increment) in CALLS {
+        let start = unsafe { get_int(instance_id) };
+        unsafe {
+            f(instance_id).unwrap();
+
+            assert_id_is(instance_id, start + expected_increment);
+        }
+        let start = start + expected_increment;
+        thread::spawn(move || unsafe { f(instance_id).unwrap() })
+            .join()
+            .unwrap();
+        unsafe {
+            assert_id_is(instance_id, start + expected_increment);
+        }
     }
+}
 
-    assert_int_is(instance_id, 0);
+/// Call each method from different threads, allowing them to run in parallel.
+///
+/// This may cause borrow failures, we do a best-effort attempt at estimating the value then. We can detect
+/// if the first call failed, so then we know the integer was incremented by 0. Otherwise we at least know
+/// the range of values that it can be incremented by.
+#[test]
+fn calls_parallel() {
+    use std::thread;
 
-    unsafe { call_immut_method(instance_id, MyClass::immut_method).unwrap() };
-    assert_int_is(instance_id, 0);
-    thread::spawn(move || unsafe {
-        call_immut_method(instance_id, MyClass::immut_method).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 0);
-
-    unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() };
-    assert_int_is(instance_id, 1);
-    thread::spawn(move || unsafe { call_mut_method(instance_id, MyClass::mut_method).unwrap() })
-        .join()
+    let instance_id = MyClass::init();
+    let mut handles = Vec::new();
+
+    for (f, min_increment, max_increment) in CALLS {
+        let handle = thread::spawn(move || unsafe {
+            f(instance_id).map_or((0, 0), |_| (*min_increment, *max_increment))
+        });
+        handles.push(handle);
+    }
+
+    let (min_expected, max_expected) = handles
+        .into_iter()
+        .map(|handle| handle.join().unwrap())
+        .reduce(|(curr_min, curr_max), (min, max)| (curr_min + min, curr_max + max))
+        .unwrap();
+
+    unsafe {
+        assert!(get_int(instance_id) >= min_expected);
+        assert!(get_int(instance_id) <= max_expected);
+    }
+}
+
+/// Call each method from different threads, allowing them to run in parallel.
+///
+/// This may cause borrow failures, we do a best-effort attempt at estimating the value then. We can detect
+/// if the first call failed, so then we know the integer was incremented by 0. Otherwise we at least know
+/// the range of values that it can be incremented by.
+///
+/// Runs each method several times in a row. This should reduce the non-determinism that comes from
+/// scheduling of threads.
+#[test]
+fn calls_parallel_many_serial() {
+    use std::thread;
+
+    let instance_id = MyClass::init();
+    let mut handles = Vec::new();
+
+    for (f, min_increment, max_increment) in CALLS {
+        for _ in 0..10 {
+            let handle = thread::spawn(move || unsafe {
+                f(instance_id).map_or((0, 0), |_| (*min_increment, *max_increment))
+            });
+            handles.push(handle);
+        }
+    }
+
+    let (min_expected, max_expected) = handles
+        .into_iter()
+        .map(|handle| handle.join().unwrap())
+        .reduce(|(curr_min, curr_max), (min, max)| (curr_min + min, curr_max + max))
         .unwrap();
-    assert_int_is(instance_id, 2);
-
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap() };
-    assert_int_is(instance_id, 3);
-    thread::spawn(move || unsafe {
-        call_mut_method(instance_id, MyClass::mut_method_calls_immut).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 4);
-
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap() };
-    assert_int_is(instance_id, 6);
-    thread::spawn(move || unsafe {
-        call_mut_method(instance_id, MyClass::mut_method_calls_mut).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 8);
-
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap() };
-    assert_int_is(instance_id, 10);
-    thread::spawn(move || unsafe {
-        call_mut_method(instance_id, MyClass::mut_method_calls_twice).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 12);
-
-    unsafe { call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap() };
-    assert_int_is(instance_id, 15);
-    thread::spawn(move || unsafe {
-        call_mut_method(instance_id, MyClass::mut_method_calls_twice_mut).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 18);
-
-    unsafe { call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap() };
-    assert_int_is(instance_id, 18);
-    thread::spawn(move || unsafe {
-        call_immut_method(instance_id, MyClass::immut_calls_immut_directly).unwrap()
-    })
-    .join()
-    .unwrap();
-    assert_int_is(instance_id, 18);
+
+    unsafe {
+        assert!(get_int(instance_id) >= min_expected);
+        assert!(get_int(instance_id) <= max_expected);
+    }
+}
+
+/// Call each method from different threads, allowing them to run in parallel.
+///
+/// This may cause borrow failures, we do a best-effort attempt at estimating the value then. We can detect
+/// if the first call failed, so then we know the integer was incremented by 0. Otherwise we at least know
+/// the range of values that it can be incremented by.
+///
+/// Runs all the tests several times. This is different from [`calls_parallel_many_serial`] as that calls the
+/// methods like AAA...BBB...CCC..., whereas this interleaves the methods like ABC...ABC...ABC...
+#[test]
+fn calls_parallel_many_parallel() {
+    use std::thread;
+
+    let instance_id = MyClass::init();
+    let mut handles = Vec::new();
+
+    for _ in 0..10 {
+        for (f, min_increment, max_increment) in CALLS {
+            let handle = thread::spawn(move || unsafe {
+                f(instance_id).map_or((0, 0), |_| (*min_increment, *max_increment))
+            });
+            handles.push(handle);
+        }
+    }
+
+    let (min_expected, max_expected) = handles
+        .into_iter()
+        .map(|handle| handle.join().unwrap())
+        .reduce(|(curr_min, curr_max), (min, max)| (curr_min + min, curr_max + max))
+        .unwrap();
+
+    unsafe {
+        assert!(get_int(instance_id) >= min_expected);
+        assert!(get_int(instance_id) <= max_expected);
+    }
 }
diff --git a/godot-core/src/obj/guards.rs b/godot-core/src/obj/guards.rs
index 98935e8a7..194790260 100644
--- a/godot-core/src/obj/guards.rs
+++ b/godot-core/src/obj/guards.rs
@@ -5,13 +5,12 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+use godot_cell::{InaccessibleGuard, MutGuard, RefGuard};
 use godot_ffi::out;
 
 use std::fmt::Debug;
 use std::ops::{Deref, DerefMut};
 
-use crate::storage::{BaseMutGuard, MutGuard, RefGuard};
-
 use super::{Gd, GodotClass};
 
 /// Immutably/shared bound reference guard for a [`Gd`][crate::obj::Gd] smart pointer.
@@ -119,14 +118,14 @@ impl<T: GodotClass> Deref for BaseRef<'_, T> {
 /// See [`WithBaseField::base_mut()`](super::WithBaseField::base_mut()) for usage.
 pub struct BaseMut<'a, T: GodotClass> {
     gd: Gd<T::Base>,
-    _base_mut_guard: BaseMutGuard<'a, T>,
+    _inaccessible_guard: InaccessibleGuard<'a, T>,
 }
 
 impl<'a, T: GodotClass> BaseMut<'a, T> {
-    pub(crate) fn new(gd: Gd<T::Base>, base_mut_guard: BaseMutGuard<'a, T>) -> Self {
+    pub(crate) fn new(gd: Gd<T::Base>, inaccessible_guard: InaccessibleGuard<'a, T>) -> Self {
         Self {
             gd,
-            _base_mut_guard: base_mut_guard,
+            _inaccessible_guard: inaccessible_guard,
         }
     }
 }
diff --git a/godot-core/src/obj/traits.rs b/godot-core/src/obj/traits.rs
index 8d60ffa5c..b452b4552 100644
--- a/godot-core/src/obj/traits.rs
+++ b/godot-core/src/obj/traits.rs
@@ -392,7 +392,7 @@ pub trait WithBaseField: GodotClass<Declarer = dom::UserDomain> {
                 .expect("we have a `Gd<Self>` so the raw should not be null")
         };
 
-        let guard = storage.get_base_mut(self);
+        let guard = storage.get_inaccessible(self);
 
         BaseMut::new(base_gd, guard)
     }
diff --git a/godot-core/src/storage.rs b/godot-core/src/storage.rs
index bf785357c..0c753f1a5 100644
--- a/godot-core/src/storage.rs
+++ b/godot-core/src/storage.rs
@@ -5,8 +5,6 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use std::ops::{Deref, DerefMut};
-
 use crate::obj::{Base, Gd, GodotClass, Inherits};
 use crate::{godot_error, out};
 use godot_ffi as sys;
@@ -69,22 +67,6 @@ pub unsafe trait Storage {
     /// The type of instances stored by this storage.
     type Instance: GodotClass;
 
-    /// The type of guards returned when a shared reference is taken.
-    type RefGuard<'a>: Deref<Target = Self::Instance>
-    where
-        Self: 'a;
-
-    /// The type of guards returned when a mutable reference is taken.
-    type MutGuard<'a>: Deref<Target = Self::Instance> + DerefMut
-    where
-        Self: 'a;
-
-    /// The type of guards returned when we know that a mutable reference can be safely ignored for purposes
-    /// of taking mutable references.
-    type BaseMutGuard<'a>
-    where
-        Self: 'a;
-
     /// Constructs a new storage for an instance binding referencing `user_instance`.
     fn construct(
         user_instance: Self::Instance,
@@ -101,22 +83,22 @@ pub unsafe trait Storage {
     ///
     /// This will ensure Rust's rules surrounding references are upheld. Possibly panicking at runtime if
     /// they are violated.
-    fn get(&self) -> Self::RefGuard<'_>;
+    fn get(&self) -> godot_cell::RefGuard<'_, Self::Instance>;
 
     /// Returns a mutable/exclusive reference to this storage's instance.
     ///
     /// This will ensure Rust's rules surrounding references are upheld. Possibly panicking at runtime if
     /// they are violated.
-    fn get_mut(&self) -> Self::MutGuard<'_>;
+    fn get_mut(&self) -> godot_cell::MutGuard<'_, Self::Instance>;
 
     /// Returns a guard that allows calling methods on `Gd<Base>` that take `&mut self`.
     ///
     /// This can use the provided `instance` to provide extra safety guarantees such as allowing reentrant
     /// code to create new mutable references.
-    fn get_base_mut<'a: 'b, 'b>(
+    fn get_inaccessible<'a: 'b, 'b>(
         &'a self,
         instance: &'b mut Self::Instance,
-    ) -> Self::BaseMutGuard<'b>;
+    ) -> godot_cell::InaccessibleGuard<'b, Self::Instance>;
 
     /// Returns whether this storage is currently alive or being destroyed.
     ///
@@ -189,10 +171,6 @@ pub type InstanceStorage<T> = single_threaded::InstanceStorage<T>;
 #[cfg(feature = "experimental-threads")]
 pub type InstanceStorage<T> = multi_threaded::InstanceStorage<T>;
 
-pub type RefGuard<'a, T> = <InstanceStorage<T> as Storage>::RefGuard<'a>;
-pub type MutGuard<'a, T> = <InstanceStorage<T> as Storage>::MutGuard<'a>;
-pub type BaseMutGuard<'a, T> = <InstanceStorage<T> as Storage>::BaseMutGuard<'a>;
-
 const fn _assert_implements_storage<T: Storage + StorageRefCounted>() {}
 
 const _INSTANCE_STORAGE_IMPLEMENTS_STORAGE: () =
diff --git a/godot-core/src/storage/multi_threaded.rs b/godot-core/src/storage/multi_threaded.rs
index 480788e86..7ede90a84 100644
--- a/godot-core/src/storage/multi_threaded.rs
+++ b/godot-core/src/storage/multi_threaded.rs
@@ -34,12 +34,6 @@ pub struct InstanceStorage<T: GodotClass> {
 unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     type Instance = T;
 
-    type RefGuard<'a> = godot_cell::RefGuard<'a, T>;
-
-    type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
-
-    type BaseMutGuard<'a> = godot_cell::InaccessibleGuard<'a, T>;
-
     fn construct(
         user_instance: Self::Instance,
         base: Base<<Self::Instance as GodotClass>::Base>,
@@ -61,7 +55,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
         &self.base
     }
 
-    fn get(&self) -> Self::RefGuard<'_> {
+    fn get(&self) -> godot_cell::RefGuard<'_, T> {
         self.user_instance.as_ref().borrow().unwrap_or_else(|err| {
             panic!(
                 "\
@@ -74,7 +68,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
         })
     }
 
-    fn get_mut(&self) -> Self::MutGuard<'_> {
+    fn get_mut(&self) -> godot_cell::MutGuard<'_, T> {
         self.user_instance
             .as_ref()
             .borrow_mut()
@@ -90,7 +84,10 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
             })
     }
 
-    fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
+    fn get_inaccessible<'a: 'b, 'b>(
+        &'a self,
+        value: &'b mut Self::Instance,
+    ) -> godot_cell::InaccessibleGuard<'b, T> {
         self.user_instance
             .as_ref()
             .make_inaccessible(value)
diff --git a/godot-core/src/storage/single_threaded.rs b/godot-core/src/storage/single_threaded.rs
index 329578def..3e2a391cc 100644
--- a/godot-core/src/storage/single_threaded.rs
+++ b/godot-core/src/storage/single_threaded.rs
@@ -34,12 +34,6 @@ pub struct InstanceStorage<T: GodotClass> {
 unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
     type Instance = T;
 
-    type RefGuard<'a> = godot_cell::RefGuard<'a, T>;
-
-    type MutGuard<'a> = godot_cell::MutGuard<'a, T>;
-
-    type BaseMutGuard<'a> = godot_cell::InaccessibleGuard<'a, T>;
-
     fn construct(
         user_instance: Self::Instance,
         base: Base<<Self::Instance as GodotClass>::Base>,
@@ -61,7 +55,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
         &self.base
     }
 
-    fn get(&self) -> Self::RefGuard<'_> {
+    fn get(&self) -> godot_cell::RefGuard<'_, T> {
         self.user_instance.as_ref().borrow().unwrap_or_else(|err| {
             panic!(
                 "\
@@ -74,7 +68,7 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
         })
     }
 
-    fn get_mut(&self) -> Self::MutGuard<'_> {
+    fn get_mut(&self) -> godot_cell::MutGuard<'_, T> {
         self.user_instance
             .as_ref()
             .borrow_mut()
@@ -90,7 +84,10 @@ unsafe impl<T: GodotClass> Storage for InstanceStorage<T> {
             })
     }
 
-    fn get_base_mut<'a: 'b, 'b>(&'a self, value: &'b mut Self::Instance) -> Self::BaseMutGuard<'b> {
+    fn get_inaccessible<'a: 'b, 'b>(
+        &'a self,
+        value: &'b mut Self::Instance,
+    ) -> godot_cell::InaccessibleGuard<'b, T> {
         self.user_instance
             .as_ref()
             .make_inaccessible(value)

From 52dd1b340d606ada86f76b757e8303af5f834641 Mon Sep 17 00:00:00 2001
From: Jan Haller <bromeon@gmail.com>
Date: Thu, 4 Jan 2024 20:54:20 +0100
Subject: [PATCH 6/7] Clippy

Complaints:
* items_after_test_module - projection.rs; `mod test` should come last.
* unnecessary_fallible_conversions - array_test.rs; TryFrom with Infallible should be replaced with From.
---
 godot-core/src/builtin/projection.rs          | 96 +++++++++----------
 .../builtin_tests/containers/array_test.rs    |  2 +
 2 files changed, 50 insertions(+), 48 deletions(-)

diff --git a/godot-core/src/builtin/projection.rs b/godot-core/src/builtin/projection.rs
index de2a93917..59f6c9cdf 100644
--- a/godot-core/src/builtin/projection.rs
+++ b/godot-core/src/builtin/projection.rs
@@ -578,6 +578,54 @@ pub enum ProjectionEye {
     Right = 2,
 }
 
+impl std::fmt::Display for Projection {
+    /// Formats `Projection` to match Godot's string representation.
+    ///
+    /// Example:
+    /// ```
+    /// use godot::prelude::*;
+    /// let proj = Projection::new([
+    ///     Vector4::new(1.0, 2.5, 1.0, 0.5),
+    ///     Vector4::new(0.0, 1.5, 2.0, 0.5),
+    ///     Vector4::new(0.0, 0.0, 3.0, 2.5),
+    ///     Vector4::new(3.0, 1.0, 4.0, 1.5),
+    /// ]);
+    /// const FMT_RESULT: &str = r"
+    /// 1, 0, 0, 3
+    /// 2.5, 1.5, 0, 1
+    /// 1, 2, 3, 4
+    /// 0.5, 0.5, 2.5, 1.5
+    /// ";
+    /// assert_eq!(format!("{}", proj), FMT_RESULT);
+    /// ```
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "\n{}, {}, {}, {}\n{}, {}, {}, {}\n{}, {}, {}, {}\n{}, {}, {}, {}\n",
+            // first row
+            self.cols[0][Vector4Axis::X],
+            self.cols[1][Vector4Axis::X],
+            self.cols[2][Vector4Axis::X],
+            self.cols[3][Vector4Axis::X],
+            // second row
+            self.cols[0][Vector4Axis::Y],
+            self.cols[1][Vector4Axis::Y],
+            self.cols[2][Vector4Axis::Y],
+            self.cols[3][Vector4Axis::Y],
+            // third row
+            self.cols[0][Vector4Axis::Z],
+            self.cols[1][Vector4Axis::Z],
+            self.cols[2][Vector4Axis::Z],
+            self.cols[3][Vector4Axis::Z],
+            // forth row
+            self.cols[0][Vector4Axis::W],
+            self.cols[1][Vector4Axis::W],
+            self.cols[2][Vector4Axis::W],
+            self.cols[3][Vector4Axis::W],
+        )
+    }
+}
+
 #[cfg(test)]
 mod test {
     // TODO(bromeon): reduce code duplication
@@ -1033,51 +1081,3 @@ mod test {
         crate::builtin::test_utils::roundtrip(&projection, expected_json);
     }
 }
-
-impl std::fmt::Display for Projection {
-    /// Formats `Projection` to match Godot's string representation.
-    ///
-    /// Example:
-    /// ```
-    /// use godot::prelude::*;
-    /// let proj = Projection::new([
-    ///     Vector4::new(1.0, 2.5, 1.0, 0.5),
-    ///     Vector4::new(0.0, 1.5, 2.0, 0.5),
-    ///     Vector4::new(0.0, 0.0, 3.0, 2.5),
-    ///     Vector4::new(3.0, 1.0, 4.0, 1.5),
-    /// ]);
-    /// const FMT_RESULT: &str = r"
-    /// 1, 0, 0, 3
-    /// 2.5, 1.5, 0, 1
-    /// 1, 2, 3, 4
-    /// 0.5, 0.5, 2.5, 1.5
-    /// ";
-    /// assert_eq!(format!("{}", proj), FMT_RESULT);
-    /// ```
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(
-            f,
-            "\n{}, {}, {}, {}\n{}, {}, {}, {}\n{}, {}, {}, {}\n{}, {}, {}, {}\n",
-            // first row
-            self.cols[0][Vector4Axis::X],
-            self.cols[1][Vector4Axis::X],
-            self.cols[2][Vector4Axis::X],
-            self.cols[3][Vector4Axis::X],
-            // second row
-            self.cols[0][Vector4Axis::Y],
-            self.cols[1][Vector4Axis::Y],
-            self.cols[2][Vector4Axis::Y],
-            self.cols[3][Vector4Axis::Y],
-            // third row
-            self.cols[0][Vector4Axis::Z],
-            self.cols[1][Vector4Axis::Z],
-            self.cols[2][Vector4Axis::Z],
-            self.cols[3][Vector4Axis::Z],
-            // forth row
-            self.cols[0][Vector4Axis::W],
-            self.cols[1][Vector4Axis::W],
-            self.cols[2][Vector4Axis::W],
-            self.cols[3][Vector4Axis::W],
-        )
-    }
-}
diff --git a/itest/rust/src/builtin_tests/containers/array_test.rs b/itest/rust/src/builtin_tests/containers/array_test.rs
index a98244caa..7beb3ae15 100644
--- a/itest/rust/src/builtin_tests/containers/array_test.rs
+++ b/itest/rust/src/builtin_tests/containers/array_test.rs
@@ -78,6 +78,8 @@ fn array_from_slice() {
 #[itest]
 fn array_try_into_vec() {
     let array = array![1, 2];
+
+    #[allow(clippy::unnecessary_fallible_conversions)]
     let result = Vec::<i64>::try_from(&array);
     assert_eq!(result, Ok(vec![1, 2]));
 }

From 48269f1210abebb74e45eee137bc3459ede5400c Mon Sep 17 00:00:00 2001
From: Jan Haller <bromeon@gmail.com>
Date: Thu, 4 Jan 2024 22:34:12 +0100
Subject: [PATCH 7/7] Add Cargo metadata to godot-cell

---
 godot-cell/Cargo.toml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/godot-cell/Cargo.toml b/godot-cell/Cargo.toml
index d94592469..7d3458bbf 100644
--- a/godot-cell/Cargo.toml
+++ b/godot-cell/Cargo.toml
@@ -2,6 +2,10 @@
 name = "godot-cell"
 version = "0.1.0"
 edition = "2021"
+rust-version = "1.70"
+license = "MPL-2.0"
+keywords = ["gamedev", "godot", "engine", "ffi"]
+categories = ["game-engines", "graphics"]
 
 [features]
 proptest = ["dep:proptest"]