Merge #1034

1034: Implement support for flexible self types r=chitoyuu a=chitoyuu

`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.

This is technically a breaking change because all `UserData` errors are now required to implement `std::error::Error`, although the possibility of actual breakage should be pretty low -- the wrapper types we ship should be powerful enough to cover most if not all valid use cases.

Close #974

Co-authored-by: Chitose Yuuzaki <[email protected]>

Author: bors[bot]

.github/workflows/full-ci.yml

@@ -130,7 +130,7 @@ jobs:
           - rust: { toolchain: 'nightly' }
             testflags: '-- --skip ui_tests'
           - os: { id: ubuntu-latest, name: linux }
-            rust: { toolchain: '1.63', postfix: ' (msrv 1.63)' }
+            rust: { toolchain: '1.67', postfix: ' (msrv 1.67)' }
             testflags: '-- --skip ui_tests'
           - os: { id: ubuntu-latest, name: linux }
             rust: { toolchain: 'stable', postfix: ' (minimal-deps)', special: 'minimal-deps' }
@@ -298,16 +298,16 @@ jobs:
             godot: "3.5.1-stable"
             postfix: ' (nightly, inventory)'
             build_args: '--features inventory'
-          - rust: '1.63'
+          - rust: '1.67'
             godot: "3.5.1-stable"
-            postfix: ' (msrv 1.63)'
-          - rust: '1.63'
+            postfix: ' (msrv 1.67)'
+          - rust: '1.67'
             godot: "3.5.1-stable"
-            postfix: ' (msrv 1.63, ptrcall)'
+            postfix: ' (msrv 1.67, ptrcall)'
             build_args: '--features ptrcall'
-          - rust: '1.63'
+          - rust: '1.67'
             godot: "3.5.1-stable"
-            postfix: ' (msrv 1.63, inventory)'
+            postfix: ' (msrv 1.67, inventory)'
             build_args: '--features inventory'
 
           # Test with oldest supported engine version

README.md

@@ -17,7 +17,7 @@
 
 The bindings cover most of the exposed API of Godot 3.5, and are being used on a number of projects in development, but we still expect non-trivial breaking changes in the API in the coming releases. godot-rust adheres to [Cargo's semantic versioning](https://doc.rust-lang.org/cargo/reference/semver.html).
 
-Minimum supported Rust version (MSRV) is **1.63**. We use the Rust 2021 Edition.
+Minimum supported Rust version (MSRV) is **1.67**. We use the Rust 2021 Edition.
 
 
 ## Engine compatibility

bindings-generator/Cargo.toml

@@ -9,7 +9,7 @@ license = "MIT"
 version = "0.11.3"
 workspace = ".."
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 
 [features]
 debug = []

examples/builder-export/Cargo.toml

@@ -3,7 +3,7 @@ name = "builder-export"
 version = "0.1.0"
 authors = ["The godot-rust developers"]
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 publish = false
 

examples/dodge-the-creeps/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 authors = ["The godot-rust developers"]
 publish = false
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [lib]

examples/godot_tps_controller_port/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 edition = "2021"
 authors = ["The godot-rust developers"]
 publish = false
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [dependencies]

examples/hello-world/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 authors = ["The godot-rust developers"]
 publish = false
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [lib]

examples/native-plugin/Cargo.toml

@@ -3,7 +3,7 @@ name = "native-plugin"
 version = "0.1.0"
 authors = ["The godot-rust developers"]
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 publish = false
 

examples/property-export/Cargo.toml

@@ -3,7 +3,7 @@ name = "property-export"
 version = "0.1.0"
 authors = ["The godot-rust developers"]
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 publish = false
 

examples/resource/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 authors = ["The godot-rust developers"]
 publish = false
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [lib]

examples/rpc/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 authors = ["The godot-rust developers"]
 publish = false
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [lib]

examples/scene-create/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 authors = ["The godot-rust developers"]
 publish = false
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 
 [lib]

examples/signals/Cargo.toml

@@ -3,7 +3,7 @@ name = "signals"
 version = "0.1.0"
 authors = ["The godot-rust developers"]
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 publish = false
 

examples/spinning-cube/Cargo.toml

@@ -3,7 +3,7 @@ name = "spinning-cube"
 version = "0.1.0"
 authors = ["The godot-rust developers"]
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 license = "MIT"
 publish = false
 

gdnative-async/Cargo.toml

@@ -9,7 +9,7 @@ version = "0.11.3"
 license = "MIT"
 workspace = ".."
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 
 [features]
 

gdnative-bindings/Cargo.toml

@@ -9,7 +9,7 @@ version = "0.11.3"
 license = "MIT"
 workspace = ".."
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 
 [features]
 formatted = []

gdnative-core/Cargo.toml

@@ -9,7 +9,7 @@ version = "0.11.3"
 license = "MIT"
 workspace = ".."
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 
 [features]
 default = []

gdnative-core/src/export/user_data.rs

@@ -121,7 +121,7 @@ pub unsafe trait UserData: Sized + Clone {
 
 /// Trait for wrappers that can be mapped immutably.
 pub trait Map: UserData {
-    type Err: Debug;
+    type Err: std::error::Error;
 
     /// Maps a `&T` to `U`. Called for methods that take `&self`.
     ///
@@ -134,7 +134,7 @@ pub trait Map: UserData {
 
 /// Trait for wrappers that can be mapped mutably.
 pub trait MapMut: UserData {
-    type Err: Debug;
+    type Err: std::error::Error;
 
     /// Maps a `&mut T` to `U`. Called for methods that take `&mut self`.
     ///
@@ -147,7 +147,7 @@ pub trait MapMut: UserData {
 
 /// Trait for wrappers that can be mapped once.
 pub trait MapOwned: UserData {
-    type Err: Debug;
+    type Err: std::error::Error;
 
     /// Maps a `T` to `U`. Called for methods that take `self`. This method may fail with
     /// an error if it is called more than once on the same object.
@@ -168,10 +168,11 @@ pub type DefaultUserData<T> = LocalCellData<T>;
 #[allow(clippy::exhaustive_enums)] // explicitly uninhabited
 pub enum Infallible {}
 
+impl std::error::Error for Infallible {}
 impl std::fmt::Display for Infallible {
     #[inline]
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "operation that can't fail just failed")
+    fn fmt(&self, _f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        unreachable!("uninhabited enum")
     }
 }
 

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,134 @@
+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: std::error::Error;
+
+    #[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 std::error::Error for 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/Cargo.toml

@@ -9,7 +9,7 @@ version = "0.11.3"
 license = "MIT"
 workspace = ".."
 edition = "2021"
-rust-version = "1.63"
+rust-version = "1.67"
 
 [lib]
 proc-macro = true