Attribute Macro bridge

#[bridge]

Defines a future or stream type that can be awaited from both Rust and C++.

Invoke this macro like so:

#[cxx_async::bridge]
unsafe impl Future for RustFutureString {
    type Output = String;
}

Here, RustFutureString is the name of the future type declared inside the extern Rust { ... } block inside the #[cxx::bridge] module. String is the Rust type that the future yields when awaited; on the Rust side it will be automatically wrapped in a CxxAsyncResult. On the C++ side it will be converted to the appropriate type, following the cxx rules. Err returns are translated into C++ exceptions.

If the future is inside a C++ namespace, add a namespace = ... attribute to the #[cxx_async::bridge] attribute like so:

#[cxx::bridge]
#[namespace = mycompany::myproject]
mod ffi {
    extern "Rust" {
        type RustFutureStringNamespaced;
    }
}

#[cxx_async::bridge(namespace = mycompany::myproject)]
unsafe impl Future for RustFutureStringNamespaced {
    type Output = String;
}

Safety

It’s the programmer’s responsibility to ensure that the specified Output type correctly reflects the type of the value that any returned C++ future resolves to. cxx_async can’t currently check to ensure that these types match. If the types don’t match, undefined behavior can result. See the cxx documentation for information on the mapping between Rust types and C++ types.