Document (lack of) support for C++ exceptions

[mcgoo]

I couldn't find any reference to C++ exceptions in the docs. I assume this is because they are out of scope for bindgen? Am I right in assuming that any function that could emit an exception is unsafe to call directly from Rust code?

Relatedly, there seem to be a number of C++-specific pain points that could be reduced if bindgen could emit a C++ wrapper also. Ensuring the existence of out-of-line copies of inline functions, translating an exception to a Result<>, and instantiating templates, for example. Clearly doing so would add complexity to the build. Is that something that has been considered?

[emilio]

Am I right in assuming that any function that could emit an exception is unsafe to call directly from Rust code?

Yes, in the same way that panicking from a function called by FFI is unsafe.

Clearly doing so would add complexity to the build. Is that something that has been considered?

Not really, so far the C++ projects I've used bindgen on all disable exceptions. I thought exceptions were actually pretty marginal actually :).

If there's a use case yeah, handling it sounds reasonable, as long as there's a way to avoid the runtime overhead and such

[Ekleog]

In order to support exceptions, something like emitting a c++ wrapper that looks like this should work (and remove the need for handling compiler-specific mangling in bindgen, making it maybe more resilient to changes in the compilers) (syntax untested) :

extern "C"
result_original_type bindgen_mangled_function(arg_type arg) {
    try {
        return result_original_type_ok(original_cpp_function(arg));
    } catch (exception e) {
        return result_original_type_err(e.message());
    } catch (...) {
        return result_original_type_err("Unknown exception raised");
    }
}

This should have no runtime slowdown (c++ exceptions work completely out-of-path) for non-exception-raising paths apart from a single function call (and the wrapping the result in an Ok()-like structure).

Anyway, if exceptions could be added to “Unsupported Features” in https://rust-lang-nursery.github.io/rust-bindgen/cpp.html (maybe with a link to this issue) I think this would be great!

[fitzgen]

Anyway, if exceptions could be added to “Unsupported Features” in https://rust-lang-nursery.github.io/rust-bindgen/cpp.html (maybe with a link to this issue) I think this would be great!

I would be happy to r+ such a pull request :)

[fitzgen]

See #1208 for tracking implementation of trampoline helpers that catch exceptions.

Will leave this open for documenting exception support (or lack thereof).