panic runtime and C-unwind documentation

Author: BatmanAoD

src/SUMMARY.md

@@ -114,6 +114,8 @@
     - [Memory allocation and lifetime](memory-allocation-and-lifetime.md)
     - [Variables](variables.md)
 
+- [Panic](panic.md)
+
 - [Linkage](linkage.md)
 
 - [Inline assembly](inline-assembly.md)

src/behavior-considered-undefined.md

@@ -77,7 +77,9 @@ r[undefined.target-feature]
   does not support (see [`target_feature`]), *except* if the platform explicitly documents this to be safe.
 
 r[undefined.call]
-* Calling a function with the wrong call ABI or unwinding from a function with the wrong unwind ABI.
+* Calling a function with the wrong [call ABI][abi], or unwinding past a stack
+  frame that does not allow unwinding (e.g. by calling a `"C-unwind"` function
+  imported or transmuted as a `"C"` function or function pointer).
 
 r[undefined.invalid]
 * Producing an [invalid value][invalid-values]. "Producing" a
@@ -96,6 +98,16 @@ r[undefined.const-transmute-ptr2int]
   'Reinterpreting' refers to loading the pointer value at integer type without a
   cast, e.g. by doing raw pointer casts or using a union.
 
+r[undefined.runtime]
+* Violating assumptions of the Rust runtime. This is only possible using
+  mechanisms outside Rust. Most assumptions of the Rust runtime are currently
+  not explicitly documented.
+  * For assumptions specifically related to unwinding, see the [panic
+    documentation][unwinding-ffi].
+  * The runtime assumes that a Rust stack frame is not deallocated without
+    executing destructors for local variables owned by the stack frame. This assumption
+    can be violated by C functions like `longjmp`.
+
 > **Note**: Undefined behavior affects the entire program. For example, calling
 > a function in C that exhibits undefined behavior of C means your entire
 > program contains undefined behaviour that can also affect the Rust code. And
@@ -245,6 +257,7 @@ reading uninitialized memory is permitted are inside `union`s and in "padding"
 [`const`]: items/constant-items.md
 [noalias]: http://llvm.org/docs/LangRef.html#noalias
 [pointer aliasing rules]: http://llvm.org/docs/LangRef.html#pointer-aliasing-rules
+[abi]: abi.md
 [undef]: http://llvm.org/docs/LangRef.html#undefined-values
 [`target_feature`]: attributes/codegen.md#the-target_feature-attribute
 [`UnsafeCell<U>`]: std::cell::UnsafeCell
@@ -258,5 +271,6 @@ reading uninitialized memory is permitted are inside `union`s and in "padding"
 [project-field]: expressions/field-expr.md
 [project-tuple]: expressions/tuple-expr.md#tuple-indexing-expressions
 [project-slice]: expressions/array-expr.md#array-and-slice-indexing-expressions
+[unwinding-ffi]: panic.md#unwinding-across-ffi-boundaries
 [const-promoted]: destructors.md#constant-promotion
 [lifetime-extended]: destructors.md#temporary-lifetime-extension

src/crates-and-source-files.md

@@ -122,10 +122,21 @@ use foo::bar as main;
 <!-- If the previous section needs updating (from "must take no arguments"
   onwards, also update it in the testing.md file -->
 
+r[crate.uncaught-foreign-unwinding]
+### Uncaught foreign unwinding
+
+When a "foreign" unwind (e.g. an exception thrown from C++ code, or a `panic!`
+in Rust code compiled or linked with a different runtime) is not caught before
+reaching the `main` function, the process will be safely terminated. This may
+take the form of an abort, in which case it is not guaranteed that any `Drop`
+calls will be executed, and the error output may be less informative than if the
+runtime had been terminated by a "native" Rust `panic`.
+
+For more information, see the [panic documentation][panic-docs].
+
 r[crate.no_main]
 ### The `no_main` attribute
 
-
 The *`no_main` [attribute]* may be applied at the crate level to disable
 emitting the `main` symbol for an executable binary. This is useful when some
 other object being linked to defines `main`.
@@ -166,6 +177,7 @@ or `_` (U+005F) characters.
 [function]: items/functions.md
 [module]: items/modules.md
 [module path]: paths.md
+[panic-docs]: panic.md#unwinding-across-ffi-boundaries
 [shebang]: input-format.md#shebang-removal
 [trait or lifetime bounds]: trait-bounds.md
 [where clauses]: items/generics.md#where-clauses

src/destructors.md

@@ -274,7 +274,8 @@ Temporaries are also created to hold the result of operands to an expression
 while the other operands are evaluated. The temporaries are associated to the
 scope of the expression with that operand. Since the temporaries are moved from
 once the expression is evaluated, dropping them has no effect unless one of the
-operands to an expression breaks out of the expression, returns, or panics.
+operands to an expression breaks out of the expression, returns, or
+[panics][panic].
 
 ```rust
 # struct PrintOnDrop(&'static str);
@@ -425,6 +426,7 @@ let x = (&temp()).use_temp();  // ERROR
 r[destructors.forget]
 ## Not running destructors
 
+### `forget`
 
 [`std::mem::forget`] can be used to prevent the destructor of a variable from being run,
 and [`std::mem::ManuallyDrop`] provides a wrapper to prevent a
@@ -433,6 +435,22 @@ variable or field from being dropped automatically.
 > Note: Preventing a destructor from being run via [`std::mem::forget`] or other means is safe even if it has a type that isn't `'static`.
 > Besides the places where destructors are guaranteed to run as defined by this document, types may *not* safely rely on a destructor being run for soundness.
 
+### Process termination without unwinding
+
+r[destructors.process-termination]
+
+There are some ways to terminate the process without [unwinding], in which case
+destructors will not be run.
+
+The standard library provides [`std::process::exit`] and
+[`std::process::abort`] to do this explicitly. Additionally, if the
+[panic-mode] is set to `abort`, panicking will always terminate the process
+without destructors being run.
+
+There is one additional case to be aware of: when a panic reaches a
+[non-unwinding ABI boundary], either no destructors will run, or all
+destructors up until the ABI boundary will run.
+
 [Assignment]: expressions/operator-expr.md#assignment-expressions
 [binding modes]: patterns.md#binding-modes
 [closure]: types/closure.md
@@ -442,11 +460,15 @@ variable or field from being dropped automatically.
 [initialized]: glossary.md#initialized
 [interior mutability]: interior-mutability.md
 [lazy boolean expression]: expressions/operator-expr.md#lazy-boolean-operators
+[non-unwinding ABI boundary]: items/functions.md#unwinding
+[panic]: panic.md
+[panic-mode]: panic.md#panic-runtimes
 [place context]: expressions.md#place-expressions-and-value-expressions
 [promoted]: destructors.md#constant-promotion
 [scrutinee]: glossary.md#scrutinee
 [statement]: statements.md
 [temporary]: expressions.md#temporaries
+[unwinding]: panic.md#unwinding
 [variable]: variables.md
 
 [array]: types/array.md

src/expressions/array-expr.md

@@ -83,7 +83,7 @@ Indices are zero-based for arrays and slices.
 
 r[expr.array.index.const]
 Array access is a [constant expression], so bounds can be checked at compile-time with a constant index value.
-Otherwise a check will be performed at run-time that will put the thread in a _panicked state_ if it fails.
+Otherwise a check will be performed at run-time that will put the thread in a [_panicked state_][panic] if it fails.
 
 ```rust,should_panic
 // lint is deny by default.
@@ -115,5 +115,6 @@ The array index expression can be implemented for types other than arrays and sl
 [constant item]: ../items/constant-items.md
 [literal]: ../tokens.md#literals
 [memory location]: ../expressions.md#place-expressions-and-value-expressions
+[panic]: ../panic.md
 [path]: path-expr.md
 [slice]: ../types/slice.md

src/items/external-blocks.md

@@ -106,7 +106,7 @@ unsafe extern "stdcall" { }
 ```
 
 r[items.extern.abi.standard]
-There are three ABI strings which are cross-platform, and which all compilers
+There are five ABI strings which are cross-platform, and which all compilers
 are guaranteed to support:
 
 r[items.extern.abi.rust]
@@ -122,6 +122,11 @@ r[items.extern.abi.system]
   which case it's `"stdcall"`, or what you should use to link to the Windows
   API itself
 
+r[items.extern.abi.unwind]
+* `extern "C-unwind"` and `extern "system-unwind"` -- identical to `"C"` and
+  `"system"`, respectively, but with [different behavior][unwind-behavior] when
+  the callee unwinds (by panicking or throwing a C++ style exception).
+
 r[items.extern.abi.platform]
 There are also some platform-specific ABI strings:
 
@@ -151,6 +156,18 @@ r[items.extern.abi.thiscall]
 r[items.extern.abi.efiapi]
 * `unsafe extern "efiapi"` -- The ABI used for [UEFI] functions.
 
+Like `"C"` and `"system"`, most platform-specific ABI strings also have a
+[corresponding `-unwind` variant][unwind-behavior]; specifically, these are:
+
+* `"cdecl-unwind"`
+* `"stdcall-unwind"`
+* `"fastcall-unwind"`
+* `"vectorcall-unwind"`
+* `"thiscall-unwind"`
+* `"aapcs-unwind"`
+* `"win64-unwind"`
+* `"sysv64-unwind"`
+
 r[items.extern.variadic]
 ## Variadic functions
 
@@ -428,10 +445,9 @@ Attributes on extern function parameters follow the same rules and
 restrictions as [regular function parameters].
 
 [IDENTIFIER]: ../identifiers.md
+[PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
 [UEFI]: https://uefi.org/specifications
 [WebAssembly module]: https://webassembly.github.io/spec/core/syntax/modules.html
-[functions]: functions.md
-[statics]: static-items.md
 [_Abi_]: functions.md
 [_Function_]: functions.md
 [_InnerAttribute_]: ../attributes.md
@@ -441,11 +457,13 @@ restrictions as [regular function parameters].
 [_OuterAttribute_]: ../attributes.md
 [_StaticItem_]: static-items.md
 [_Visibility_]: ../visibility-and-privacy.md
-[attributes]: ../attributes.md
-[regular function parameters]: functions.md#attributes-on-function-parameters
 [`bundle` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-bundle
-[`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive
-[`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
 [`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib
-[PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
+[`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
+[`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive
+[attributes]: ../attributes.md
+[functions]: functions.md
+[regular function parameters]: functions.md#attributes-on-function-parameters
+[statics]: static-items.md
+[unwind-behavior]: functions.md#unwinding
 [value namespace]: ../names/namespaces.md

src/items/functions.md

@@ -253,13 +253,58 @@ extern "C" fn new_i32() -> i32 { 0 }
 let fptr: extern "C" fn() -> i32 = new_i32;
 ```
 
+### Unwinding
+
 r[items.fn.extern.unwind]
-Functions with an ABI that differs from `"Rust"` do not support unwinding in the
-exact same way that Rust does. Therefore, unwinding past the end of functions
-with such ABIs causes the process to abort.
 
-> **Note**: The LLVM backend of the `rustc` implementation
-aborts the process by executing an illegal instruction.
+r[items.fn.extern.unwind.into]
+Most ABI strings come in two variants, one with an `-unwind` suffix and one without.
+The `Rust` ABI always permits unwinding, so there is no `Rust-unwind` ABI. The
+choice of ABI, together with the runtime [panic mode][panic-modes], determines
+the behavior when unwinding out of a function.
+
+The table below indicates the behavior of an unwinding operation reaching each
+type of ABI boundary (function declaration or definition using the
+corresponding ABI string). Note that the Rust runtime is not affected by, and
+cannot have an effect on, any unwinding that occurs entirely within another
+language's runtime, that is, unwinds that are thrown and caught without
+reaching a Rust ABI boundary.
+
+The `panic`-unwind column refers to [panicking] via the `panic!` macro and
+similar standard library mechanisms, as well as to any other Rust operations
+that cause a panic, such as out-of-bounds array indexing or integer overflow.
+
+The "unwinding" ABI category refers to `"Rust"` (the implicit ABI of Rust
+functions not marked `extern`), `"C-unwind"`, and any other ABI with `-unwind`
+in its name. The "non-unwinding" ABI category refers to all other ABI strings,
+including `"C"` and `"stdcall"`.
+
+Native unwinding is defined per-target. On targets that support throwing and
+catching C++ exceptions, it refers to the mechanism used to implement this
+feature. Some platforms implement a form of unwinding referred to as ["forced
+unwinding"][forced-unwinding]; `longjmp` on Windows and `pthread_exit` in
+`glibc` are implemented this way. Forced unwinding is explicitly excluded
+from the "Native unwind" column in the table.
+
+| panic runtime  | ABI           | `panic`-unwind                        | Native unwind (unforced) |
+| -------------- | ------------  | ------------------------------------- | -----------------------  |
+| `panic=unwind` | unwinding     | unwind                                | unwind                   |
+| `panic=unwind` | non-unwinding | abort (see notes below)               | [undefined behavior]     |
+| `panic=abort`  | unwinding     | `panic` aborts without unwinding      | abort                    |
+| `panic=abort`  | non-unwinding | `panic` aborts without unwinding      | [undefined behavior]     |
+
+> **Note**: With `panic=unwind`, when a `panic` is turned into an abort by a
+> non-unwinding ABI boundary, either no destructors (`Drop` calls) will run, or
+> all destructors up until the ABI boundary will run.
+
+For other considerations and limitations regarding unwinding across FFI
+boundaries, see the [relevant section in the Panic documentation][panic-ffi].
+
+[forced-unwinding]: https://rust-lang.github.io/rfcs/2945-c-unwind-abi.html#forced-unwinding
+[panic-modes]: ../panic.md#panic-runtimes
+[panic-ffi]: ../panic.md#unwinding-across-ffi-boundaries
+[panicking]: ../panic.md
+[undefined behavior]: ../behavior-considered-undefined.md
 
 r[items.fn.const]
 ## Const functions

src/linkage.md

@@ -253,6 +253,9 @@ RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-pc-windows
 
 ## Mixed Rust and foreign codebases
 
+r[link.foreign-code]
+
+r[link.foreign-code.foreign-linkers]
 If you are mixing Rust with foreign code (e.g. C, C++) and wish to make a single
 binary containing both types of code, you have two approaches for the final
 binary link:
@@ -268,6 +271,42 @@ binary link:
 
 Passing `rlib`s directly into your foreign linker is currently unsupported.
 
+### Prohibited linkage and foreign unwinding
+
+r[link.foreign-code.prohibited]
+
+Undfined behavior may be caused by foreign code unwinding into a Rust crate
+with these characteristics:
+
+* The foreign unwind enters Rust via a function or function pointer declared
+  with an ABI that permits unwinding, that is, `"Rust"` (the default ABI) or
+  any `-unwind` ABI
+* The Rust crate containing the `-unwind` ABI declaration was compiled with
+  `panic=unwind`
+* The final binary is linked with [the `panic=abort` runtime][panic-runtime]
+
+> **Note**: To protect against this undefined behavior, `rustc` does not permit
+> linking the `panic=abort` runtime against any crate that was compiled with
+> `panic=unwind` if that crate also contains a call to a foreign function or
+> function pointer declared with an `-unwind` ABI. Note that this prohibition
+> applies even when linking a static or dynamic library that only includes Rust
+> code, since the resulting library may be subsequently linked against another
+> library that may unwind. However, use of the `Rust` (default) ABI does not
+> cause a link-error, since that ABI is not expected to be used as an
+> entrypoint into a static or shared library.
+
+r[link.foreign-code.prohibited.lint.ffi_unwind_calls]
+To guarantee that a library will be sound (and linkable with `rustc`)
+regardless of the panic mode used at link-time, the [`ffi_unwind_calls` lint]
+may be used. The lint flags any calls to `-unwind` foreign functions or
+function pointers.
+
+> **Note**: the restriction can only be violated when mixing code with different
+> `-C panic` flags. This is not possible in normal use of cargo, so most users
+> need not be concerned about this.
+
 [`cfg` attribute `target_feature` option]: conditional-compilation.md#target_feature
+[`ffi_unwind_calls` lint]: ../rustc/lints/listing/allowed-by-default.html#ffi-unwind-calls
 [configuration option]: conditional-compilation.md
+[panic-runtime]: panic.md#panic-runtimes
 [procedural macros]: procedural-macros.md