55 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
66 */
77
8- use std:: marker:: PhantomData ;
98use std:: mem:: ManuallyDrop ;
109use std:: ops:: { Deref , DerefMut } ;
1110
1211use crate :: obj:: { Gd , GodotClass } ;
12+ use crate :: sys;
1313
1414/// Passive (non-owning) reference to a Godot object.
1515///
16- /// `PassiveGd<'gd, T>` provides a safe abstraction for weak references to Godot objects. Unlike `Gd<T>`, it does not increment/decrement
16+ /// `PassiveGd<T>` provides an unsafe abstraction for weak references to Godot objects. Unlike `Gd<T>`, it does not increment/decrement
1717/// the reference count for `RefCounted` objects, and its `Drop` impl only cleans up metadata, not the Godot object.
1818///
19- /// The lifetime `'gd` can be used to tie it to a _strong_ `Gd<T>` reference, however it can also be `'static` if more flexibility is needed.
19+ /// This type is for internal use only, to access base objects in guards and traits, and to wrap manual [`Gd::clone_weak()`] and
20+ /// [`Gd::drop_weak()`] patterns.
2021///
21- /// This type is primarily used internally for base object access in guards and traits, providing a clean alternative to manual
22- /// [`Gd::clone_weak()`] and [`Gd::drop_weak()`] patterns.
23- pub ( crate ) struct PassiveGd < ' gd , T : GodotClass > {
22+ /// # Why no lifetime?
23+ /// Previous versions used `PassiveGd<'gd, T>` with an explicit lifetime parameter. This caused subtle borrow-checking issues due to Rust's
24+ /// [drop check](https://doc.rust-lang.org/nomicon/dropck.html) rules. When a type has drop obligations (implements `Drop` or contains fields
25+ /// that do), the borrow checker conservatively assumes the destructor might access borrowed data reachable through that value, forcing all
26+ /// such borrows to strictly outlive the value. This created false conflicts when creating both shared and mutable base references from the
27+ /// same object, even though our `Drop` implementation never accesses the lifetime-bound data.
28+ ///
29+ /// By removing the lifetime parameter and making construction `unsafe`, we eliminate these false-positive borrow conflicts while maintaining
30+ /// memory safety through explicit caller contracts.
31+ ///
32+ /// In nightly Rust, `#[may_dangle]` on the lifetime parameter might be an alternative, to tell the compiler that our `Drop` implementation
33+ /// won't access the borrowed data, but this attribute requires careful safety analysis to ensure it's correctly applied.
34+ pub ( crate ) struct PassiveGd < T : GodotClass > {
2435 weak_gd : ManuallyDrop < Gd < T > > ,
25-
26- // Covariant lifetime: PassiveGd<'a, T> can be used wherever PassiveGd<'b, T> is needed, if 'a: 'b.
27- _phantom : PhantomData < & ' gd ( ) > ,
2836}
2937
30- impl < ' gd , T : GodotClass > PassiveGd < ' gd , T > {
31- pub fn from_strong_ref ( gd : & Gd < T > ) -> Self {
32- // SAFETY:
33- // - `clone_weak()` creates a pointer conforming to `from_weak_gd()` requirements.
34- // - PassiveGd will destroy the pointer with `drop_weak()`.
38+ impl < T : GodotClass > PassiveGd < T > {
39+ /// Creates a passive reference from a strong `Gd<T>` shared reference.
40+ ///
41+ /// # Safety
42+ /// The caller must ensure that the underlying object remains valid for the entire lifetime of this `PassiveGd`.
43+ pub unsafe fn from_strong_ref ( gd : & Gd < T > ) -> Self {
44+ // SAFETY: clone_weak() creates valid weak reference; caller ensures object validity.
45+ let weak_gd = gd. clone_weak ( ) ;
46+ unsafe { Self :: new ( weak_gd) }
47+ }
48+
49+ /// Creates a passive reference directly from a raw object pointer.
50+ ///
51+ /// This is a direct constructor that avoids the intermediate `Gd::from_obj_sys_weak()` step,
52+ /// providing better performance for the common pattern of creating PassiveGd from raw pointers.
53+ ///
54+ /// # Safety
55+ /// - `obj_ptr` must be a valid, live object pointer.
56+ /// - The caller must ensure that the underlying object remains valid for the entire lifetime of this `PassiveGd`.
57+ pub unsafe fn from_obj_sys ( obj_ptr : sys:: GDExtensionObjectPtr ) -> Self {
58+ // SAFETY: from_obj_sys_weak() creates valid weak reference from obj_ptr; caller ensures object validity.
3559 unsafe {
36- let weak_gd = gd . clone_weak ( ) ;
37- Self :: from_weak_owned ( weak_gd)
60+ let weak_gd = Gd :: from_obj_sys_weak ( obj_ptr ) ;
61+ Self :: new ( weak_gd)
3862 }
3963 }
4064
4165 /// Creates a passive reference directly from a weak `Gd<T>`.
4266///
43- /// Will invoke `Gd::drop_weak()` when dropped. Since the parameter has no lifetime, you need to provide the lifetime `'gd` explicitly.
67+ /// Will invoke `Gd::drop_weak()` when dropped.
4468///
4569/// # Safety
4670/// - `weak_gd` must be a weakly created `Gd`, e.g. from [`Gd::clone_weak()`] or [`Gd::from_obj_sys_weak()`].
47- /// - The caller must ensure that the `weak_gd` remains valid for the lifetime `'gd `.
48- pub unsafe fn from_weak_owned ( weak_gd : Gd < T > ) -> Self {
71+ /// - The caller must ensure that the underlying object remains valid for the entire lifetime of this `PassiveGd `.
72+ unsafe fn new ( weak_gd : Gd < T > ) -> Self {
4973 Self {
5074 weak_gd : ManuallyDrop :: new ( weak_gd) ,
51- _phantom : PhantomData ,
5275 }
5376 }
5477}
5578
56- impl < T : GodotClass > Drop for PassiveGd < ' _ , T > {
79+ impl < T : GodotClass > Drop for PassiveGd < T > {
5780 fn drop ( & mut self ) {
5881 // SAFETY: Only extracted once, in Drop.
5982 let weak = unsafe { ManuallyDrop :: take ( & mut self . weak_gd ) } ;
@@ -62,15 +85,15 @@ impl<T: GodotClass> Drop for PassiveGd<'_, T> {
6285 }
6386}
6487
65- impl < T : GodotClass > Deref for PassiveGd < ' _ , T > {
88+ impl < T : GodotClass > Deref for PassiveGd < T > {
6689 type Target = Gd < T > ;
6790
6891 fn deref ( & self ) -> & Self :: Target {
6992 & self . weak_gd
7093 }
7194}
7295
73- impl < T : GodotClass > DerefMut for PassiveGd < ' _ , T > {
96+ impl < T : GodotClass > DerefMut for PassiveGd < T > {
7497 fn deref_mut ( & mut self ) -> & mut Self :: Target {
7598 & mut self . weak_gd
7699 }
0 commit comments