Skip to content

Mention -unwind ABI variants #3729

Closed

Description

@BatmanAoD

As of Rust 1.71, every ABI except for Rust comes in two variants, an -unwind version and the original non-unwind version. This isn't something the book should cover in detail, but it seems reasonable to mention briefly.

The most appropriate place is probably Chapter 19, towards the end of "Using extern Functions to Call External Code". I'm not entirely sure whether it deserves a full paragraph or even its own inset, but here's some draft verbiage:

There are also ABI strings with -unwind, such as "C-unwind". The "unwind" in these strings refers to panic in Rust and to exceptions in C++. It is usually correct to use the standard, non-unwind version of an ABI string, which will cause the program to immediately exit with an error rather than letting a Rust panic or C++ exception "escape" from one language runtime to the other. Unwinding across language boundaries is hazardous and generally not a good way to expose errors in a cross-language API. If you do need to unwind across an FFI boundary, refer to the Reference or the Nomicon to learn how to do so safely.

If that's too much detail/information, it could be further shortened to:

There are also ABI strings with -unwind, such as "C-unwind". It is usually correct to use the standard, non-unwind version of an ABI string, but if you do need to unwind across an FFI boundary, refer to the Reference or the Nomicon to learn how to do so safely.

Activity

  1. added this to the ch19 milestone on Mar 29, 2024
  2. chriskrycho commented on Dec 16, 2024

    @chriskrycho
    Contributor

    Thanks for flagging this up. I think given the growing set of variants here, our best move is probably a single sentence saying something like “For information about all available ABIs, see The Reference.” (We could otherwise end up multiplying which ABIs we name indefinitely, and/or get an unceasing stream of “Why isn’t [my favorite ABI] mentioned?” I’ll open a PR with that simple tweak.

  3. modified the milestones: ch19, ch20 on Dec 16, 2024
  4. chriskrycho commented on Dec 16, 2024

    @chriskrycho
    Contributor

    Oooof, what a huge effort to figure out juuuuust how to get this documented in the Reference! I’m going to open a PR momentarily, but mark is as blocked on landing rust-lang/reference#1226.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions