Skip to content

const-eval: explain the final-value-byte-provenance restriction#2138

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.

Sign up for GitHub

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

Open
RalfJung wants to merge 6 commits into
base:master
Choose a base branch
from
Open

const-eval: explain the final-value-byte-provenance restriction #2138

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2bb92c2
const-eval: explain the final-value-byte-provenance restriction
RalfJung Jan 19, 2026
c461766
Revise text on initializer provenance restriction
traviscross Jan 20, 2026
af42b06
Describe pointer fragment restriction in const final values
traviscross Jan 20, 2026
716afec
Add note explaining whole-pointer order requirement
traviscross Jan 27, 2026
8fd2d3e
Add example of reversed pointer bytes being rejected
traviscross Jan 27, 2026
57f4708
Add normative mention about ordering pointer bytes
traviscross Jan 27, 2026
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
90 changes: 90 additions & 0 deletions src/const_eval.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -232,6 +232,94 @@ r[const-eval.const-expr.loop]
r[const-eval.const-expr.if-match]
* [if] and [match] expressions.

## Const initializers

r[const-eval.const-expr.final-value-provenance]
The representation of the final value of a [constant][constant initializer] or [static initializer] must only contain bytes with provenance in whole-pointer groups. If a byte has provenance but is not part of an adjacent group of correctly-ordered bytes that form an entire pointer, compilation will fail.

@tshepangtshepangFeb 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Does final value mean more than coercions? Should we use that term if so, or should we create a glossary entry maybe?

@RalfJungRalfJungFeb 6, 2026•
edited
Loading

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

@tshepang I don't understand the question. What does any of this have to do with coercions?

This is about the value computed by the const initializer expression, as opposed to some arbitrary value that occurs in the middle of computing said expression.

@tshepangtshepangFeb 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Sorry for lacking clarity, was thinking final value is a technical term, guessing it could mean a value one gets after coercions, me lacking proper vocabulary/understanding.

Would it be good to have final value be a glossary entry, or should we use different terminology... because framing things like that maybe goes too much into the implementation details. Maybe that's ok, like these are details that can't be omitted. Thing is it was not clear to me why call it final, and I don't know what happens before final.

@theemathastheemathasFeb 6, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Maybe this is about cases where a const item's path is used in an array repeat expression, and the const item needs to be coerced in some way before using it as the array, like in rust-lang/rust#143671 and rust-lang/rust#140123? I don't see how that could possibly matter though.

@RalfJungRalfJungFeb 9, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

If anything the term here is "(final) value of a (const or static) initializer". There's no general concept of "final value".

@tshepangtshepangApr 15, 2026•
edited by rustbot
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

adding an explanation

Suggested change
The representation of the final value of a [constant][constant initializer] or [static initializer] must only contain bytes with provenance in whole-pointer groups. If a byte has provenance but is not part of an adjacent group of correctly-ordered bytes that form an entire pointer, compilation will fail.
The representation of the final value of a [constant][constant initializer] or [static initializer] must only contain bytes with provenance in whole-pointer groups. If a byte has provenance but is not part of an adjacent group of correctly-ordered bytes that form an entire pointer, compilation will fail.
> [!NOTE]
> The _final_ here indicates that the value is computed by the initializer expression, to make it clear that it's not some arbitrary value that occurs in the middle of computing said expression.

View changes since the review


```rust,compile_fail
# use core::mem::MaybeUninit;
#
#[repr(C, align(32))]
struct Pair {
x: u128, // Offset 0, 16 bytes.
y: MaybeUninit<u64>, // Offset 16, 8 bytes.
// Offset 24, 8 bytes of padding.
}

const _: Pair = unsafe {
// ^^^^^^^ ERROR: Partial pointer in final value of constant.
let mut m = MaybeUninit::<Pair>::uninit();
// Store pointer that extends halfway into trailing padding.
m.as_mut_ptr().byte_add(20).cast::<&u8>().write_unaligned(&0);
// Initialize fields.
(*m.as_mut_ptr()).x = 0;
(*m.as_mut_ptr()).y = MaybeUninit::new(0);
// Now `m` contains a pointer fragment in the padding.

@RalfJungRalfJungFeb 6, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

Do you think it would be useful to add some ASCII art to explain what happens?

 +-------------------------------------------------+-------------------------+-------------------------------+
Field | x (offsets 0..16) | y (offsets 16..24) | <padding> (offsets 24..32) |
+-------------------------------------------------+-------------------------+-------------------------------+
Data | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | 00 00 00 00 00 00 00 00 | <byte 4..8 of &0> UU UU UU UU |
+-------------------------------------------------+-------------------------+-------------------------------+

Also, why is the x field even part of this example? It seems entirely unnecessary.

m.assume_init()
};
```

> [!NOTE]
> The bytes with provenance must form a complete pointer in the correct order. In the example above, the pointer is written at offset 20, but a pointer requires 8 bytes (assuming an 8-byte pointer). Four of those bytes fit in the `y` field; the rest extend into the padding at offset 24. When the fields are initialized, the `y` bytes get overwritten, leaving only a partial pointer (4 bytes) in the padding. These 4 bytes have provenance but don't form a complete pointer, causing compilation to fail.

@RalfJungRalfJungFeb 6, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

Suggested change
> The bytes with provenance must form a complete pointer in the correct order. In the example above, the pointer is written at offset 20, but a pointer requires 8 bytes (assuming an 8-byte pointer). Four of those bytes fit in the `y` field; the rest extend into the padding at offset 24. When the fields are initialized, the `y` bytes get overwritten, leaving only a partial pointer (4 bytes) in the padding. These 4 bytes have provenance but don't form a complete pointer, causing compilation to fail.
> The bytes with provenance must form a complete pointer in the correct order. In the example above, the pointer is written at offset 20, but a pointer requires 8 bytes (assuming a 64-bit target). Four of those bytes fit in the `y` field; the rest extend into the padding at offset 24. When the fields are initialized, the `y` bytes get overwritten, leaving only a partial pointer (4 bytes) in the padding. These 4 bytes have provenance but don't form a complete pointer, causing compilation to fail.

"a pointer requires 8 bytes (assuming an 8-byte pointer)" sounds too much like an obvious tautology.

>
> This restriction ensures that any bytes with provenance in the final value represent complete pointers. Binary formats such as ELF cannot represent pointer fragments, so the compiler cannot emit them in the final binary.
>
> Reversing the order of the pointer bytes also causes compilation to fail, even though all bytes are present:
>
> ```rust,compile_fail
> # use core::mem::{self, MaybeUninit};
> const PTR_WIDTH: usize = mem::size_of::<*const u8>();
> const _: MaybeUninit<u64> = unsafe {
> // ^^^^^^^^^^^^^^^^
> // ERROR: Partial pointer in final value of constant.
> let mut m = MaybeUninit::<u64>::uninit();
> let ptr: *const u8 = &0;
> let ptr_bytes = &raw const ptr as *const MaybeUninit<u8>;
> // Write pointer bytes in reverse order.
> let dst: *mut MaybeUninit<u8> = m.as_mut_ptr().cast();
> let mut i = 0;
> while i < PTR_WIDTH {
> dst.add(i).write(ptr_bytes.add(PTR_WIDTH - 1 - i).read());
> i += 1;
> }
> m
> };
> ```

> [!NOTE]
> If a byte in the representation of the final value is uninitialized, then it *may* end up having provenance, which can cause compilation to fail. `rustc` tries (but does not guarantee) to only actually fail if the initializer copies or overwrites parts of a pointer and those bytes appear in the final value.
>
> E.g., `rustc` currently accepts this, even though the padding bytes are uninitialized:
>
> ```rust
> #[repr(C, align(32))]
> struct Pair { x: u128, y: u64 }
> // The padding bytes are uninitialized.
> const _: Pair = Pair { x: 0, y: 0 }; // OK.
> ```
>
> Constant evaluation makes the details of typed copies observable: depending on whether a copy is performed field-by-field or as a memory-block copy, provenance in padding bytes might be discarded or preserved (both in the source and in the destination). The language allows the compiler to reject any final initializer value with an uninitialized padding byte to preserve implementation flexibility (e.g., the compiler may in the future always set padding bytes to uninitialized).
>
> Manually initializing (e.g., zeroing) the padding bytes ensures the final value is accepted:
>
> ```rust
> # use std::mem::MaybeUninit;
> # #[repr(C, align(32))]
> # struct Pair { x: u128, y: u64 }
> const _: Pair = unsafe { // OK.
> let mut m = Pair { x: 0, y: 0 };
> # // Trigger failure if padding were not zeroed.
> # let ptr: *const u8 = &0;
> # let ptr_bytes = &raw const ptr as *const MaybeUninit<u8>;
> # let dst: *mut MaybeUninit<u8> = (&raw mut m).byte_add(31).cast();
> # dst.write(ptr_bytes.read());
> // Explicitly zero the padding.
> (&raw mut m).byte_add(24).cast::<u64>().write_unaligned(0);
> m

@RalfJungRalfJungFeb 6, 2026

Copy link
Copy Markdown
MemberAuthor

Choose a reason for hiding this comment

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

Technically speaking, the use of m here at the end incurs a typed copy which resets the padding back to "uninit".

With the hidden code, this example turns more into "how can I launder an arbitrary Pair value I got from somewhere to ensure it doesn't have nonsense it its padding", but that's not what the user sees in these docs.

Also, the more I think about it the more it makes me really uneasy that we'd recommend people write horrible code like this instead of the simple safe initializer above. There's no way I can imagine that initializer to actually cause a problem. You have to do "weird" things like reading/overwriting a part of a pointer value or doing a typed copy where the source memory has pointer bytes in places that the type doesn't store a pointer. It's non-trivial to fully precisely define this list, but even a vague and somewhat hand-wavy definition I think is better than people reading this and going "uh so should I use this MaybeUninit construction instead of normal safe Rust?".

> };
> ```

r[const-eval.const-context]
## Const context
[const context]: #const-context
Expand DownExpand Up@@ -307,6 +395,7 @@ The types of a const function's parameters and return type are restricted to tho
[const generic argument]: items/generics.md#const-generics
[const generic parameters]: items/generics.md#const-generics
[constant expressions]: #constant-expressions
[constant initializer]: items.const
[constants]: items/constant-items.md
[Const parameters]: items/generics.md
[dereference expression]: expr.deref
Expand DownExpand Up@@ -336,6 +425,7 @@ The types of a const function's parameters and return type are restricted to tho
[promoted]: destructors.md#constant-promotion
[range expressions]: expressions/range-expr.md
[slice]: types/slice.md
[static initializer]: items.static.init
[statics]: items/static-items.md
[Struct expressions]: expressions/struct-expr.md
[temporary lifetime extension]: destructors.scope.lifetime-extension
Expand Down