Async naming updates and doc fixes

After implementing foreign futures these in JS, I wanted to make some
updates.  The FFI is staying the same, but some names have been changed.

`UniffiForeignFutureFree` is now named `UniffiForeignFutureDroppedCallback` and
`UniffiForeignFuture` is now `UniffiForeignFutureDroppedCallbackStruct`.
This reflects the fact that we don't really need to use these to manage
the future, the real reason they're here nowadays is to support
cancellation. For languages like JS, where we can't implement
cancellation, we can just ignore these structs and the param.

Updated some of the code that deals with this to treat it like the out
parameter it is, rather than a return value.  I think that was leftover
from previous implementations.

There's also one change for RustFuture: `RustFuturePoll::MaybeReady` is
now `RustFuturePoll::Wake`.  "MaybeReady" was always a
confusing/ambiguous name.  "Wake" seems reasonable, since it's what the
foreign bindings should do and reflects how the Rust futures code works.

Updated some outdated docstrings.

Author: bendk

CHANGELOG.md

@@ -18,6 +18,15 @@
 
 [All changes in [[UnreleasedUniFFIVersion]]](https://github.com/mozilla/uniffi-rs/compare/v0.29.1...HEAD).
 
+### ⚠️ Breaking Changes for external bindings authors ⚠️
+
+* Some async-related names have changed.  Bindings authors may need to update their code to reflect
+  the new names.  This is a name-change only -- the FFI and semantics are still the same.
+
+  * `UniffiForeignFutureFree` is now `UniffiForeignFutureDroppedCallback`
+  * `UniffiForeignFuture` is `UniffiForeignFutureDroppedCallbackStruct`.
+  * `RustFuturePoll::MaybeReady` is now `RustFuturePoll::Wake`.
+
 ## v0.29.1 (backend crates: v0.29.1) - (_2025-03-18_)
 
 ### What's fixed?

docs/manual/src/internals/async-overview.md

@@ -51,9 +51,8 @@ The UniFFI generated code for an async function performs these steps:
 
 1. Call the Rust scaffolding function, receiving a `RustFuture` handle
 1. Call the `rust_future_poll` function for the future until the future is ready.
-   * The `rust_future_poll` function inputs a callback function and an opaque pointer (AKA a `void *`) to call the callback with.
-   * If the future is pending, then the generated code registers a waker that will call the callback function with `RUST_FUTURE_MAYBE_READY`.
-     When the generated foreign code sees this, it calls poll again, starting the loop over.
+   * The `rust_future_poll` function inputs a callback function and a `u64` callback data value to pass to the callback.
+   * If the future is pending, then the generated code registers a waker that will call the callback function with `RUST_FUTURE_WAKE`.
    * If the future is ready, then the callback function is immediately called with `RUST_FUTURE_READY` and we move to the next step.
 1. Call `rust_future_complete`, receiving the return value of the future
 1. Call `rust_future_free` (ideally in a `finally` block)

uniffi_bindgen/src/bindings/kotlin/templates/Async.kt

@@ -1,7 +1,7 @@
 // Async return type handlers
 
 internal const val UNIFFI_RUST_FUTURE_POLL_READY = 0.toByte()
-internal const val UNIFFI_RUST_FUTURE_POLL_MAYBE_READY = 1.toByte()
+internal const val UNIFFI_RUST_FUTURE_POLL_WAKE = 1.toByte()
 
 internal val uniffiContinuationHandleMap = UniffiHandleMap<CancellableContinuation<Byte>>()
 
@@ -44,12 +44,13 @@ internal inline fun<T> uniffiTraitInterfaceCallAsync(
     crossinline makeCall: suspend () -> T,
     crossinline handleSuccess: (T) -> Unit,
     crossinline handleError: (UniffiRustCallStatus.ByValue) -> Unit,
-): UniffiForeignFuture {
+    uniffiOutDroppedCallback: UniffiForeignFutureDroppedCallbackStruct,
+) {
     // Using `GlobalScope` is labeled as a "delicate API" and generally discouraged in Kotlin programs, since it breaks structured concurrency.
     // However, our parent task is a Rust future, so we're going to need to break structure concurrency in any case.
     //
     // Uniffi does its best to support structured concurrency across the FFI.
-    // If the Rust future is dropped, `uniffiForeignFutureFreeImpl` is called, which will cancel the Kotlin coroutine if it's still running.
+    // If the Rust future is dropped, `uniffiForeignFutureDroppedCallbackImpl` is called, which will cancel the Kotlin coroutine if it's still running.
     @OptIn(DelicateCoroutinesApi::class)
     val job = GlobalScope.launch {
         try {
@@ -64,15 +65,16 @@ internal inline fun<T> uniffiTraitInterfaceCallAsync(
         }
     }
     val handle = uniffiForeignFutureHandleMap.insert(job)
-    return UniffiForeignFuture(handle, uniffiForeignFutureFreeImpl)
+    uniffiOutDroppedCallback.uniffiSetValue(UniffiForeignFutureDroppedCallbackStruct(handle, uniffiForeignFutureDroppedCallbackImpl))
 }
 
 internal inline fun<T, reified E: Throwable> uniffiTraitInterfaceCallAsyncWithError(
     crossinline makeCall: suspend () -> T,
     crossinline handleSuccess: (T) -> Unit,
     crossinline handleError: (UniffiRustCallStatus.ByValue) -> Unit,
     crossinline lowerError: (E) -> RustBuffer.ByValue,
-): UniffiForeignFuture {
+    uniffiOutDroppedCallback: UniffiForeignFutureDroppedCallbackStruct,
+) {
     // See uniffiTraitInterfaceCallAsync for details on `DelicateCoroutinesApi`
     @OptIn(DelicateCoroutinesApi::class)
     val job = GlobalScope.launch {
@@ -97,12 +99,12 @@ internal inline fun<T, reified E: Throwable> uniffiTraitInterfaceCallAsyncWithEr
         }
     }
     val handle = uniffiForeignFutureHandleMap.insert(job)
-    return UniffiForeignFuture(handle, uniffiForeignFutureFreeImpl)
+    uniffiOutDroppedCallback.uniffiSetValue(UniffiForeignFutureDroppedCallbackStruct(handle, uniffiForeignFutureDroppedCallbackImpl))
 }
 
 internal val uniffiForeignFutureHandleMap = UniffiHandleMap<Job>()
 
-internal object uniffiForeignFutureFreeImpl: UniffiForeignFutureFree {
+internal object uniffiForeignFutureDroppedCallbackImpl: UniffiForeignFutureDroppedCallback {
     override fun callback(handle: Long) {
         val job = uniffiForeignFutureHandleMap.remove(handle)
         if (!job.isCompleted) {

uniffi_bindgen/src/bindings/kotlin/templates/CallbackInterfaceImpl.kt

@@ -67,23 +67,23 @@ internal object {{ trait_impl }} {
                 )
             }
 
-            uniffiOutReturn.uniffiSetValue(
-                {%- match meth.throws_type() %}
-                {%- when None %}
-                uniffiTraitInterfaceCallAsync(
-                    makeCall,
-                    uniffiHandleSuccess,
-                    uniffiHandleError
-                )
-                {%- when Some(error_type) %}
-                uniffiTraitInterfaceCallAsyncWithError(
-                    makeCall,
-                    uniffiHandleSuccess,
-                    uniffiHandleError,
-                    { e: {{error_type|type_name(ci) }} -> {{ error_type|lower_fn }}(e) }
-                )
-                {%- endmatch %}
+            {%- match meth.throws_type() %}
+            {%- when None %}
+            uniffiTraitInterfaceCallAsync(
+                makeCall,
+                uniffiHandleSuccess,
+                uniffiHandleError,
+                uniffiOutDroppedCallback
             )
+            {%- when Some(error_type) %}
+            uniffiTraitInterfaceCallAsyncWithError(
+                makeCall,
+                uniffiHandleSuccess,
+                uniffiHandleError,
+                { e: {{error_type|type_name(ci) }} -> {{ error_type|lower_fn }}(e) },
+                uniffiOutDroppedCallback
+            )
+            {%- endmatch %}
             {%- endif %}
         }
     }

uniffi_bindgen/src/bindings/python/templates/Async.py

@@ -1,6 +1,6 @@
 # RustFuturePoll values
 _UNIFFI_RUST_FUTURE_POLL_READY = 0
-_UNIFFI_RUST_FUTURE_POLL_MAYBE_READY = 1
+_UNIFFI_RUST_FUTURE_POLL_WAKE = 1
 
 # Stores futures for _uniffi_continuation_callback
 _UniffiContinuationHandleMap = _UniffiHandleMap()
@@ -63,7 +63,7 @@ async def _uniffi_rust_call_async(rust_future, ffi_poll, ffi_complete, ffi_free,
         ffi_free(rust_future)
 
 {%- if ci.has_async_callback_interface_definition() %}
-def _uniffi_trait_interface_call_async(make_call, handle_success, handle_error):
+def _uniffi_trait_interface_call_async(make_call, uniffi_out_dropped_callback, handle_success, handle_error):
     async def make_call_and_call_callback():
         try:
             handle_success(await make_call())
@@ -77,9 +77,9 @@ async def make_call_and_call_callback():
     eventloop = _uniffi_get_event_loop()
     task = asyncio.run_coroutine_threadsafe(make_call_and_call_callback(), eventloop)
     handle = _UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.insert((eventloop, task))
-    return _UniffiForeignFuture(handle, _uniffi_foreign_future_free)
+    uniffi_out_dropped_callback[0] = _UniffiForeignFutureDroppedCallbackStruct(handle, _uniffi_future_dropped_callback)
 
-def _uniffi_trait_interface_call_async_with_error(make_call, handle_success, handle_error, error_type, lower_error):
+def _uniffi_trait_interface_call_async_with_error(make_call, uniffi_out_dropped_callback, handle_success, handle_error, error_type, lower_error):
     async def make_call_and_call_callback():
         try:
             try:
@@ -99,16 +99,16 @@ async def make_call_and_call_callback():
     eventloop = _uniffi_get_event_loop()
     task = asyncio.run_coroutine_threadsafe(make_call_and_call_callback(), eventloop)
     handle = _UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.insert((eventloop, task))
-    return _UniffiForeignFuture(handle, _uniffi_foreign_future_free)
+    uniffi_out_dropped_callback[0] = _UniffiForeignFutureDroppedCallbackStruct(handle, _uniffi_future_dropped_callback)
 
 _UNIFFI_FOREIGN_FUTURE_HANDLE_MAP = _UniffiHandleMap()
 
-@_UNIFFI_FOREIGN_FUTURE_FREE
-def _uniffi_foreign_future_free(handle):
+@_UNIFFI_FOREIGN_FUTURE_DROPPED_CALLBACK
+def _uniffi_future_dropped_callback(handle):
     (eventloop, task) = _UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.remove(handle)
-    eventloop.call_soon(_uniffi_foreign_future_do_free, task)
+    eventloop.call_soon(_uniffi_cancel_task, task)
 
-def _uniffi_foreign_future_do_free(task):
+def _uniffi_cancel_task(task):
     if not task.done():
         task.cancel()
 {%- endif %}

uniffi_bindgen/src/bindings/python/templates/CallbackInterfaceImpl.py

@@ -72,9 +72,9 @@ def handle_error(status_code, rust_buffer):
 
         {%- match meth.throws_type() %}
         {%- when None %}
-        uniffi_out_return[0] = _uniffi_trait_interface_call_async(make_call, handle_success, handle_error)
+        _uniffi_trait_interface_call_async(make_call, uniffi_out_dropped_callback, handle_success, handle_error)
         {%- when Some(error) %}
-        uniffi_out_return[0] = _uniffi_trait_interface_call_async_with_error(make_call, handle_success, handle_error, {{ error|type_name }}, {{ error|lower_fn }})
+        _uniffi_trait_interface_call_async_with_error(make_call, uniffi_out_dropped_callback, handle_success, handle_error, {{ error|type_name }}, {{ error|lower_fn }})
         {%- endmatch %}
         {%- endif %}
     {%- endfor %}

uniffi_bindgen/src/bindings/swift/templates/Async.swift

@@ -1,5 +1,5 @@
 private let UNIFFI_RUST_FUTURE_POLL_READY: Int8 = 0
-private let UNIFFI_RUST_FUTURE_POLL_MAYBE_READY: Int8 = 1
+private let UNIFFI_RUST_FUTURE_POLL_WAKE: Int8 = 1
 
 fileprivate let uniffiContinuationHandleMap = UniffiHandleMap<UnsafeContinuation<Int8, Never>>()
 
@@ -49,8 +49,9 @@ fileprivate func uniffiFutureContinuationCallback(handle: UInt64, pollResult: In
 private func uniffiTraitInterfaceCallAsync<T>(
     makeCall: @escaping () async throws -> T,
     handleSuccess: @escaping (T) -> (),
-    handleError: @escaping (Int8, RustBuffer) -> ()
-) -> UniffiForeignFuture {
+    handleError: @escaping (Int8, RustBuffer) -> (),
+    droppedCallback: UnsafeMutablePointer<UniffiForeignFutureDroppedCallbackStruct>
+) {
     let task = Task {
         do {
             handleSuccess(try await makeCall())
@@ -59,16 +60,19 @@ private func uniffiTraitInterfaceCallAsync<T>(
         }
     }
     let handle = UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.insert(obj: task)
-    return UniffiForeignFuture(handle: handle, free: uniffiForeignFutureFree)
-
+    droppedCallback.pointee = UniffiForeignFutureDroppedCallbackStruct(
+        handle: handle,
+        free: uniffiForeignFutureDroppedCallback
+    )
 }
 
 private func uniffiTraitInterfaceCallAsyncWithError<T, E>(
     makeCall: @escaping () async throws -> T,
     handleSuccess: @escaping (T) -> (),
     handleError: @escaping (Int8, RustBuffer) -> (),
-    lowerError: @escaping (E) -> RustBuffer
-) -> UniffiForeignFuture {
+    lowerError: @escaping (E) -> RustBuffer,
+    droppedCallback: UnsafeMutablePointer<UniffiForeignFutureDroppedCallbackStruct>
+) {
     let task = Task {
         do {
             handleSuccess(try await makeCall())
@@ -79,7 +83,10 @@ private func uniffiTraitInterfaceCallAsyncWithError<T, E>(
         }
     }
     let handle = UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.insert(obj: task)
-    return UniffiForeignFuture(handle: handle, free: uniffiForeignFutureFree)
+    droppedCallback.pointee = UniffiForeignFutureDroppedCallbackStruct(
+        handle: handle,
+        free: uniffiForeignFutureDroppedCallback
+    )
 }
 
 // Borrow the callback handle map implementation to store foreign future handles
@@ -96,15 +103,15 @@ fileprivate protocol UniffiForeignFutureTask {
 
 extension Task: UniffiForeignFutureTask {}
 
-private func uniffiForeignFutureFree(handle: UInt64) {
+private func uniffiForeignFutureDroppedCallback(handle: UInt64) {
     do {
         let task = try UNIFFI_FOREIGN_FUTURE_HANDLE_MAP.remove(handle: handle)
         // Set the cancellation flag on the task.  If it's still running, the code can check the
         // cancellation flag or call `Task.checkCancellation()`.  If the task has completed, this is
         // a no-op.
         task.cancel()
     } catch {
-        print("uniffiForeignFutureFree: handle missing from handlemap")
+        print("uniffiForeignFutureDroppedCallback: handle missing from handlemap")
     }
 }
 

uniffi_bindgen/src/bindings/swift/templates/CallbackInterfaceImpl.swift

@@ -80,20 +80,21 @@ fileprivate struct {{ trait_impl }} {
 
             {%- match meth.throws_type() %}
             {%- when None %}
-            let uniffiForeignFuture = uniffiTraitInterfaceCallAsync(
+            uniffiTraitInterfaceCallAsync(
                 makeCall: makeCall,
                 handleSuccess: uniffiHandleSuccess,
-                handleError: uniffiHandleError
+                handleError: uniffiHandleError,
+                droppedCallback: uniffiOutDroppedCallback
             )
             {%- when Some(error_type) %}
-            let uniffiForeignFuture = uniffiTraitInterfaceCallAsyncWithError(
+            uniffiTraitInterfaceCallAsyncWithError(
                 makeCall: makeCall,
                 handleSuccess: uniffiHandleSuccess,
                 handleError: uniffiHandleError,
-                lowerError: {{ error_type|lower_fn }}
+                lowerError: {{ error_type|lower_fn }},
+                droppedCallback: uniffiOutDroppedCallback
             )
             {%- endmatch %}
-            uniffiOutReturn.pointee = uniffiForeignFuture
             {%- endif %}
         },
         {%- endfor %}

uniffi_bindgen/src/interface/callbacks.rs

@@ -180,8 +180,9 @@ pub fn method_ffi_callback(trait_name: &str, method: &Method, index: usize) -> F
                     ),
                     FfiArgument::new("uniffi_callback_data", FfiType::UInt64),
                     FfiArgument::new(
-                        "uniffi_out_return",
-                        FfiType::Struct("ForeignFuture".to_owned()).mut_reference(),
+                        "uniffi_out_dropped_callback",
+                        FfiType::Struct("ForeignFutureDroppedCallbackStruct".to_owned())
+                            .mut_reference(),
                     ),
                 ])
                 .collect(),
@@ -196,7 +197,7 @@ pub fn foreign_future_ffi_result_struct(return_ffi_type: Option<FfiType>) -> Ffi
     let return_type_name =
         FfiType::return_type_name(return_ffi_type.as_ref()).to_upper_camel_case();
     FfiStruct {
-        name: format!("ForeignFutureStruct{return_type_name}"),
+        name: format!("ForeignFutureResult{return_type_name}"),
         fields: match return_ffi_type {
             Some(return_ffi_type) => vec![
                 FfiField::new("return_value", return_ffi_type),
@@ -222,7 +223,7 @@ pub fn ffi_foreign_future_complete(return_ffi_type: Option<FfiType>) -> FfiCallb
             FfiArgument::new("callback_data", FfiType::UInt64),
             FfiArgument::new(
                 "result",
-                FfiType::Struct(format!("ForeignFutureStruct{return_type_name}")),
+                FfiType::Struct(format!("ForeignFutureResult{return_type_name}")),
             ),
         ],
         return_type: None,

uniffi_bindgen/src/interface/mod.rs

@@ -658,7 +658,7 @@ impl ComponentInterface {
             }
             .into(),
             FfiCallbackFunction {
-                name: "ForeignFutureFree".to_owned(),
+                name: "ForeignFutureDroppedCallback".to_owned(),
                 arguments: vec![FfiArgument::new("handle", FfiType::UInt64)],
                 return_type: None,
                 has_rust_call_status_arg: false,
@@ -672,10 +672,13 @@ impl ComponentInterface {
             }
             .into(),
             FfiStruct {
-                name: "ForeignFuture".to_owned(),
+                name: "ForeignFutureDroppedCallbackStruct".to_owned(),
                 fields: vec![
                     FfiField::new("handle", FfiType::UInt64),
-                    FfiField::new("free", FfiType::Callback("ForeignFutureFree".to_owned())),
+                    FfiField::new(
+                        "free",
+                        FfiType::Callback("ForeignFutureDroppedCallback".to_owned()),
+                    ),
                 ],
             }
             .into(),

uniffi_core/src/ffi/ffidefault.rs

@@ -53,13 +53,6 @@ impl FfiDefault for crate::RustBuffer {
     }
 }
 
-impl FfiDefault for crate::ForeignFuture {
-    fn ffi_default() -> Self {
-        extern "C" fn free(_handle: u64) {}
-        crate::ForeignFuture { handle: 0, free }
-    }
-}
-
 impl<T> FfiDefault for Option<T> {
     fn ffi_default() -> Self {
         None