Add Callable::from_once_fn() for one-time calls

Author: Bromeon

godot-core/src/builtin/callable.rs

@@ -11,10 +11,10 @@ use godot_ffi as sys;
 use sys::{ffi_methods, ExtVariantType, GodotFfi};
 
 use crate::builtin::{inner, GString, StringName, Variant, VariantArray};
-use crate::classes;
 use crate::meta::{GodotType, ToGodot};
 use crate::obj::bounds::DynMemory;
 use crate::obj::{Bounds, Gd, GodotClass, InstanceId};
+use crate::{classes, meta};
 
 #[cfg(all(since_api = "4.2", before_api = "4.3"))]
 type CallableCustomInfo = sys::GDExtensionCallableCustomInfo;
@@ -181,6 +181,40 @@ impl Callable {
         })
     }
 
+    /// Create callable from **single-threaded** Rust function or closure that can only be called once.
+    ///
+    /// `name` is used for the string representation of the closure, which helps debugging.
+    ///
+    /// After the first invocation, subsequent calls will panic with a message indicating the callable has already been consumed. This is
+    /// useful for deferred operations that should only execute once. For repeated execution, use [`from_local_fn()][Self::from_local_fn].
+    #[cfg(since_api = "4.2")]
+    pub(crate) fn from_once_fn<F, S>(name: S, rust_function: F) -> Self
+    where
+        F: 'static + FnOnce(&[&Variant]) -> Result<Variant, ()>,
+        S: meta::AsArg<GString>,
+    {
+        meta::arg_into_owned!(name);
+
+        let mut rust_fn_once = Some(rust_function);
+        Self::from_local_fn(&name, move |args| {
+            let rust_fn_once = rust_fn_once
+                .take()
+                .expect("callable created with from_once_fn() has already been consumed");
+            rust_fn_once(args)
+        })
+    }
+
+    #[cfg(feature = "trace")] // Test only.
+    #[cfg(since_api = "4.2")]
+    #[doc(hidden)]
+    pub fn __once_fn<F, S>(name: S, rust_function: F) -> Self
+    where
+        F: 'static + FnOnce(&[&Variant]) -> Result<Variant, ()>,
+        S: meta::AsArg<GString>,
+    {
+        Self::from_once_fn(name, rust_function)
+    }
+
     #[cfg(since_api = "4.2")]
     pub(crate) fn with_scoped_fn<S, F, Fc, R>(name: S, rust_function: F, callable_usage: Fc) -> R
     where
@@ -518,8 +552,6 @@ pub use custom_callable::RustCallable;
 #[cfg(since_api = "4.2")]
 use custom_callable::*;
 
-use crate::meta;
-
 #[cfg(since_api = "4.2")]
 mod custom_callable {
     use std::hash::Hash;

godot-core/src/obj/call_deferred.rs

@@ -61,14 +61,11 @@ where
             is_main_thread(),
             "`apply_deferred` must be called on the main thread"
         );
-        let mut rust_fn_once = Some(rust_function);
+
         let mut this = self.to_signal_obj().clone();
-        let callable = Callable::from_local_fn("apply_deferred", move |_| {
-            let rust_fn_once = rust_fn_once
-                .take()
-                .expect("rust_fn_once was already consumed");
+        let callable = Callable::from_once_fn("apply_deferred", move |_| {
             let mut this_mut = T::object_as_mut(&mut this);
-            rust_fn_once(this_mut.deref_mut());
+            rust_function(this_mut.deref_mut());
             Ok(Variant::nil())
         });
         callable.call_deferred(&[]);

itest/rust/src/builtin_tests/containers/callable_test.rs

@@ -648,6 +648,20 @@ pub mod custom_callable {
         assert!(signal.is_connected(&identical_callable));
     }
 
+    #[cfg(since_api = "4.2")]
+    #[itest]
+    fn callable_from_once_fn() {
+        let callable = Callable::__once_fn("once_test", move |_| Ok(42.to_variant()));
+
+        // First call should succeed.
+        let result = callable.call(&[]);
+        assert_eq!(result.to::<i32>(), 42);
+
+        // Second call should fail (panic currently isn't propagated, see other tests).
+        let result = callable.call(&[]);
+        assert!(result.is_nil());
+    }
+
     // ------------------------------------------------------------------------------------------------------------------------------------------
     // Helper structs and functions for custom callables