Module organization

Author: Bromeon

godot-core/src/meta/mod.rs

@@ -60,6 +60,9 @@ pub use class_name::ClassName;
 pub use godot_convert::{FromGodot, GodotConvert, ToGodot};
 pub use traits::{ArrayElement, GodotType, PackedArrayElement};
 
+#[cfg(since_api = "4.2")]
+pub use crate::registry::signal::variadic::ParamTuple;
+
 pub(crate) use array_type_info::ArrayTypeInfo;
 pub(crate) use traits::{
     element_godot_type_name, element_variant_type, GodotFfiVariant, GodotNullableFfi,

godot-core/src/registry/mod.rs

@@ -16,11 +16,11 @@ pub mod plugin;
 pub mod property;
 
 #[cfg(since_api = "4.2")]
-pub mod functional;
+pub mod signal;
 
 // Contents re-exported in `godot` crate; just keep empty.
 #[cfg(before_api = "4.2")]
-pub mod functional {}
+pub mod signal {}
 
 // RpcConfig uses MultiplayerPeer::TransferMode and MultiplayerApi::RpcMode, which are only enabled in `codegen-full` feature.
 #[cfg(feature = "codegen-full")]

godot-core/src/registry/functional/connect_builder.rs renamed to godot-core/src/registry/signal/connect_builder.rs

@@ -8,7 +8,7 @@
 use crate::builtin::{Callable, GString, Variant};
 use crate::classes::object::ConnectFlags;
 use crate::obj::{bounds, Bounds, Gd, GodotClass, WithBaseField};
-use crate::registry::functional::{AsFunc, ParamTuple, TypedSignal};
+use crate::registry::signal::{SignalReceiver, TypedSignal};
 use crate::{meta, sys};
 
 /// Type-state builder for customizing signal connections.
@@ -63,7 +63,7 @@ pub struct ConnectBuilder<'ts, 'c, CSig: GodotClass, CRcv, Ps, GodotFn> {
     godot_fn: GodotFn,
 }
 
-impl<'ts, 'c, CSig: WithBaseField, Ps: ParamTuple> ConnectBuilder<'ts, 'c, CSig, (), Ps, ()> {
+impl<'ts, 'c, CSig: WithBaseField, Ps: meta::ParamTuple> ConnectBuilder<'ts, 'c, CSig, (), Ps, ()> {
     pub(super) fn new(parent_sig: &'ts mut TypedSignal<'c, CSig, Ps>) -> Self {
         ConnectBuilder {
             parent_sig,
@@ -86,7 +86,7 @@ impl<'ts, 'c, CSig: WithBaseField, Ps: ParamTuple> ConnectBuilder<'ts, 'c, CSig,
         /* GodotFn= */ impl FnMut(&[&Variant]) -> Result<Variant, ()> + 'static,
     >
     where
-        F: AsFunc<(), Ps>,
+        F: SignalReceiver<(), Ps>,
     {
         let godot_fn = move |variant_args: &[&Variant]| -> Result<Variant, ()> {
             let args = Ps::from_variant_array(variant_args);
@@ -132,7 +132,7 @@ impl<'ts, 'c, CSig: WithBaseField, Ps: ParamTuple> ConnectBuilder<'ts, 'c, CSig,
     }
 }
 
-impl<'ts, 'c, CSig: WithBaseField, CRcv: GodotClass, Ps: ParamTuple>
+impl<'ts, 'c, CSig: WithBaseField, CRcv: GodotClass, Ps: meta::ParamTuple>
     ConnectBuilder<'ts, 'c, CSig, Gd<CRcv>, Ps, ()>
 {
     /// **Stage 2:** method taking `&mut self`.
@@ -150,7 +150,7 @@ impl<'ts, 'c, CSig: WithBaseField, CRcv: GodotClass, Ps: ParamTuple>
     >
     where
         CRcv: GodotClass + Bounds<Declarer = bounds::DeclUser>,
-        for<'c_rcv> F: AsFunc<&'c_rcv mut CRcv, Ps>,
+        for<'c_rcv> F: SignalReceiver<&'c_rcv mut CRcv, Ps>,
     {
         let mut gd: Gd<CRcv> = self.receiver_obj;
 
@@ -189,7 +189,7 @@ impl<'ts, 'c, CSig: WithBaseField, CRcv: GodotClass, Ps: ParamTuple>
     >
     where
         CRcv: GodotClass + Bounds<Declarer = bounds::DeclUser>,
-        for<'c_rcv> F: AsFunc<&'c_rcv CRcv, Ps>,
+        for<'c_rcv> F: SignalReceiver<&'c_rcv CRcv, Ps>,
     {
         let gd: Gd<CRcv> = self.receiver_obj;
 
@@ -218,7 +218,7 @@ impl<'ts, 'c, CSig: WithBaseField, CRcv: GodotClass, Ps: ParamTuple>
 impl<'ts, 'c, CSig, CRcv, Ps, GodotFn> ConnectBuilder<'ts, 'c, CSig, CRcv, Ps, GodotFn>
 where
     CSig: WithBaseField,
-    Ps: ParamTuple,
+    Ps: meta::ParamTuple,
     GodotFn: FnMut(&[&Variant]) -> Result<Variant, ()> + 'static,
 {
     /// **Stage 3:** allow signal to be called across threads.

godot-core/src/registry/functional/mod.rs renamed to godot-core/src/registry/signal/mod.rs

@@ -7,8 +7,9 @@
 
 mod connect_builder;
 mod typed_signal;
-mod variadic;
+pub(crate) mod variadic;
 
 pub use connect_builder::*;
 pub use typed_signal::*;
-pub use variadic::*;
+pub use variadic::SignalReceiver;
+// ParamTuple re-exported in crate::meta.

godot-core/src/registry/functional/typed_signal.rs renamed to godot-core/src/registry/signal/typed_signal.rs

@@ -5,19 +5,18 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-// Maybe move this to builtin::functional module?
-
 use crate::builtin::{Callable, GString, Variant};
 use crate::classes::object::ConnectFlags;
 use crate::obj::{bounds, Bounds, Gd, GodotClass, WithBaseField};
-use crate::registry::functional::{AsFunc, ConnectBuilder, ParamTuple};
+use crate::registry::signal::{ConnectBuilder, SignalReceiver};
 use crate::{classes, meta};
 use std::borrow::Cow;
 use std::marker::PhantomData;
 
+/// Links to a Godot object, either via reference (for `&mut self` uses) or via `Gd`.
 #[doc(hidden)]
 pub enum ObjectRef<'a, C: GodotClass> {
-    /// Helpful for emit: reuse `&self` from within the `impl` block, goes through `base()` re-borrowing and thus allows re-entrant calls
+    /// Helpful for emit: reuse `&mut self` from within the `impl` block, goes through `base_mut()` re-borrowing and thus allows re-entrant calls
     /// through Godot.
     Internal { obj_mut: &'a mut C },
 
@@ -46,15 +45,38 @@ where
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
+/// Type-safe version of a Godot signal.
+///
+/// Short-lived type, only valid in the scope of its surrounding object type `C`, for lifetime `'c`. The generic argument `Ps` represents
+/// the parameters of the signal, thus ensuring the type safety.
+///
+/// The [`WithSignals::signals()`][crate::obj::WithSignals::signals] collection returns multiple signals with distinct, code-generated types,
+/// but they all implement `Deref` and `DerefMut` to `TypedSignal`. This allows you to either use the concrete APIs of the generated types,
+/// or the more generic ones of `TypedSignal`.
+///
+/// # Connecting a signal to a receiver
+/// Receiver functions are functions that are called when a signal is emitted. You can connect a signal in many different ways:
+/// - [`connect()`][Self::connect] for global functions, associated functions or closures.
+/// - [`connect_self()`][Self::connect_self] for methods with `&mut self` as the first parameter.
+/// - [`connect_obj()`][Self::connect_obj] for methods with any `Gd<T>` (not `self`) as the first parameter.
+/// - [`connect_builder()`][Self::connect_builder] for more complex setups.
+///
+/// # Emitting a signal
+/// Code-generated signal types provide a method `emit(...)`, which adopts the names and types of the `#[signal]` parameter list.
+/// In most cases, that's the method you are looking for.
+///
+/// For generic use, you can also use [`emit_tuple()`][Self::emit_tuple], which does not provide parameter names.
+///
+/// # More information
+/// See the [Signals](https://godot-rust.github.io/book/register/signals.html) chapter in the book for a detailed introduction and examples.
 pub struct TypedSignal<'c, C: GodotClass, Ps> {
-    //signal: Signal,
     /// In Godot, valid signals (unlike funcs) are _always_ declared in a class and become part of each instance. So there's always an object.
     owner: ObjectRef<'c, C>,
     name: Cow<'static, str>,
     _signature: PhantomData<Ps>,
 }
 
-impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
+impl<'c, C: WithBaseField, Ps: meta::ParamTuple> TypedSignal<'c, C, Ps> {
     #[doc(hidden)]
     pub fn new(owner: ObjectRef<'c, C>, name: &'static str) -> Self {
         Self {
@@ -68,11 +90,15 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
         self.owner.to_owned()
     }
 
-    pub fn emit(&mut self, params: Ps) {
+    /// Emit the signal with the given parameters.
+    ///
+    /// This is intended for generic use. Typically, you'll want to use the more specific `emit()` method of the code-generated signal
+    /// type, which also has named parameters.
+    pub fn emit_tuple(&mut self, args: Ps) {
         let name = self.name.as_ref();
 
         self.owner.with_object_mut(|obj| {
-            obj.emit_signal(name, &params.to_variant_array());
+            obj.emit_signal(name, &args.to_variant_array());
         });
     }
 
@@ -85,10 +111,11 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
     /// sig.connect(|arg| { /* closure */ });
     /// ```
     ///
-    /// To connect to a method of the own object `self`, use [`connect_self()`][Self::connect_self].
+    /// To connect to a method of the own object `self`, use [`connect_self()`][Self::connect_self].  \
+    /// If you need cross-thread signals or connect flags, use [`connect_builder()`][Self::connect_builder].
     pub fn connect<F>(&mut self, mut function: F)
     where
-        F: AsFunc<(), Ps>,
+        F: SignalReceiver<(), Ps>,
     {
         let callable_name = std::any::type_name_of_val(&function);
 
@@ -103,9 +130,12 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
     }
 
     /// Connect a method (member function) with `&mut self` as the first parameter.
+    ///
+    /// To connect to methods on other objects, use [`connect_obj()`][Self::connect_obj].  \
+    /// If you need a `&self` receiver, cross-thread signals or connect flags, use [`connect_builder()`][Self::connect_builder].
     pub fn connect_self<F>(&mut self, mut function: F)
     where
-        for<'c_rcv> F: AsFunc<&'c_rcv mut C, Ps>,
+        for<'c_rcv> F: SignalReceiver<&'c_rcv mut C, Ps>,
     {
         // When using sys::short_type_name() in the future, make sure global "func" and member "MyClass::func" are rendered as such.
         // PascalCase heuristic should then be good enough.
@@ -132,11 +162,12 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
 
     /// Connect a method (member function) with any `Gd<T>` (not `self`) as the first parameter.
     ///
-    /// To connect to methods on the same object, use [`connect_self()`][Self::connect_self].
+    /// To connect to methods on the same object that declares the `#[signal]`, use [`connect_self()`][Self::connect_self].  \
+    /// If you need cross-thread signals or connect flags, use [`connect_builder()`][Self::connect_builder].
     pub fn connect_obj<F, OtherC>(&mut self, object: &Gd<OtherC>, mut function: F)
     where
         OtherC: GodotClass + Bounds<Declarer = bounds::DeclUser>,
-        for<'c_rcv> F: AsFunc<&'c_rcv mut OtherC, Ps>,
+        for<'c_rcv> F: SignalReceiver<&'c_rcv mut OtherC, Ps>,
     {
         let callable_name = std::any::type_name_of_val(&function);
 
@@ -154,6 +185,14 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
         self.inner_connect_local(callable_name, godot_fn);
     }
 
+    /// Fully customizable connection setup.
+    ///
+    /// The returned builder provides several methods to configure how to connect the signal. It needs to be finalized with a call to
+    /// [`ConnectBuilder::done()`].
+    pub fn connect_builder(&mut self) -> ConnectBuilder<'_, 'c, C, (), Ps, ()> {
+        ConnectBuilder::new(self)
+    }
+
     fn inner_connect_local<F>(&mut self, callable_name: impl meta::AsArg<GString>, godot_fn: F)
     where
         F: FnMut(&[&Variant]) -> Result<Variant, ()> + 'static,
@@ -179,8 +218,4 @@ impl<'c, C: WithBaseField, Ps: ParamTuple> TypedSignal<'c, C, Ps> {
             c.done();
         });
     }
-
-    pub fn connect_builder(&mut self) -> ConnectBuilder<'_, 'c, C, (), Ps, ()> {
-        ConnectBuilder::new(self)
-    }
 }

godot-core/src/registry/functional/variadic.rs renamed to godot-core/src/registry/signal/variadic.rs

@@ -14,14 +14,65 @@
 use crate::builtin::Variant;
 use crate::meta;
 
-pub trait AsFunc<I, Ps>: 'static {
+/// Trait that is implemented for functions that can be connected to signals.
+///
+// Direct RustDoc link doesn't work, for whatever reason again...
+/// This is used in [`ConnectBuilder`](struct.ConnectBuilder.html). There are three variations of the `I` (instance) parameter:
+/// - `()` for global and associated ("static") functions.
+/// - `&C` for `&self` methods.
+/// - `&mut C` for `&mut self` methods.
+///
+/// See also [Signals](https://godot-rust.github.io/book/register/signals.html) in the book.
+pub trait SignalReceiver<I, Ps>: 'static {
+    /// Invoke the receiver on the given instance (possibly `()`) with `params`.
     fn call(&mut self, maybe_instance: I, params: Ps);
 }
 
+/// Represents a parameter list as Rust tuple.
+///
+/// Each tuple element is one parameter. This trait provides conversions to and from `Variant` arrays.
+// Re-exported under crate::meta. Might be worth splitting, but depends a bit on SignatureVarcall/Ptrcall refactoring.
+pub trait ParamTuple {
+    fn to_variant_array(&self) -> Vec<Variant>;
+    fn from_variant_array(array: &[&Variant]) -> Self;
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Generated impls
+
 macro_rules! impl_signal_recipient {
     ($( $args:ident : $Ps:ident ),*) => {
+        // --------------------------------------------------------------------------------------------------------------------------------------
+        // ParamTuple
+
+        impl<$($Ps),*> ParamTuple for ($($Ps,)*)
+        where
+            $($Ps: meta::ToGodot + meta::FromGodot),*
+        {
+            fn to_variant_array(&self) -> Vec<Variant> {
+                let ($($args,)*) = self;
+
+                vec![
+                    $( $args.to_variant(), )*
+                ]
+            }
+
+            #[allow(unused_variables, unused_mut, clippy::unused_unit)]
+            fn from_variant_array(array: &[&Variant]) -> Self {
+               let mut iter = array.iter();
+               ( $(
+                  <$Ps>::from_variant(
+                        iter.next().unwrap_or_else(|| panic!("ParamTuple: {} access out-of-bounds (len {})", stringify!($args), array.len()))
+                  ),
+               )* )
+            }
+        }
+
+        // --------------------------------------------------------------------------------------------------------------------------------------
+        // SignalReceiver
+
         // Global and associated functions.
-        impl<F, R, $($Ps,)*> AsFunc<(), ( $($Ps,)* )> for F
+        impl<F, R, $($Ps,)*> SignalReceiver<(), ( $($Ps,)* )> for F
             where F: FnMut( $($Ps,)* ) -> R + 'static
         {
             fn call(&mut self, _no_instance: (), ($($args,)*): ( $($Ps,)* )) {
@@ -30,7 +81,7 @@ macro_rules! impl_signal_recipient {
         }
 
         // Methods with mutable receiver - &mut self.
-        impl<F, R, C, $($Ps,)*> AsFunc<&mut C, ( $($Ps,)* )> for F
+        impl<F, R, C, $($Ps,)*> SignalReceiver<&mut C, ( $($Ps,)* )> for F
             where F: FnMut( &mut C, $($Ps,)* ) -> R + 'static
         {
             fn call(&mut self, instance: &mut C, ($($args,)*): ( $($Ps,)* )) {
@@ -39,7 +90,7 @@ macro_rules! impl_signal_recipient {
         }
 
         // Methods with immutable receiver - &self.
-        impl<F, R, C, $($Ps,)*> AsFunc<&C, ( $($Ps,)* )> for F
+        impl<F, R, C, $($Ps,)*> SignalReceiver<&C, ( $($Ps,)* )> for F
             where F: FnMut( &C, $($Ps,)* ) -> R + 'static
         {
             fn call(&mut self, instance: &C, ($($args,)*): ( $($Ps,)* )) {
@@ -53,42 +104,10 @@ impl_signal_recipient!();
 impl_signal_recipient!(arg0: P0);
 impl_signal_recipient!(arg0: P0, arg1: P1);
 impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2);
-
-// ----------------------------------------------------------------------------------------------------------------------------------------------
-
-pub trait ParamTuple {
-    fn to_variant_array(&self) -> Vec<Variant>;
-    fn from_variant_array(array: &[&Variant]) -> Self;
-}
-
-macro_rules! impl_param_tuple {
-    ($($args:ident : $Ps:ident),*) => {
-        impl<$($Ps),*> ParamTuple for ($($Ps,)*)
-        where
-            $($Ps: meta::ToGodot + meta::FromGodot),*
-        {
-            fn to_variant_array(&self) -> Vec<Variant> {
-                let ($($args,)*) = self;
-
-                vec![
-                    $( $args.to_variant(), )*
-                ]
-            }
-
-            #[allow(unused_variables, unused_mut, clippy::unused_unit)]
-            fn from_variant_array(array: &[&Variant]) -> Self {
-               let mut iter = array.iter();
-               ( $(
-                  <$Ps>::from_variant(
-                        iter.next().unwrap_or_else(|| panic!("ParamTuple: {} access out-of-bounds (len {})", stringify!($args), array.len()))
-                  ),
-               )* )
-            }
-        }
-    };
-}
-
-impl_param_tuple!();
-impl_param_tuple!(arg0: P0);
-impl_param_tuple!(arg0: P0, arg1: P1);
-impl_param_tuple!(arg0: P0, arg1: P1, arg2: P2);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8);
+impl_signal_recipient!(arg0: P0, arg1: P1, arg2: P2, arg3: P3, arg4: P4, arg5: P5, arg6: P6, arg7: P7, arg8: P8, arg9: P9);

godot-macros/src/class/data_models/signal.rs

@@ -257,7 +257,7 @@ fn make_signal_individual_struct(details: &SignalDetails) -> TokenStream {
         #(#signal_cfg_attrs)*
         impl #individual_struct_name<'_> {
             pub fn emit(&mut self, #emit_params) {
-                self.typed.emit((#( #param_names, )*));
+                self.typed.emit_tuple((#( #param_names, )*));
             }
         }