Implement support for flexible self types

`Instance` and `TInstance` can now be used as self types where
applicable. Additionally, `Arc` is supported when `ArcData` is used as
the user-data wrapper.

The `self` type can be provided through the standard
`arbitrary_self_types` syntax, or a `#[self]` attribute on the argument
when unavailable.

Author: chitoyuu

gdnative-core/src/object/instance.rs

@@ -1,3 +1,4 @@
+use std::fmt::Debug;
 use std::ptr::NonNull;
 
 use crate::core_types::{
@@ -13,6 +14,9 @@ use crate::object::ownership::{NonUniqueOwnership, Ownership, Shared, ThreadLoca
 use crate::object::{GodotObject, Instanciable, QueueFree, RawObject, Ref, TRef};
 use crate::private::{get_api, ReferenceCountedClassPlaceholder};
 
+mod receiver;
+
+pub use receiver::Receiver;
 /// A persistent reference to a GodotObject with a rust NativeClass attached.
 ///
 /// `Instance`s can be worked on directly using `map` and `map_mut` if the base object is

gdnative-core/src/object/instance/receiver.rs

@@ -0,0 +1,133 @@
+use std::fmt::{Debug, Display};
+use std::sync::Arc;
+
+use crate::export::user_data::{ArcData, Map, MapMut, MapOwned};
+use crate::export::NativeClass;
+use crate::object::ownership::Shared;
+
+use super::{Instance, TInstance};
+
+/// Trait for types that can be used as the `self` or `#[self]` argument (receiver) for methods
+/// exported through the `#[methods]` attribute macro. This trait has no public interface, and
+/// is not intended to be implemented by users.
+///
+/// Notably, this is implemented for [`Instance`] and [`TInstance`] along with the usual `self`
+/// reference types. For types using [`ArcData`] as the wrapper specifically, [`Arc<C>`] is also
+/// allowed.
+///
+/// The trait is unsealed for technical coherence issues, but is not intended to be implemented
+/// by users. Changes to the definition of this trait are not considered breaking changes under
+/// semver.
+pub trait Receiver<C: NativeClass>: Sized {
+    #[doc(hidden)]
+    type This<'a>;
+    #[doc(hidden)]
+    type Err: Debug;
+
+    #[doc(hidden)]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R;
+}
+
+/// Error type indicating that an operation can't fail.
+#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
+#[allow(clippy::exhaustive_enums)] // explicitly uninhabited
+pub enum Infallible {}
+
+impl Display for Infallible {
+    fn fmt(&self, _f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        unreachable!("uninhabited enum")
+    }
+}
+
+impl<'r, C: NativeClass> Receiver<C> for TInstance<'r, C, Shared> {
+    type This<'a> = TInstance<'a, C, Shared>;
+    type Err = Infallible;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        Ok(f(instance))
+    }
+}
+
+impl<C: NativeClass> Receiver<C> for Instance<C, Shared> {
+    type This<'a> = Instance<C, Shared>;
+    type Err = Infallible;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        Ok(f(instance.claim()))
+    }
+}
+
+impl<'r, C: NativeClass> Receiver<C> for &'r C
+where
+    C::UserData: Map,
+{
+    type This<'a> = &'a C;
+    type Err = <C::UserData as Map>::Err;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        instance.map(|this, _| f(this))
+    }
+}
+
+impl<'r, C: NativeClass> Receiver<C> for &'r mut C
+where
+    C::UserData: MapMut,
+{
+    type This<'a> = &'a mut C;
+    type Err = <C::UserData as MapMut>::Err;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        instance.map_mut(|this, _| f(this))
+    }
+}
+
+impl<C: NativeClass> Receiver<C> for C
+where
+    C::UserData: MapOwned,
+{
+    type This<'a> = C;
+    type Err = <C::UserData as MapOwned>::Err;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        instance.map_owned(|this, _| f(this))
+    }
+}
+
+impl<C> Receiver<C> for Arc<C>
+where
+    C: NativeClass<UserData = ArcData<C>>,
+{
+    type This<'a> = Arc<C>;
+    type Err = Infallible;
+
+    #[inline]
+    fn with_instance<F, R>(instance: TInstance<'_, C, Shared>, f: F) -> Result<R, Self::Err>
+    where
+        F: for<'a> FnOnce(Self::This<'a>) -> R,
+    {
+        let (_, script) = instance.claim().decouple();
+        Ok(f(script.into_inner()))
+    }
+}

gdnative-derive/src/lib.rs

@@ -289,7 +289,13 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 /// [exporting](https://docs.godotengine.org/en/stable/tutorials/export/exporting_basics.html) in GDScript.
 ///
 /// A valid function signature must have:
-/// - `self`, `&self` or `&mut self` as its first parameter, if applicable.
+/// - Up to one receiver parameter as the first parameter. This can be one of:
+///     - `self`, `&self` or `&mut self`.
+///     - `self: Instance<Self>` or `self: TInstance<Self>`, when the `arbitrary_self_types` feature
+///       is available. Additionally, `self: Arc<Self>` is allowed when the `user_data` wrapper is
+///       specified to be `ArcData<Self>`.
+///     - `#[self] this: T` where `T` is any of the types mentioned above, as a workaround when
+///       `arbitrary_self_types` is unavailable.
 /// - Up of one of each of the following special arguments, in any order, denoted by the attributes:
 ///     - `#[base]` - A reference to the base/owner object. This may be `&T` or `TRef<T>`m where `T` refers to
 ///       the type declared in `#[inherit(T)]` attribute for the `NativeClass` type.
@@ -307,6 +313,10 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 /// #[method]
 /// fn foo();
 ///
+/// // Access `TInstance` instead of a variation of `self`, without `arbitrary_self_types`.
+/// #[method]
+/// fn foo(#[self] this: TInstance<Self>);
+///
 /// // No access to base parameter
 /// #[method]
 /// fn foo(&self);