Merge branch 'schreter_rust_type_alias' into maizatskyi/2025-06-09-async-io-stream

Author: mikea

book/src/extern-rust.md

@@ -163,3 +163,48 @@ mod ffi {
 
 Bounds on a lifetime (like `<'a, 'b: 'a>`) are not currently supported. Nor are
 type parameters or where-clauses.
+
+## Type equivalence across bridges
+
+Similar to type aliases for C++ types, it is possible to create type aliases for
+previously-exported types via the `extern "Rust"` block in another bridge.
+However, current support is very limited:
+
+- The type name must be the same as that of the target type.
+- If the target is in a different C++ namespace, then the namespace must be
+  explicitly specified on the alias, otherwise C++ won't consider the types as
+  equivalent.
+
+Basically, this is enough to import the type from another bridge and nothing more.
+
+In the first module `crate::mod1`, you export the type:
+
+```rust,noplayground
+pub struct MyType {
+    ...
+}
+
+#[cxx::bridge(namespace = "mod1")]
+mod ffi {
+    extern "Rust" {
+        type MyType;
+    }
+}
+```
+
+And in another crate/module `mod2`, you can now import the type and use it as
+a parameter or a return value in C++ and Rust functions:
+
+```rust,noplayground
+#[cxx::bridge(namespace = "mod2")]
+mod ffi {
+    extern "Rust" {
+        #[namespace = "mod1"]
+        type MyType = crate::mod1::MyType;
+    }
+
+    extern "C++" {
+        fn c_func(param: &MyType);
+    }
+}
+```

gen/src/namespace.rs

@@ -5,8 +5,9 @@ pub fn namespace(api: &Api) -> &Namespace {
     match api {
         Api::CxxFunction(efn) | Api::RustFunction(efn) => &efn.name.namespace,
         Api::CxxType(ety) | Api::RustType(ety) => &ety.name.namespace,
+        Api::TypeAlias(ety) => &ety.name.namespace,
         Api::Enum(enm) => &enm.name.namespace,
         Api::Struct(strct) => &strct.name.namespace,
-        Api::Impl(_) | Api::Include(_) | Api::TypeAlias(_) => Default::default(),
+        Api::Impl(_) | Api::Include(_) => Default::default(),
     }
 }

gen/src/write.rs

@@ -11,8 +11,8 @@ use syntax::symbol::{self, Symbol};
 use syntax::trivial::{self, TrivialReason};
 use syntax::Lang;
 use syntax::{
-    derive, mangle, Api, Doc, Enum, EnumRepr, ExternFn, ExternType, Pair, Signature, Struct, Trait,
-    Type, TypeAlias, Types, Var,
+    derive, mangle, Api, Doc, Enum, EnumRepr, ExternFn, ExternType, Lang, Pair, Signature, Struct,
+    Trait, Type, TypeAlias, Types, Var,
 };
 
 pub fn gen(apis: &[Api], types: &Types, opt: &Opt, header: bool) -> Vec<u8> {
@@ -36,6 +36,7 @@ pub fn gen(apis: &[Api], types: &Types, opt: &Opt, header: bool) -> Vec<u8> {
 fn write_forward_declarations(out: &mut OutFile, apis: &[Api]) {
     let needs_forward_declaration = |api: &&Api| match api {
         Api::Struct(_) | Api::CxxType(_) | Api::RustType(_) => true,
+        Api::TypeAlias(ety) => ety.lang == Lang::Rust,
         Api::Enum(enm) => !out.types.cxx.contains(&enm.name.rust),
         _ => false,
     };
@@ -55,6 +56,7 @@ fn write_forward_declarations(out: &mut OutFile, apis: &[Api]) {
                 Api::Enum(enm) => write_enum_decl(out, enm),
                 Api::CxxType(ety) => write_struct_using(out, &ety.name),
                 Api::RustType(ety) => write_struct_decl(out, &ety.name),
+                Api::TypeAlias(ety) => write_struct_decl(out, &ety.name),
                 _ => unreachable!(),
             }
         }
@@ -129,8 +131,17 @@ fn write_data_structures<'a>(out: &mut OutFile<'a>, apis: &'a [Api]) {
     out.next_section();
     for api in apis {
         if let Api::TypeAlias(ety) = api {
-            if let Some(reasons) = out.types.required_trivial.get(&ety.name.rust) {
-                check_trivial_extern_type(out, ety, reasons);
+            match ety.lang {
+                Lang::Cxx => {
+                    if let Some(reasons) = out.types.required_trivial.get(&ety.name.rust) {
+                        check_trivial_extern_type(out, ety, reasons)
+                    }
+                }
+                Lang::Rust => {
+                    // nothing to write here, the alias is only used to generate
+                    // forward declaration in C++ (so C++ shims for Rust functions
+                    // using the type compile correctly).
+                }
             }
         }
     }
@@ -223,7 +234,7 @@ fn pick_includes_and_builtins(out: &mut OutFile, apis: &[Api]) {
             Type::SliceRef(_) => out.builtin.rust_slice = true,
             Type::Array(_) => out.include.array = true,
             Type::Ref(_) | Type::Void(_) | Type::Ptr(_) => {}
-            Type::Future(_) => out.include.kj_rs = true,
+            Type::Future(_) | Type::Own(_) => out.include.kj_rs = true,
         }
     }
 }
@@ -1030,6 +1041,16 @@ fn write_rust_function_shim_impl(
         return;
     }
     writeln!(out, " {{");
+    sig.args
+        .iter()
+        .filter(|arg| matches!(arg.ty, Type::Own(_)))
+        .for_each(|arg_own| {
+            writeln!(
+                out,
+                "  KJ_ASSERT({}.get() != nullptr, \"Cannot pass a null Own to Rust\");",
+                arg_own.name.cxx
+            );
+        });
     for arg in &sig.args {
         if arg.ty != RustString && out.types.needs_indirect_abi(&arg.ty) {
             out.include.utility = true;
@@ -1228,6 +1249,11 @@ fn write_type(out: &mut OutFile, ty: &Type) {
             write_type(out, &ptr.inner);
             write!(out, ">");
         }
+        Type::Own(ptr) => {
+            write!(out, "::kj::Own<");
+            write_type(out, &ptr.inner);
+            write!(out, ">");
+        }
         Type::SharedPtr(ptr) => {
             write!(out, "::std::shared_ptr<");
             write_type(out, &ptr.inner);
@@ -1328,6 +1354,7 @@ fn write_space_after_type(out: &mut OutFile, ty: &Type) {
         Type::Ident(_)
         | Type::RustBox(_)
         | Type::UniquePtr(_)
+        | Type::Own(_)
         | Type::SharedPtr(_)
         | Type::WeakPtr(_)
         | Type::Str(_)
@@ -1404,6 +1431,7 @@ fn write_generic_instantiations(out: &mut OutFile) {
             ImplKey::RustBox(ident) => write_rust_box_extern(out, ident),
             ImplKey::RustVec(ident) => write_rust_vec_extern(out, ident),
             ImplKey::UniquePtr(ident) => write_unique_ptr(out, ident),
+            ImplKey::Own(ident) => write_kj_own(out, ident),
             ImplKey::SharedPtr(ident) => write_shared_ptr(out, ident),
             ImplKey::WeakPtr(ident) => write_weak_ptr(out, ident),
             ImplKey::CxxVector(ident) => write_cxx_vector(out, ident),
@@ -1615,6 +1643,34 @@ fn write_rust_vec_impl(out: &mut OutFile, key: NamedImplKey) {
     writeln!(out, "}}");
 }
 
+// Writes static assertion that we do not use an Own with a static disposer
+fn write_kj_own(out: &mut OutFile, key: NamedImplKey) {
+    let ident = key.rust;
+    let resolve = out.types.resolve(ident);
+    let inner = resolve.name.to_fully_qualified();
+    let instance = resolve.name.to_symbol();
+
+    out.include.utility = true;
+    out.include.kj_rs = true;
+
+    // Static disposers are not supported, only Owns containing 2 pointers are allowed
+    writeln!(
+        out,
+        "static_assert(sizeof(::kj::Own<{}>) == 2 * sizeof(void *), \"Static disposers for Own are not supported in workerd-cxx\");",
+        inner,
+    );
+    writeln!(
+        out,
+        "static_assert(alignof(::kj::Own<{}>) == sizeof(void *), \"Static disposers for Own are not supported in workerd-cxx\");",
+        inner,
+    );
+    writeln!(
+        out,
+        "static_assert(!::std::is_base_of<::kj::Refcounted, {}>::value, \"Value must not inherit from kj::Refcounted\");",
+        inner
+    );
+}
+
 fn write_unique_ptr(out: &mut OutFile, key: NamedImplKey) {
     let ty = UniquePtr::Ident(key.rust);
     write_unique_ptr_common(out, ty);

kj-rs/lib.rs

@@ -14,9 +14,11 @@ mod awaiter;
 mod future;
 mod promise;
 mod waker;
+mod own;
 
 pub mod repr {
     pub use crate::future::repr::*;
+    pub use crate::own::repr::*;
 }
 
 pub type Result<T> = std::io::Result<T>;

kj-rs/own.c++

@@ -0,0 +1,11 @@
+#include "own.h"
+
+extern "C" {
+// As of right now, this function works and passes all tests, destroying all tested objects correctly.
+// This works because disposers work by virtual call, and the disposer is created during creation of
+// the Own, so the type of the Own at destruction doesn't actually matter for Owns that do not use a
+// static disposer, which are not currently supported by workerd-cxx.
+void cxxbridge$kjrs$own$drop(void *own) {
+  reinterpret_cast<kj::Own<void> *>(own)->~Own();
+}
+}

kj-rs/own.h

@@ -0,0 +1,7 @@
+#pragma once
+
+#include <kj/memory.h>
+
+extern "C" {
+    void cxxbridge$kjrs$own$drop(void* own);
+}

kj-rs/own.rs

@@ -0,0 +1,169 @@
+//! The `workerd-cxx` module containing the [`Own<T>`] type, which is bindings to the `kj::Own<T>` C++ type
+
+use static_assertions::{assert_eq_align, assert_eq_size};
+
+assert_eq_size!(repr::Own<()>, [*const (); 2]);
+assert_eq_align!(repr::Own<()>, *const ());
+
+pub mod repr {
+    use std::ffi::c_void;
+    use std::fmt::{self, Debug, Display};
+    use std::hash::{Hash, Hasher};
+    use std::ops::Deref;
+    use std::ops::DerefMut;
+    use std::pin::Pin;
+    use std::ptr::NonNull;
+
+    /// A [`Own<T>`] represents the `kj::Own<T>`. It is a smart pointer to an opaque C++ type.
+    /// Safety:
+    /// - Passing a null `kj::Own` to rust is considered unsafe from the C++ side,
+    ///   and it is required that this invariant is upheld in C++ code.
+    /// - Currently, it is runtime asserted in the bridge macro that no null Own can be passed
+    ///   to Rust
+    #[repr(C)]
+    pub struct Own<T> {
+        disposer: *const c_void,
+        ptr: NonNull<T>,
+    }
+
+    /// Public-facing Own api
+    impl<T> Own<T> {
+        /// Returns a mutable pinned reference to the object owned by this [`Own`]
+        /// if any, otherwise None.
+        pub fn as_mut(&mut self) -> Pin<&mut T> {
+            // Safety: Passing a null kj::Own to Rust from C++ is not supported.
+            unsafe {
+                let mut_reference = self.ptr.as_mut();
+                Pin::new_unchecked(mut_reference)
+            }
+        }
+
+        /// Returns a mutable pinned reference to the object owned by this
+        /// [`Own`].
+        ///
+        /// ```compile_fail
+        /// let mut own = ffi::cxx_kj_own();
+        /// let pin1 = own.pin_mut();
+        /// let pin2 = own.pin_mut();
+        /// pin1.set_data(12); // Causes a compile fail, because we invalidated the first borrow
+        /// ```
+        ///
+        /// ```compile_fail
+        ///
+        /// let mut own = ffi::cxx_kj_own();
+        /// let pin = own.pin_mut();
+        /// let moved  = own;
+        /// own.set_data(143); // Compile fail, because we tried using a moved object
+        /// ```
+        pub fn pin_mut(&mut self) -> Pin<&mut T> {
+            self.as_mut()
+        }
+
+        /// Returns a raw const pointer to the object owned by this [`Own`]
+        #[must_use]
+        pub fn as_ptr(&self) -> *const T {
+            self.ptr.as_ptr().cast()
+        }
+    }
+
+    impl<T> AsRef<T> for Own<T> {
+        /// Returns a reference to the object owned by this [`Own`] if any,
+        /// otherwise None.
+        fn as_ref(&self) -> &T {
+            // Safety: Passing a null kj::Own to Rust from C++ is not supported.
+            unsafe { self.ptr.as_ref() }
+        }
+    }
+
+    unsafe impl<T> Send for Own<T> where T: Send {}
+
+    unsafe impl<T> Sync for Own<T> where T: Sync {}
+
+    impl<T> Deref for Own<T> {
+        type Target = T;
+
+        fn deref(&self) -> &Self::Target {
+            self.as_ref()
+        }
+    }
+
+    impl<T> DerefMut for Own<T>
+    where
+        T: Unpin,
+    {
+        fn deref_mut(&mut self) -> &mut Self::Target {
+            Pin::into_inner(self.as_mut())
+        }
+    }
+
+    // Own<T> is safe to implement Unpin because moving the Own doesn't move the pointee, and
+    // the drop implentation doesn't depend on the Own's location, because it's handed by virtual dispatch
+    impl<T> Unpin for Own<T> {}
+
+    impl<T> Debug for Own<T> {
+        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+            write!(f, "Own(ptr: {:p}, disposer: {:p})", self.ptr, self.disposer)
+        }
+    }
+
+    impl<T> Display for Own<T>
+    where
+        T: Display,
+    {
+        fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
+            Display::fmt(self.as_ref(), formatter)
+        }
+    }
+
+    impl<T> PartialEq for Own<T>
+    where
+        T: PartialEq,
+    {
+        fn eq(&self, other: &Self) -> bool {
+            self.as_ref() == other.as_ref()
+        }
+    }
+
+    impl<T> Eq for Own<T> where T: Eq {}
+
+    impl<T> PartialOrd for Own<T>
+    where
+        T: PartialOrd,
+    {
+        fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+            PartialOrd::partial_cmp(&self.as_ref(), &other.as_ref())
+        }
+    }
+
+    impl<T> Ord for Own<T>
+    where
+        T: Ord,
+    {
+        fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+            Ord::cmp(&self.as_ref(), &other.as_ref())
+        }
+    }
+
+    impl<T> Hash for Own<T>
+    where
+        T: Hash,
+    {
+        fn hash<H: Hasher>(&self, state: &mut H) {
+            self.as_ref().hash(state);
+        }
+    }
+
+    impl<T> Drop for Own<T> {
+        fn drop(&mut self) {
+            unsafe extern "C" {
+                #[link_name = "cxxbridge$kjrs$own$drop"]
+                fn __drop(this: *mut c_void);
+            }
+
+            let this = std::ptr::from_mut::<Self>(self).cast::<c_void>();
+            unsafe {
+                __drop(this);
+            }
+        }
+    }
+}