Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

panic runtime and C-unwind documentation #1226

Open
wants to merge 37 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
eb818a7
panic runtime and C-unwind documentation
BatmanAoD Oct 2, 2024
f90fca6
Rust version number for destructors guarantee
BatmanAoD Nov 24, 2024
915aa47
Fix identifeirs in functions.md and move the guarantee about destruct…
chorman0773 Nov 25, 2024
2f51185
Add identifier syntax to panic.md
chorman0773 Nov 25, 2024
a2efd56
Move note in linkage.md
chorman0773 Nov 25, 2024
abee069
Fix whitespace issues in previous commit
chorman0773 Nov 25, 2024
5b28a23
Fix omitted whitespace issue (thanks VSC)
chorman0773 Nov 25, 2024
5f78ce8
Update src/items/functions.md
chorman0773 Nov 26, 2024
79db784
fix wording regarding UB due to unwinding linkage
RalfJung Nov 29, 2024
1151023
improve terminology
RalfJung Dec 21, 2024
18d6ec9
Do not document a rustc-lint as a language rule
ehuss Jan 10, 2025
92680b0
Use built-in std linking
ehuss Jan 10, 2025
0bb3b0b
Fix misspelled word
ehuss Jan 10, 2025
2e2f843
Remove vectorcall-unwind, it is unstable
ehuss Jan 14, 2025
17f57cc
Sort unwind list
ehuss Jan 14, 2025
4c55570
Switch link for ABI to the list of ABIs
ehuss Jan 14, 2025
9cfe94d
Tweak wording of "beyond rust main function"
ehuss Jan 14, 2025
c7dbee8
Make sure a terminal rule is used for this definition
ehuss Jan 14, 2025
2d2b9ee
Remove historical note
ehuss Jan 14, 2025
fb2a8d8
Clarify that this is unspecified
ehuss Jan 14, 2025
14b4405
Fix rule name to follow style
ehuss Jan 14, 2025
29df509
Add missing rule name
ehuss Jan 14, 2025
e9a8097
Reword the title of this section
ehuss Jan 14, 2025
6b50173
Unwrap the panic chapter
ehuss Jan 14, 2025
cd4efeb
Update rules to be with headers
ehuss Jan 14, 2025
19dec5f
Apply suggestions from RalfJung
ehuss Jan 14, 2025
4d612a9
Move panic runtimes towards the top of the chapter
ehuss Jan 15, 2025
c655d7d
Add the concept of panic strategy
ehuss Jan 15, 2025
7022fa6
Fix typo
ehuss Jan 15, 2025
e0f870a
Drop sentence about UB of how to violate the Rust runtime
ehuss Jan 15, 2025
b712800
Add "panic" to "unwind runtime"
ehuss Jan 16, 2025
ccb6610
Clarify optimization for abort strategy
ehuss Jan 16, 2025
a78a1c9
Add another link for panic strategy
ehuss Jan 16, 2025
c99233b
Normatively define the abort and unwind runtimes
ehuss Jan 16, 2025
c057f76
Rework link.unwinding
ehuss Jan 16, 2025
db05b96
Apply suggestions from RalfJung
ehuss Jan 17, 2025
e43ab64
Clarify function pointer variadics also support `-unwind`
ehuss Jan 21, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
15 changes: 14 additions & 1 deletion src/behavior-considered-undefined.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
ehuss marked this conversation as resolved.
Show resolved Hide resolved
frame that does not allow unwinding (e.g. by calling a `"C-unwind"` function
imported or transmuted as a `"C"` function or function pointer).
Comment on lines +81 to +82
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there something this can link to that explicitly says what frames don't allow unwinding?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I recall correctly, the intent here was to leave open the possibility of other future mechanisms prohibiting unwinding. It may also be that there's something else I'm not thinking of at the moment that can make unwinding past a frame illegal or undefined. But I believe that currently this example, i.e. a call that uses a non-unwinding ABI, is the only form of frame that doesn't allow unwinding. It would, at least, be appropriate to link to the "c-unwind" page from here, I think.


r[undefined.invalid]
* Producing an [invalid value][invalid-values]. "Producing" a
Expand All @@ -96,6 +98,15 @@ 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. 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
Expand Down Expand Up @@ -245,6 +256,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]: items/external-blocks.md#abi
[undef]: http://llvm.org/docs/LangRef.html#undefined-values
[`target_feature`]: attributes/codegen.md#the-target_feature-attribute
[`UnsafeCell<U>`]: std::cell::UnsafeCell
Expand All @@ -258,5 +270,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
4 changes: 3 additions & 1 deletion src/conditional-compilation.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,14 +304,16 @@ r[cfg.panic]
### `panic`

r[cfg.panic.general]
Key-value option set depending on the panic strategy. Note that more values may be added in the future.
Key-value option set depending on the [panic strategy]. Note that more values may be added in the future.

r[cfg.panic.values]
Example values:

* `"abort"`
* `"unwind"`

[panic strategy]: panic.md#panic-strategy

## Forms of conditional compilation

r[cfg.attr]
Expand Down
14 changes: 13 additions & 1 deletion src/crates-and-source-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) propagates beyond
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`.
Expand Down Expand Up @@ -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
Expand Down
24 changes: 23 additions & 1 deletion src/destructors.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -425,6 +426,8 @@ let x = (&temp()).use_temp(); // ERROR
r[destructors.forget]
## Not running destructors

r[destructors.manually-suppressing]
### Manually suppressing destructors

[`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
Expand All @@ -433,6 +436,21 @@ 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.

r[destructors.process-termination]
### Process termination without unwinding

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
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion src/expressions/array-expr.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Just as with methods, Rust will also insert dereference operations on `a` repeat

Indices are zero-based for arrays and slices.
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.
Expand Down Expand Up @@ -84,5 +84,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
34 changes: 26 additions & 8 deletions src/items/external-blocks.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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:

Expand Down Expand Up @@ -151,6 +156,18 @@ r[items.extern.abi.thiscall]
r[items.extern.abi.efiapi]
* `unsafe extern "efiapi"` -- The ABI used for [UEFI] functions.

r[items.extern.abi.platform-unwind-variants]
Like `"C"` and `"system"`, most platform-specific ABI strings also have a
ehuss marked this conversation as resolved.
Show resolved Hide resolved
[corresponding `-unwind` variant][unwind-behavior]; specifically, these are:

* `"aapcs-unwind"`
* `"cdecl-unwind"`
ehuss marked this conversation as resolved.
Show resolved Hide resolved
* `"fastcall-unwind"`
* `"stdcall-unwind"`
* `"sysv64-unwind"`
* `"thiscall-unwind"`
* `"win64-unwind"`

r[items.extern.variadic]
## Variadic functions

Expand Down Expand Up @@ -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
Expand All @@ -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
57 changes: 51 additions & 6 deletions src/items/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,12 +254,57 @@ let fptr: extern "C" fn() -> i32 = new_i32;
```

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.
### Unwinding

r[items.fn.extern.unwind.intro]
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.

r[items.fn.extern.unwind.behavior]
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] |

r[items.fn.extern.abort]
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. It is unspecified which of those two behaviors will happen.

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

BatmanAoD marked this conversation as resolved.
Show resolved Hide resolved
r[items.fn.const]
## Const functions
Expand Down
46 changes: 46 additions & 0 deletions src/linkage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -268,6 +271,49 @@ binary link:

Passing `rlib`s directly into your foreign linker is currently unsupported.

> [!NOTE]
> Rust code compiled or linked with a different instance of the Rust runtime counts as a
> "foreign code" for the purpose of this section.

r[link.unwinding]
### Prohibited linkage and unwinding

r[link.unwinding.intro]
Panic unwinding can only be used if the binary is built consistently according to the following rules.

ehuss marked this conversation as resolved.
Show resolved Hide resolved
r[link.unwinding.potential]
A Rust artifact is called *potentially unwinding* if any of the following conditions is met:
- The artifact is linked with [the `unwind` panic runtime][panic-runtime].
- The artifact contains a crate built with the `unwind` [panic strategy] that makes a call
to a function using a `-unwind` ABI.
- The artifact makes a `"Rust"` ABI call to code running in another Rust
artifact that has a separate copy of the Rust runtime, and that other artifact is
potentially unwinding.

> [!NOTE]
> This definition captures whether a `"Rust"` ABI call inside a Rust artifact can ever
> unwind.

r[link.unwinding.prohibited]
If a Rust artifact is potentially unwinding, then all its crates must be built with the `unwind` [panic strategy].
ehuss marked this conversation as resolved.
Show resolved Hide resolved
Otherwise, unwinding can cause undefined behavior.

> [!NOTE]
> If you are using `rustc` to link, these rules are enforced automatically.
> If you are *not* using `rustc` to link, you must take care to ensure that unwinding is handled consistently across the entire binary. Linking without `rustc` includes using `dlopen` or similar facilities where linking is done by the system runtime without `rustc` being involved.
ehuss marked this conversation as resolved.
Show resolved Hide resolved
>
> This can only happen when mixing code with different [`-C panic`] flags, so most users do not have to be concerned about this.

> [!NOTE]
> To guarantee that a library will be sound (and linkable with `rustc`)
> regardless of the panic runtime used at link-time, the [`ffi_unwind_calls` lint]
> may be used. The lint flags any calls to `-unwind` foreign functions or
> function pointers.

[`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
[panic strategy]: panic.md#panic-strategy
[`-C panic`]: ../rustc/codegen-options/index.html#panic
Loading
Loading