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 10 commits into
base: master
Choose a base branch
from
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
16 changes: 15 additions & 1 deletion src/behavior-considered-undefined.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,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
Expand All @@ -97,6 +99,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
Expand Down Expand Up @@ -246,6 +258,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
Expand All @@ -259,5 +272,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
14 changes: 14 additions & 0 deletions src/crates-and-source-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,19 @@ 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 -->

### Uncaught foreign unwinding

r[crate.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].

### The `no_main` attribute

r[crate.no_main]
Expand Down Expand Up @@ -169,6 +182,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
25 changes: 24 additions & 1 deletion src/destructors.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,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 @@ -419,6 +420,8 @@ let x = (&temp()).use_temp(); // ERROR

## Not running destructors

### `forget`

r[destructors.forget]

[`std::mem::forget`] can be used to prevent the destructor of a variable from being run,
Expand All @@ -428,6 +431,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
Expand All @@ -437,11 +456,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 @@ -102,7 +102,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 @@ -118,6 +118,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.

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"`

## Variadic functions

r[items.extern.variadic]
Expand Down Expand Up @@ -439,10 +456,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 @@ -452,11 +468,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
59 changes: 54 additions & 5 deletions src/items/functions.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,13 +254,62 @@ 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.info]
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.

> [!NOTE]
> Prior to Rust 1.82, it is possible for only some of the destructors to execute, and not others.

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
## Const functions

Expand Down
43 changes: 43 additions & 0 deletions src/linkage.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,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 @@ -269,6 +272,46 @@ 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.

### Prohibited linkage and unwinding

r[link.unwinding]
If you are *not* using `rustc` to link Rust files, you must take care to ensure that unwinding is
handled consistently across the entire binary. This includes using `dlopen` or similar facilities
where linking is done by the system runtime without `rustc` being involved.

r[link.unwinding.potential]
A Rust binary or `staticlib` is called *potentially unwinding* if any of the following conditions
Copy link
Member

Choose a reason for hiding this comment

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

Do we have a name for "the final artifact of Rust linkage, with a single Rust runtime included"? Always saying "Rust binary or staticlib" is awkward...

Copy link
Contributor

Choose a reason for hiding this comment

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

I believe this also needs to account for cdylib?

Copy link
Member

Choose a reason for hiding this comment

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

Yeah we really need a proper term for this, not an enumeration. "final Rust artifact"? Or can we say "Rust binary" since staticlib and cdylib are binaries but in some sense rlib is not? Not sure if that makes any sense...

Copy link
Member

Choose a reason for hiding this comment

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

@bjorn3 maybe you have a good idea for what to call this?

Copy link
Member

@bjorn3 bjorn3 Dec 1, 2024

Choose a reason for hiding this comment

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

I don't have a great name for it either unfortunately. bin, dylib, cdylib and proc-macro are all linked crates, but staticlib isn't.

Copy link
Member

Choose a reason for hiding this comment

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

I decided to just directly talk about artifacts and whether they share the same copy of the Rust runtime.

is met:
- The binary or `staticlib` is linked with [the `panic=unwind` runtime][panic-runtime].
- The binary or `staticlib` contains a crate built with `-Cpanic=unwind` that makes a call
to a function using a `-unwind` ABI.
- The binary or `staticlib` makes a `"Rust"` ABI call to code running in a separately built
`staticlib` (i.e., a separate instance of the Rust runtime), and that other `staticlib` is
potentially unwinding.

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

r[link.unwinding.prohibited]
If a Rust binary or `staticlib` is potentially unwinding, then all its crates must be built with `-Cpanic=unwind`.

> [!NOTE]
> This restriction can only be violated when mixing code with different `-C panic` flags
> while also using a non-`rustc` linker. Most users to not have to be concerned about this.

r[link.unwinding.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.

[`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
Loading