Update exception handling to use std::exception_ptr

This makes the interface between C++ exception handling and Rust
`Result` cleaner and allows passing C++ exception from the inner C++
call to the outer C++ call via Rust's `CxxException` unmodified, i.e.,
without losing information.

To allow custom exception types, trait `ToCxxException` was introduced.
With this trait, it's possible to convert a Rust error to the wrapper
`CxxExeception` via a C++ function, thus allowing throwing other
exceptions as well. This required changing `r#try` function into
macros, so we can properly default to `rust::Error` for errors not
having `ToCxxException` defined.

Background: The `throw` statement in C++ (__cxa_throw) effectively
first allocates space on the heap and creates the exception within,
then starts unwinding. This can be also done via standard C++11 API in
two steps. First, `std::make_exception_ptr()` creates a new
`std::exception_ptr`, which points into this allocated space and
internally is just a pointer (it's a smart pointer much like
`std::shared_ptr`). Then, `std::rethrow_exception()` can be used to
actually throw and/or rethrow this exception.

Basically, the new implementation now uses `std::make_exception_ptr()`
called from Rust to construct an exception for the `Result<_, E>` and
then after returning it back to C++ via `CxxResult` (which is now BTW
smaller, just 8B) the C++ part throws it using
`std::rethrow_exception()`.

Author: schreter

book/src/binding/result.md

@@ -25,7 +25,19 @@ the Rust side produces an error.
 Note that the return type written inside of cxx::bridge must be written without
 a second type parameter. Only the Ok type is specified for the purpose of the
 FFI. The Rust *implementation* (outside of the bridge module) may pick any error
-type as long as it has a std::fmt::Display impl.
+type as long as it has a `std::fmt::Display` or `cxx:ToCxxException`
+implementation.
+
+Exception is built from the actual error type via `cxx::ToCxxException` trait
+which converts the error type into a custom exception by the user code, if such
+an implementation exists, else using `cxx::ToCxxExceptionDefault`, which only
+requires the type to implement `std::fmt::Display` trait. The sole trait method
+of both traits returns a `cxx::CxxException`, which wraps a `std::exception_ptr`
+on the C++ side. An implementation of `cxx::ToCxxException` will call the
+appropriate C++ function (again, via the bridge) to construct the
+`std::exception_ptr`, likely using standard C++ function
+`std::make_exception_ptr()` to wrap an exception. The signature on the C++ side
+expects `std::exception_ptr` for `cxx::CxxException` on the Rust side.
 
 ```rust,noplayground
 # use std::io;
@@ -51,9 +63,10 @@ fn fallible2() -> Result<(), io::Error> {
 }
 ```
 
-The exception that gets thrown by CXX on the C++ side is always of type
-`rust::Error` and has the following C++ public API. The `what()` member function
-gives the error message according to the Rust error's std::fmt::Display impl.
+The exception that gets thrown by CXX on the C++ side is of type `rust::Error`
+(unless otherwise specified by `cxx::ToCxxException` trait for a custom error
+type) and has the following C++ public API. The `what()` member function gives
+the error message according to the Rust error's `std::fmt::Display` implementation.
 
 ```cpp,hidelines
 // rust/cxx.h
@@ -85,6 +98,12 @@ a second type parameter. Only the Ok type is specified for the purpose of the
 FFI. The resulting error type created by CXX when an `extern "C++"` function
 throws will always be of type **[`cxx::Exception`]**.
 
+Note that this exception can be converted to [`cxx::CxxException`] using its
+`Into` trait implementation and returned back to C++ later, as a `Result` with
+error type `CxxException`, providing a transparent bridge from the original C++
+exception thrown in a C++ callback through Rust API back to the C++ code calling
+the Rust API without loss of information.
+
 [`cxx::Exception`]: https://docs.rs/cxx/*/cxx/struct.Exception.html
 
 ```rust,noplayground
@@ -141,6 +160,8 @@ static void trycatch(Try &&func, Fail &&fail) noexcept try {
   func();
 } catch (const std::exception &e) {
   fail(e.what());
+} catch (...) {
+  fail("<no message>");
 }
 #
 # } // namespace behavior

gen/src/builtin.rs

@@ -20,7 +20,7 @@ pub struct Builtins<'a> {
     pub manually_drop: bool,
     pub maybe_uninit: bool,
     pub trycatch: bool,
-    pub ptr_len: bool,
+    pub repr_cxxresult: bool,
     pub repr_fat: bool,
     pub rust_str_new_unchecked: bool,
     pub rust_str_repr: bool,
@@ -138,7 +138,7 @@ pub(super) fn write(out: &mut OutFile) {
     }
 
     if builtin.trycatch {
-        builtin.ptr_len = true;
+        builtin.repr_cxxresult = true;
     }
 
     out.begin_block(Block::Namespace("rust"));
@@ -217,13 +217,21 @@ pub(super) fn write(out: &mut OutFile) {
         writeln!(out, "using Fat = ::std::array<::std::uintptr_t, 2>;");
     }
 
-    if builtin.ptr_len {
+    if builtin.repr_cxxresult {
+        include.exception = true;
         include.cstddef = true;
         out.next_section();
         writeln!(out, "struct PtrLen final {{");
         writeln!(out, "  void *ptr;");
         writeln!(out, "  ::std::size_t len;");
         writeln!(out, "}};");
+        writeln!(out, "struct CxxResult final {{");
+        writeln!(out, "  void *ptr;");
+        writeln!(out, "}};");
+        writeln!(out, "struct Exception final {{");
+        writeln!(out, "  CxxResult exc;");
+        writeln!(out, "  PtrLen msg;");
+        writeln!(out, "}};");
     }
 
     out.end_block(Block::Namespace("repr"));
@@ -258,11 +266,11 @@ pub(super) fn write(out: &mut OutFile) {
         include.string = true;
         out.next_section();
         writeln!(out, "class Fail final {{");
-        writeln!(out, "  ::rust::repr::PtrLen &throw$;");
+        writeln!(out, "  ::rust::repr::Exception &throw$;");
         writeln!(out, "public:");
         writeln!(
             out,
-            "  Fail(::rust::repr::PtrLen &throw$) noexcept : throw$(throw$) {{}}",
+            "  Fail(::rust::repr::Exception &throw$) noexcept : throw$(throw$) {{}}",
         );
         writeln!(out, "  void operator()(char const *) noexcept;");
         writeln!(out, "  void operator()(std::string const &) noexcept;");
@@ -345,20 +353,6 @@ pub(super) fn write(out: &mut OutFile) {
         writeln!(out, "}};");
     }
 
-    if builtin.rust_error {
-        out.next_section();
-        writeln!(out, "template <>");
-        writeln!(out, "class impl<Error> final {{");
-        writeln!(out, "public:");
-        writeln!(out, "  static Error error(repr::PtrLen repr) noexcept {{");
-        writeln!(out, "    Error error;");
-        writeln!(out, "    error.msg = static_cast<char const *>(repr.ptr);");
-        writeln!(out, "    error.len = repr.len;");
-        writeln!(out, "    return error;");
-        writeln!(out, "  }}");
-        writeln!(out, "}};");
-    }
-
     if builtin.destroy {
         out.next_section();
         writeln!(out, "template <typename T>");
@@ -414,6 +408,8 @@ pub(super) fn write(out: &mut OutFile) {
         writeln!(out, "  func();");
         writeln!(out, "}} catch (::std::exception const &e) {{");
         writeln!(out, "  fail(e.what());");
+        writeln!(out, "}} catch (...) {{");
+        writeln!(out, "  fail(\"<no message>\");");
         writeln!(out, "}}");
         out.end_block(Block::Namespace("behavior"));
     }

gen/src/write.rs

@@ -706,8 +706,8 @@ fn write_cxx_function_shim<'a>(out: &mut OutFile<'a>, efn: &'a ExternFn) {
     out.begin_block(Block::ExternC);
     begin_function_definition(out);
     if efn.throws {
-        out.builtin.ptr_len = true;
-        write!(out, "::rust::repr::PtrLen ");
+        out.builtin.repr_cxxresult = true;
+        write!(out, "::rust::repr::Exception ");
     } else {
         write_extern_return_type_space(out, &efn.ret);
     }
@@ -783,9 +783,9 @@ fn write_cxx_function_shim<'a>(out: &mut OutFile<'a>, efn: &'a ExternFn) {
     writeln!(out, ";");
     write!(out, "  ");
     if efn.throws {
-        out.builtin.ptr_len = true;
+        out.builtin.repr_cxxresult = true;
         out.builtin.trycatch = true;
-        writeln!(out, "::rust::repr::PtrLen throw$;");
+        writeln!(out, "::rust::repr::Exception throw$;");
         writeln!(out, "  ::rust::behavior::trycatch(");
         writeln!(out, "      [&] {{");
         write!(out, "        ");
@@ -856,7 +856,8 @@ fn write_cxx_function_shim<'a>(out: &mut OutFile<'a>, efn: &'a ExternFn) {
     }
     writeln!(out, ";");
     if efn.throws {
-        writeln!(out, "        throw$.ptr = nullptr;");
+        writeln!(out, "        throw$.exc.ptr = nullptr;");
+        writeln!(out, "        throw$.msg.ptr = nullptr;");
         writeln!(out, "      }},");
         writeln!(out, "      ::rust::detail::Fail(throw$));");
         writeln!(out, "  return throw$;");
@@ -899,8 +900,8 @@ fn write_rust_function_decl_impl(
 ) {
     out.next_section();
     if sig.throws {
-        out.builtin.ptr_len = true;
-        write!(out, "::rust::repr::PtrLen ");
+        out.builtin.repr_cxxresult = true;
+        write!(out, "::rust::repr::CxxResult ");
     } else {
         write_extern_return_type_space(out, &sig.ret);
     }
@@ -1074,8 +1075,8 @@ fn write_rust_function_shim_impl(
         }
     }
     if sig.throws {
-        out.builtin.ptr_len = true;
-        write!(out, "::rust::repr::PtrLen error$ = ");
+        out.builtin.repr_cxxresult = true;
+        write!(out, "::rust::repr::CxxResult error$ = ");
     }
     write!(out, "{}(", invoke);
     let mut needs_comma = false;
@@ -1124,7 +1125,8 @@ fn write_rust_function_shim_impl(
     if sig.throws {
         out.builtin.rust_error = true;
         writeln!(out, "  if (error$.ptr) {{");
-        writeln!(out, "    throw ::rust::impl<::rust::Error>::error(error$);");
+        writeln!(out, "    void *ppexc = &error$.ptr;");
+        writeln!(out, "    std::rethrow_exception(std::move(*static_cast<std::exception_ptr*>(ppexc)));");
         writeln!(out, "  }}");
     }
     if indirect_return {

macro/src/expand.rs

@@ -146,6 +146,7 @@ fn expand(ffi: Module, doc: Doc, attrs: OtherAttrs, apis: &[Api], types: &Types)
             clippy::ptr_as_ptr,
             clippy::upper_case_acronyms,
             clippy::use_self,
+            clippy::items_after_statements,
         )]
         #vis #mod_token #ident #expanded
     }
@@ -471,7 +472,7 @@ fn expand_cxx_function_decl(efn: &ExternFn, types: &Types) -> TokenStream {
     });
     let all_args = receiver.chain(args);
     let ret = if efn.throws {
-        quote!(-> ::cxx::private::Result)
+        quote!(-> ::cxx::private::CxxResultWithMessage)
     } else {
         expand_extern_return_type(&efn.ret, types, true)
     };
@@ -1108,7 +1109,7 @@ fn expand_rust_function_shim_impl(
             None => quote_spanned!(span=> &mut ()),
         };
         requires_closure = true;
-        expr = quote_spanned!(span=> ::cxx::private::r#try(#out, #expr));
+        expr = quote_spanned!(span=> ::cxx::map_rust_result_to_cxx_result!(#out, #expr));
     } else if indirect_return {
         requires_closure = true;
         expr = quote_spanned!(span=> ::cxx::core::ptr::write(__return, #expr));
@@ -1123,7 +1124,7 @@ fn expand_rust_function_shim_impl(
     expr = quote_spanned!(span=> ::cxx::private::prevent_unwind(__fn, #closure));
 
     let ret = if sig.throws {
-        quote!(-> ::cxx::private::Result)
+        quote!(-> ::cxx::private::CxxResult)
     } else {
         expand_extern_return_type(&sig.ret, types, false)
     };
@@ -1166,16 +1167,12 @@ fn expand_rust_function_shim_super(
     let args = sig.args.iter().map(|arg| quote!(#arg));
     let all_args = receiver.chain(args);
 
-    let ret = if let Some((result, _langle, rangle)) = sig.throws_tokens {
+    let ret = if let Some((result, _langle, _rangle)) = &sig.throws_tokens {
         let ok = match &sig.ret {
             Some(ret) => quote!(#ret),
             None => quote!(()),
         };
-        // Set spans that result in the `Result<...>` written by the user being
-        // highlighted as the cause if their error type has no Display impl.
-        let result_begin = quote_spanned!(result.span=> ::cxx::core::result::Result<#ok, impl);
-        let result_end = quote_spanned!(rangle.span=> ::cxx::core::fmt::Display>);
-        quote!(-> #result_begin #result_end)
+        quote_spanned!(result.span=> -> ::cxx::core::result::Result<#ok, ::cxx::CxxException>)
     } else {
         expand_return_type(&sig.ret)
     };
@@ -1192,9 +1189,23 @@ fn expand_rust_function_shim_super(
         }
     };
 
+    let call = if let Some((result, _langle, rangle)) = &sig.throws_tokens {
+        // Set spans that result in the `Result<...>` written by the user being
+        // highlighted as the cause if their error type is not convertible to
+        // CxxException (i.e., no `Display` trait by default).
+        let result_begin = quote_spanned!{ result.span=>
+            |e| ::cxx::map_rust_error_to_cxx_exception!
+        };
+        let result_end = quote_spanned!{ rangle.span=> (e) };
+        quote_spanned! {span=>
+            #call(#(#vars,)*).map_err( #result_begin #result_end )
+        }
+    } else {
+        quote_spanned! {span=> #call(#(#vars,)*) }
+    };
     quote_spanned! {span=>
         #unsafety fn #local_name #generics(#(#all_args,)*) #ret {
-            #call(#(#vars,)*)
+            #call
         }
     }
 }

src/cxx.cc

@@ -474,10 +474,6 @@ static_assert(alignof(std::exception_ptr) == alignof(void *),
               "Unsupported std::exception_ptr alignment");
 
 extern "C" {
-const char *cxxbridge1$error(const char *ptr, std::size_t len) noexcept {
-  return errorCopy(ptr, len);
-}
-
 void *cxxbridge1$default_exception(const char *ptr, std::size_t len) noexcept {
   // Construct an `std::exception_ptr` for the default `rust::Error` in the
   // space provided by the pointer itself (placement new).
@@ -501,8 +497,9 @@ void *cxxbridge1$clone_exception(const char *ptr) noexcept {
   // Implement the `clone` for `CxxException` on the Rust side, which is just a
   // pointer to the exception stored in `std::exception_ptr`.
   void *eptr;
-  new (&eptr) std::exception_ptr(
-      *reinterpret_cast<const std::exception_ptr *const>(&ptr));
+  const void *pptr = &ptr;
+  new (&eptr)
+      std::exception_ptr(*static_cast<const std::exception_ptr *>(pptr));
   return eptr;
 }
 } // extern "C"
@@ -559,6 +556,13 @@ struct PtrLen final {
   void *ptr;
   std::size_t len;
 };
+struct CxxResult final {
+  void *ptr;
+};
+struct Exception final {
+  CxxResult exc;
+  PtrLen msg;
+};
 } // namespace repr
 
 extern "C" {
@@ -580,20 +584,26 @@ using isize_if_unique =
                               struct isize_ignore, rust::isize>::type;
 
 class Fail final {
-  repr::PtrLen &throw$;
+  repr::Exception &throw$;
 
 public:
-  Fail(repr::PtrLen &throw$) noexcept : throw$(throw$) {}
+  Fail(repr::Exception &throw$) noexcept : throw$(throw$) {}
   void operator()(const char *) noexcept;
   void operator()(const std::string &) noexcept;
 };
 
 void Fail::operator()(const char *catch$) noexcept {
-  throw$ = cxxbridge1$exception(catch$, std::strlen(catch$));
+  void *eptr;
+  new (&eptr)::std::exception_ptr(::std::current_exception());
+  throw$.exc.ptr = eptr;
+  throw$.msg = cxxbridge1$exception(catch$, std::strlen(catch$));
 }
 
 void Fail::operator()(const std::string &catch$) noexcept {
-  throw$ = cxxbridge1$exception(catch$.data(), catch$.length());
+  void *eptr;
+  new (&eptr)::std::exception_ptr(::std::current_exception());
+  throw$.exc.ptr = eptr;
+  throw$.msg = cxxbridge1$exception(catch$.data(), catch$.length());
 }
 } // namespace detail
 

src/exception.rs

@@ -1,12 +1,14 @@
 #![cfg(feature = "alloc")]
 
 use alloc::boxed::Box;
-use core::fmt::{self, Display};
+use core::fmt::{self, Display, Debug};
+
+use crate::CxxException;
 
 /// Exception thrown from an `extern "C++"` function.
 #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]
-#[derive(Debug)]
 pub struct Exception {
+    pub(crate) src: CxxException,
     pub(crate) what: Box<str>,
 }
 
@@ -16,6 +18,12 @@ impl Display for Exception {
     }
 }
 
+impl Debug for Exception {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Exception").field("what", &self.what).finish()
+    }
+}
+
 #[cfg(feature = "std")]
 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))]
 impl std::error::Error for Exception {}